Cryptomatte Tools

by Dragon.Studio in Scripts and Addons

How to use

When no Cryptomatte node exists the addon just shows Cryptomatte ID in Object Properties, in the same format as it would appear in a Cryptomatte node. For example this is how it looks for the default cube:

Cryptomatte supported in both Cycles and Eevee (Cryptomatte for Eevee requires Blender 2.92 or newer). To begin using Cryptomatte Tools in View Layer Properties enable at least one Cryptomatte type, for example Object:

Then in Compositing Workspace enable nodes:

And create at least one Cryptomatte node:

Then in Scene Properties Cryptomatte Tools panel will appear:

In Node menu you can choose a Cryptomatte node. Alternatively, select a Cryptomatte node in Compositor. Please note that only "Add Objects" button is available. This is because the node connected to CryptoObject slot of Render Layers so it makes sense only to add objects.

If you look at the Cryptomatte node, you will see it has Crypto ID of the Cube added:

Let's try renaming it from "Cube":

To "Box":

Normally Cryptomatte node will lose track of the objects and may even end up picking wrong one (if you latter create an object with the same name). But thanks to Cryptomatte Tools, Crypto ID will be automatically updated to the new one:

This helps to organize your scene without worrying about accidentally breaking references in Cryptomatte nodes.

Let's create two additional objects:

First cube already added to the Cryptomatte node but the other one isn't, this is why we have both Add Objects and Remove Objects buttons available simultaneously.

After clicking Add Objects, second cube will be added and only Remove buttons will be available:

If automatic clean up (refreshing and reformating cryptomatte list) is disabled either in setting or due performance reasons (usually in very large scene where iterating through all objects is costly), you may need to press it manually but normally it is done automatically and always grayed out, so you do not need to worry about it in most cases.

If we clear selection, then only two buttons will be available:

Remove All will make the list in the Cryptomatte node empty. Append to Selected will add all objects from Cryptomatte list to current selection. If you click it, it would look like in the previous screenshots, with two cubes selected. This is quick and easy way to see what objects are assigned to the Cryptomatte node.

In Object and Material Properties, the object or its material can be removed or added individually:

The addon has advanced preferences, defaults should work well in most cases, change these settings only if you have a reason:

Please read the tooltips by hovering the mouse cursor on each settings if you want to know more. One issue worth mentioning not specific to the addon but Blender in general is that if there is at least one addon which uses modal operator, Blender will disable autosave. Without modal operator, tracking renaming of objects is not possible. You can disable tracking if you do not need it and then restart Blender for the change to take effect.

Python API

  • bpy.types.Scene.find_nodes_by_type(type_="VIEWER", node_tree=None, limit=inf, _found_nodes=[])

Find nodes whose type is equal to type_. For example, "VIEWER" will find all viewer nodes.

You can specify node_tree manually if you want to limit a search to a specific tree.

The limit variable sets a limit, if you need to find just one node, you can set it to one, and the first found node will be returned. If the limit is set to infinity, then all nodes will be searched.

If node_tree is None, node_tree will be set to scene.node_tree.

The _found_nodes variable is for internal use and should not be used.

  • bpy.types.Scene.matte_id_get_object(id_, material=False)

The id_ variable can be int (Murmurhash3), float or string (in the format it appears in the Cryptomatte node list).

If material == True, this function will return a material with matching id_. Since in Blender object and material can have the same name and Murmurhash3 is name-based (as required by the Cryptomatte standard), it is necessary to distinguish them with an additional flag.

  • bpy.types.Scene.uid_get()

Return object's or material's unique ID (32-bit hash). The uid variable can only be an integer.

  • bpy.types.Scene.uid_get_object(uid)

Return object or material by its unique ID (32-bit hash). The uid variable can only be an integer.

  • bpy.types.Scene.uid_get_node(uid)

Return node by its unique ID (32-bit hash). The uid variable can only be an integer. Only nodes of type CompositorNodeCryptomatte are supported.

  • bpy.types.Scene.matte_id_uid_storage

For internal usage only, do not use. It preserves stored Cryptomatte IDs and UIDs. Since Cryptomatte ID can be the same for an object and a material if they both have the same name, it is necessary to store corresponding UIDs.

  • bpy.types.CompositorNodeCryptomatte.uid_get()

Return node's unique ID (32-bit hash). The uid variable can only be an integer.

  • bpy.types.CompositorNodeCryptomatte.matte_id_objects_get()

Returns objects list for a given Cryptomatte node.

  • bpy.types.CompositorNodeCryptomatte.matte_id_materials_get()

