manifest#

The manifest of a cryptomatte is an optional field that encodes a key-value list (implemented as json) mapping the name of the mask to its hash value. For example:

{
    "bunny" : "13851a76",
    "default" : "42c9679f"
}

This manifest serves to give the decoding additional information and to give names to the masks. It should however never be relied on for decoding. This is because the manifest is not required to be encoded and is also in practice quite unreliable to read from across different DCCs.

Internally we only use this to assign names to masks but our decoding happens separate of it.

It is part of the metadata stored as an optional value. Loading the manifest from a file should be done through the metadata rather than doing it directly.

manifest#

c++

struct manifest#

creating a manifest

manifest() = default#

explicit manifest(json_ordered json)#

Load and decode a manifest from a json (this would be the cryptomatte/<hash>/manifest or cryptomatte/<hash>/manif_file).

Parameters:: json – The json to load from.

static manifest from_str(std::string json)#

Load and decode a manifest from a json string (this would be the cryptomatte/<hash>/manifest or cryptomatte/<hash>/manif_file).

Parameters:: json – The json string, must be a valid json.
Returns:: The decoded manifest.

static std::optional<manifest> load(std::string manif_key, std::string manif_value, std::filesystem::path image_path) noexcept#

Load the manifest from the passed image metadata, optionally returning a decoded manifest.

This function scans the metadata for a manifest string or filename, attempts to read and decode the manifest data, and returns it if successful. If a sidecar file is used (very rare), the function will also attempt to load it from disk.

Parameters:

manif_key – The metadata key for the manifest, will be used to determine whether its a sidecar or embedded.
manif_value – The value found on the cryptomattes’ ‘manifest’ or ‘manif_file’ value, we will take care of parsing internally.
image_path – The path to the image that the cryptomatte was loaded from, required to successfully decode sidecar files.

Returns:

A decoded manifest if present and successfully parsed; otherwise, std::nullopt.

retrieving the mapping

std::vector<std::string> names() const noexcept#: Retrieve all the names stored by this manifest as a vector.

template<typename T = uint32_t> inline requires std::is_same_v< T, float32_t > std::is_same_v< T, std::string > std::is_same_v< T, uint32_t > std::vector< T > hashes () const noexcept

Retrieve all the hashes stored by this manifest as a vector.

This returns the values associated with the names in the manifest, transformed into the desired output format specified by the template parameter T. Supported formats include:

uint32_t: The raw internal representation (default).
float32_t: A bit-cast form of the hash, this is what the hashes are stored as in-file.
std::string: A hexadecimal string representation of the hash.

Template Parameters:: T – The type to return the hash values as, defaulting to uint32_t. Must be one of: float32_t, std::string, or uint32_t.
Returns:: A vector containing all hash values, cast to the requested type, in the same order as names().

template<typename T = uint32_t> inline requires std::is_same_v< T, float32_t > std::is_same_v< T, std::string > std::is_same_v< T, uint32_t > std::vector< std::pair< std::string, T > > mapping () const

Retrieve the full name-to-hash mapping, cast to the specified type.

This function provides access to the name-hash mapping in the desired format:

uint32_t: The raw internal representation (default).
float32_t: A bit-cast form of the hash, this is what the hashes are stored as in-file.
std::string: A hexadecimal string representation of the hash.

Template Parameters:: T – The type to return the hash values as, defaulting to uint32_t. Must be one of: float32_t, std::string, or uint32_t.
Returns:: A vector of name-hash pairs in the specified format.

template<typename T = uint32_t> inline requires std::is_same_v< T, float32_t > std::is_same_v< T, std::string > std::is_same_v< T, uint32_t > T hash (std::string_view name) const

Get the hash associated with the given name

Returns it as the specified template parameter which may be float32_t, std::string or uint32_t

Throws:: std::invalid_argument – if the given name does not exist in the manifest. Use contains to check whether the hash exists
Template Parameters:: T – The type to retrieve the cryptomatte hash as, may be float32_t, std::string or uint32_t defaulting to uint32_t
Returns:: The hash at the given name.

Public Functions

bool contains(std::string_view name)#

Check whether the manifest contains the passed name.

Parameters:: name – The name to check for existence within the manifest.
Returns:: True if the name exists in the manifest, false otherwise.

