metadata#

Cryptomattes are required to encode metadata about themselves on-disk such as the name of the channels, the type of hashing method used and the data type conversion to get from pixel value -> hash value.

The cmatte::metadata class allows you to transparently access all of this information and gets created automatically on load of a cryptomatte.

It additionally provides some utility functions for checking if a given channel is part of a cryptomatte defined by the metadata. These functions are is_valid_legacy_channel_name and is_valid_channel_name for checking both the legacy channel names and the mask channels.

how metadata is stored#

Cryptomatte metadata is stored as part of the images’ extra attributes and is encoded as follows:

cryptomatte/<key>/name: "crypto_asset"
cryptomatte/<key>/hash: "MurmurHash3_32"
cryptomatte/<key>/conversion: "uint32_to_float32"
cryptomatte/<key>/<manifest/manif_file>: "{'bunny': '3dcaf72e'}"

The first 3 of these attributes are mandatory, and the hash and conversion attributes only have one valid option (the ones shown here).

The manifest on the other hand can either be an embedded json string or a sidecar json file which is stored as a path relative to the image. This maps a human-readable name to its pixel hash, for more visit manifest. The cryptomatte-api handles reading these values for you automatically.

The name attribute in this case refers to the {typename} which tells us what the channel names for this cryptomatte are.

The key is some kind of unique identifier that identifies this cryptomatte within the file. This is needed to separate separate cryptomatte definitions within the same file as there is no limit to how many different cryptomattes can be encoded in a single file. It sometimes is a hash, but could be ‘banana’ or ‘definitely_not_a_cryptomatte’. There is no convention or limitation, it should just be unique within the file.

Note

Often times DCCs will use the same key for the same type of cryptomattes. So if they are encoding e.g. a crypto_asset they may always use the key 3fe9c8 for this.

checking metadata without loading a file#

Sometimes it may be desirable to load the metadatas without loading the whole image to be able to extract only the channel names. To do this. we provide static creation functions which allow you to initialize the metadata from the opened OIIO::ImageInput without having to open the file yourself.

These functions are cmatte::metadata::from_spec, cmatte::metadata::from_param_value_list and cmatte::metadata::from_json.

Note that these give a vector of cmatte::metadata as a single file may hold any number of cryptomattes.

Below you can find an example of retrieving the channelnames from the metadata without having to ever construct a cryptomatte object.

auto input_ptr = ImageInput::open("my_file");
if (!inp)
{
    return;
}

auto metadatas = cmatte::metadata::from_spec(input_ptr->spec());
auto& metadata = metadatas[0];
auto mask_channel_names = metadata.channel_names(input_ptr->spec().channelnames);
auto legacy_channel_names = metadata.legacy_channel_names(input_ptr->spec().channelnames);

metadata#

c++

struct metadata#

creating the metadata struct

metadata() = default#

metadata(std::string name, std::string key, std::string hash, std::string conversion, std::optional<manifest> manif = std::nullopt)#

Construct a cryptomattes’ metadata from the given parameters extracted from the images’ metadata.

Parameters:

name – The name of the cryptomattes, will be used to get the valid channel structure.
key – The key or hash of this unique cryptomatte. As a file may store more than one cryptomatte this uniquely identifies the cryptomatte within the file. This is not to be confused with the hash of an individual matte.
hash – The hashing method used internally to generate the IDs, this must be ‘MurmurHash3_32’
conversion – The conversion method of pixel values into hashes (only relevant for the rank channel of a cryptomatte). This must be ‘uint32_to_float32’.

Throws:

std::runtime_error – If the hash or conversion are not valid. See hash_method and conversion_method for more information.

static std::vector<metadata> from_spec(const OIIO::ImageSpec &spec, std::filesystem::path image_path)#

Deserialize the cryptomattes’ metadata from an imagespec.

Loads the cryptomatte related values into metadata structs. This may return none, one, or more than one items depending on how many cryptomattes are in the file. No metadata conversely also means that there is no cryptomatte in the file. The individual definitions are separated by their key field.

This function is equivalent to calling from_param_value_list(spec.extra_attribs).

Parameters:

spec – The ImageSpec to deserialize the metadata from.
image_path – The image path that the cryptomatte was loaded from, required if the cryptomatte file has a sidecar manifest.

Throws:

std::runtime_error – If the metadata is malformed or otherwise incorrect in its definition. On failure of a single cryptomatte this function will abort and not parse the other, potentially valid cryptomattes.

Returns:

a vector of metadata definitions, there is no limit to how many there may be in a single file.

static std::vector<metadata> from_param_value_list(const OIIO::ParamValueList &list, std::filesystem::path image_path)#

Deserialize the cryptomattes’ metadata from a param value list.

Parameters:

list – The ParamValueList to deserialize the metadata from.
image_path – The image path that the cryptomatte was loaded from, required if the cryptomatte file has a sidecar manifest.

Throws:

Returns:

a vector of metadata definitions, there is no limit to how many there may be in a single file.

static std::vector<metadata> from_json(const json_ordered &json, std::filesystem::path image_path)#

Deserialize the cryptomattes’ metadata from a json of the images’ metadata.

Parameters:

json – The ordered json to deserialize the metadata from.
image_path – The image path that the cryptomatte was loaded from, required if the cryptomatte file has a sidecar manifest.

Throws:

Returns:

a vector of metadata definitions, there is no limit to how many there may be in a single file.

attribute name constants

Constants for the identifiers of these attributes within the metadata. Cryptomattes store their metadata in the following format cryptomatte/<key>/<attribute>. These functions give you all the valid names for these attributes. These are ‘name’, ‘hash’, ‘conversion’, ‘manifest’ and ‘manif_file’.

static std::string attrib_name_identifier()#

static std::string attrib_hash_method_identifier()#

static std::string attrib_conversion_method_identifier()#

static std::string attrib_manifest_identifier()#

static std::string attrib_manif_file_identifier()#

Public Functions

std::vector<std::string> channel_names(const std::vector<std::string> &channelnames) const#: Retrieve all the cryptomatte channel names for the given list of channelnames in the order they came in. Filters all of them according to is_valid_channel_name and returns all the channel names matching this.

std::vector<std::string> legacy_channel_names(const std::vector<std::string> &channelnames) const#: Retrieve all the legacy cryptomatte channel names for the given list of channelnames in the order they came in. Filters all of them according to is_valid_legacy_channel_name and returns all the channel names matching this.

bool is_valid_channel_name(std::string channel_name) const#

Check whether the passed channel name is a channel name of this metadata (excluding legacy channels). Channel names must follow the following convention

{typename}00.r
{typename}00.g
{typename}00.b
{typename}00.a
{typename}01.r
...

where typename is name

Parameters:: channel_name – The name to match against.
Returns:: Whether the passed channel_name is a channel name.

bool is_valid_legacy_channel_name(std::string channel_name) const#

Check whether the passed channel name is a legacy channel name of this metadata. Legacy channels in cryptomattes are one of the following:

{typename}.r
{typename}.g
{typename}.b

where typename is name

Parameters:: channel_name – The name to match against.
Returns:: Whether the passed channel_name is a legacy channel name.

std::string name() const#

Retrieve the name, also referred to as typename of the cryptomatte.

This determines the name the cryptomatte channels will have. For example, for the first rank channel the name of the channel would be {typename}00.r

std::string key() const#

Retrieve the key of the cryptomatte, this uniquely identifies the cryptomatte within the metadata.

This has no function outside of the metadata and consumers of the API do typically not have to deal with this. This will however tell you which part of the metadata refers to this specific cryptomatte.

std::string_view hash_method() const#: Retrieve the hashing method used for encoding, always ‘MurmurHash3_32’.

std::string_view conversion_method() const#: Retrieve the conversion method used for converting the rank-channel pixels into hashes. Always ‘uint32_to_float32’.

std::optional<cmatte::manifest> manifest() const#: Retrieve the manifest (if present) from the metadata, this may be empty and should not be relied upon for decoding the cryptomatte masks.

python

class cryptomatte_api.Metadata#

__init__(*args, **kwargs)#

Overloaded function.

__init__(self: cryptomatte_api.lib64.cryptomatte_api.Metadata) -> None