Returns material list for a given Cryptomatte node.

  • bpy.types.CompositorNodeCryptomatte.matte_id_add(objects, material=False)

The objects variable can be either an object or material, or a list of objects/materials. This function adds an object or list of objects to the Cryptomatte node. If material is True, then add an material or list of materials.

  • bpy.types.CompositorNodeCryptomatte.matte_id_remove(objects)

The objects variable can be either an object or material, or a list of objects/materials. This function removes an object or list of objects from the Cryptomatte node.

  • bpy.types.CompositorNodeCryptomatte.matte_id_set(objects, material=False)

This function is similar to matte_id_add() but clears the list in the Cryptomatte node before adding objects/materials.

  • bpy.types.CompositorNodeCryptomatte.matte_id_is_in(objects, material_slots=False, return_list=False, partial_match=False)

Returns either a boolean or list of booleans for given objects if they are in the list of the Cryptomatte node. If both material_slots and return_list are True, then it will return list of lists of booleans - list with an element per objects, and each element will be a list of booleans for each material slot which belong to the object, even if it has only one or none.

  • bpy.types.CompositorNodeCryptomatte.matte_id_clean_up()

Clean up matte_id by regenerating it. This will update matte_ids in case if some objects are renamed, will remove unnecessary commas, etc. Usually there is no need to call this function, but if you are changing names of objects with a script and it to be sure that the list in the Cryptomatte node is updated, it can be useful.

  • bpy.types.CompositorNodeCryptomatte.matte_id_clean_up_force

Force background node clean up if set to True. This flag will eventually cause a call to node.matte_id_clean_up() function and then will be set back to False. This flag should be used only internally, but if you do use it for some reason, never set it to False yourself, it can only be set to True.

  • bpy.types.CompositorNodeCryptomatte.matte_id_append_to_selected(context=bpy.context)

Append to current selection objects listed in the Cryptomatte node. If the node contains list of materials, then objects which have them will be appended to the selection.

  • bpy.types.CompositorNodeCryptomatte.matte_id_remove_from_selected(context=bpy.context)

Remove from current selection objects listed in the Cryptomatte node. If the node contains list of materials, then objects which have them will be removed from the selection.

  • bpy.types.CompositorNodeCryptomatte.matte_id_cached

Cached matte_id to keep track of removed objects in the compositor with the eyedrop tool of Cryptomatte node. For internal use only.

  • bpy.types.CompositorNodeCryptomatte.uid

For internal use only! Use uid_get() to get the uid instead!

  • bpy.types.CompositorNodeCryptomatte.uid_get()

Unique hash which never changes after initialization (unless duplicated - then new one will be generated).

  • bpy.types.Object.matte_id_get()

Returns object's Cryptomatte ID as a float.

  • bpy.types.Object.matte_id_get_hash()

Returns object's Cryptomatte ID as an integer.

  • bpy.types.Object.matte_id_get_str()

Returns object's Cryptomatte ID as a string (for example, <1.23456789>).

  • bpy.types.Object.matte_id_cached_hash

For internal use only, please use matte_id_get_hash() to get the hash. Cached Cryptomatte ID (Murmurhash3) of the object at the moment when matte_id_get() was called on it last time.

  • bpy.types.Object.matte_id_cached_name

This is for internal use only. Name of the object at the moment when matte_id_get() was called on it last time.

  • bpy.types.Object.uid

This is for internal use only, please use uid_get() to get current UID.

  • bpy.types.Object.uid_get()

Unique hash which never changes after initialization (unless duplicated - then new one will be generated).

  • bpy.types.Material.matte_id_get()

Returns object's Cryptomatte ID as a float.

  • bpy.types.Material.matte_id_get_hash()

Returns object's Cryptomatte ID as an integer.

  • bpy.types.Material.matte_id_get_str()

Returns object's Cryptomatte ID as a string (for example, <1.23456789>).

  • bpy.types.Material.matte_id_cached_hash

For internal use only, please use matte_id_get_hash() to get the hash. Cached Cryptomatte ID (Murmurhash3) of the object at the moment when matte_id_get() was called on it last time.

  • bpy.types.Material.matte_id_cached_name

This is for internal use only. Name of the object at the moment when matte_id_get() was called on it last time.

  • bpy.types.Material.uid

This is for internal use only, please use uid_get() to get current UID.

  • bpy.types.Object.uid_get()

Unique hash which never changes after initialization (unless duplicated - then new one will be generated).