size_t size() const noexcept#: Get the size of the manifest, i.e. how many items are in the mapping.

python

class cryptomatte_api.Manifest#

__init__(self: cryptomatte_api.lib64.cryptomatte_api.Manifest) → None#: Construct an empty Manifest.

contains(self: cryptomatte_api.lib64.cryptomatte_api.Manifest, name: str) → bool#

Check whether the manifest contains the given name.

Parameters:: name – Name to check for existence within the manifest.
Returns:: True if the name exists, False otherwise.

static from_json(json_obj: json) → cryptomatte_api.lib64.cryptomatte_api.Manifest#

Load and decode a manifest from JSON.

Parameters:: json_obj – JSON object containing manifest data.
Returns:: Decoded Manifest instance.

static from_str(str: str) → cryptomatte_api.lib64.cryptomatte_api.Manifest#

Load and decode a manifest from a json string.

Parameters:: str – JSON string containing manifest data.
Returns:: Decoded Manifest instance.

hash_float(self: cryptomatte_api.lib64.cryptomatte_api.Manifest, name: str) → float#

Get the hash associated with the given name as float32.

Parameters:: name – Name whose hash to retrieve.
Returns:: Hash value as float32.
Raises:: ValueError – If the name does not exist in the manifest.

hash_hex(self: cryptomatte_api.lib64.cryptomatte_api.Manifest, name: str) → str#

Get the hash associated with the given name as a hexadecimal string.

Parameters:: name – Name whose hash to retrieve.
Returns:: Hash value as an 8-character hex string.
Raises:: ValueError – If the name does not exist in the manifest.

hash_uint32(self: cryptomatte_api.lib64.cryptomatte_api.Manifest, name: str) → int#

Get the hash associated with the given name as uint32.

Parameters:: name – Name whose hash to retrieve.
Returns:: Hash value as uint32.
Raises:: ValueError – If the name does not exist in the manifest.

hashes_float(self: cryptomatte_api.lib64.cryptomatte_api.Manifest) → list[float]#

Retrieve all hashes stored in the manifest as float32 values.

Returns:: List of hash values as float32 in the same order as names().

hashes_hex(self: cryptomatte_api.lib64.cryptomatte_api.Manifest) → list[str]#

Retrieve all hashes stored in the manifest as hexadecimal strings.

Returns:: List of hash values as 8-character hex strings in the same order as names().

hashes_uint32(self: cryptomatte_api.lib64.cryptomatte_api.Manifest) → list[int]#

Retrieve all hashes stored in the manifest as uint32 values.

Returns:: List of hash values as uint32 in the same order as names().

static load(manif_key: str, manif_value: str, image_path: str) → Optional[cryptomatte_api.lib64.cryptomatte_api.Manifest]#

Load and decode a manifest from a json string.

Parameters:

manif_key – The metadata key for the manifest, will be used to determine whether its a sidecar or embedded.
manif_value – The value found on the cryptomattes’ ‘manifest’ or ‘manif_file’ value, we will take care of parsing internally.
image_path – The path to the image that the cryptomatte was loaded from, required to successfully decode sidecar files.

Returns:

Decoded Manifest instance.

mapping_float(self: cryptomatte_api.lib64.cryptomatte_api.Manifest) → list[tuple[str, float]]#

Retrieve the full name-to-hash mapping as float32 values.

Returns:: List of (name, hash) pairs with hash as float32.

mapping_hex(self: cryptomatte_api.lib64.cryptomatte_api.Manifest) → list[tuple[str, str]]#

Retrieve the full name-to-hash mapping as hexadecimal strings.

Returns:: List of (name, hash) pairs with hash as 8-character hex strings.

mapping_uint32(self: cryptomatte_api.lib64.cryptomatte_api.Manifest) → list[tuple[str, int]]#

Retrieve the full name-to-hash mapping as uint32 values.

Returns:: List of (name, hash) pairs with hash as uint32.

names(self: cryptomatte_api.lib64.cryptomatte_api.Manifest) → list[str]#

Retrieve all names stored in the manifest.

Returns:: List of names in the manifest.

size(self: cryptomatte_api.lib64.cryptomatte_api.Manifest) → int#

Get the size of the manifest (number of items).

Returns:: Number of items in the mapping.