Default constructor.

__init__(self: cryptomatte_api.lib64.cryptomatte_api.Metadata, name: str, key: str, hash: str, conversion: str, manifest: typing.Optional[cmatte::manifest] = None) -> None

Construct a cryptomatte metadata object.

Parameters:

name – Cryptomatte type name.
key – Unique identifier within the file.
hash – Hashing method used. Must be ‘MurmurHash3_32’.
conversion – Conversion method. Must be ‘uint32_to_float32’.
manifest – Optional manifest for label-to-ID mapping.

static attrib_conversion_method_identifier() → str#

Return the attribute conversion method identifier (‘conversion’).

Returns:: Identifier string for ‘conversion’ attribute.

static attrib_hash_method_identifier() → str#

Return the attribute hash method identifier (‘hash’).

Returns:: Identifier string for ‘hash’ attribute.

static attrib_manif_file_identifier() → str#

Return the attribute manifest file identifier (‘manif_file’).

Returns:: Identifier string for ‘manif_file’ attribute.

static attrib_manifest_identifier() → str#

Return the attribute manifest identifier (‘manifest’).

Returns:: Identifier string for ‘manifest’ attribute.

static attrib_name_identifier() → str#

Return the attribute name identifier (‘name’).

Returns:: Identifier string for ‘name’ attribute.

channel_names(self: cryptomatte_api.lib64.cryptomatte_api.Metadata, channelnames: collections.abc.Sequence[str]) → list[str]#

Retrieve all valid cryptomatte channel names.

Parameters:: channelnames – List of channel names to filter.
Returns:: Valid cryptomatte channel names.

conversion_method(self: cryptomatte_api.lib64.cryptomatte_api.Metadata) → str#

Get the pixel value conversion method (always ‘uint32_to_float32’).

Returns:: Conversion method.

static from_filepath(filepath: Union[os.PathLike, str, bytes]) → list[cryptomatte_api.lib64.cryptomatte_api.Metadata]#

Load and parse cryptomatte metadata from an image file.

Parameters:: filepath – Path to the image file.
Returns:: List of Metadata objects parsed from the file.

static from_json(json: json, image_path: str) → list[cryptomatte_api.lib64.cryptomatte_api.Metadata]#

Parse metadata from JSON representation.

Parameters:

json – Ordered JSON data representing the metadata.
image_path – Path to the source image (used to locate sidecar manifests).

Returns:

List of Metadata objects parsed from the JSON.

hash_method(self: cryptomatte_api.lib64.cryptomatte_api.Metadata) → str#

Get the hashing method used (always ‘MurmurHash3_32’).

Returns:: Hash method.

is_valid_channel_name(self: cryptomatte_api.lib64.cryptomatte_api.Metadata, channel_name: str) → bool#

Check if a channel name is a valid cryptomatte channel name (non-legacy).

Parameters:: channel_name – The name to match against.
Returns:: True if valid, False otherwise.

is_valid_legacy_channel_name(self: cryptomatte_api.lib64.cryptomatte_api.Metadata, channel_name: str) → bool#

Check if a channel name is a valid legacy cryptomatte channel name.

Parameters:: channel_name – The name to match against.
Returns:: True if valid, False otherwise.

key(self: cryptomatte_api.lib64.cryptomatte_api.Metadata) → str#

Get the unique key identifying this cryptomatte.

Returns:: Unique key.

legacy_channel_names(self: cryptomatte_api.lib64.cryptomatte_api.Metadata, channelnames: collections.abc.Sequence[str]) → list[str]#

Retrieve all valid legacy-style cryptomatte channel names.

Parameters:: channelnames – List of channel names to filter.
Returns:: Valid legacy cryptomatte channel names.

manifest(self: cryptomatte_api.lib64.cryptomatte_api.Metadata) → Optional[cmatte::manifest]#

Get the optional manifest mapping names to hash IDs.

Returns:: The manifest or None.

name(self: cryptomatte_api.lib64.cryptomatte_api.Metadata) → str#

Get the name (type identifier) of the cryptomatte.

Returns:: Cryptomatte name.