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.

Color ID Map

The addon can also generate pass index for objects and/or materials, and you can override material with a single click on a button, then you can render Color ID map. In Scene Properties > Cryptomatte Tools under Pass Index label you can see few button and checkboxes:

If "For All Objects" checkbox is enabled, Pass Index is generated for all selected objects on the fly, so "Generate Object Index" button becomes grayed out (the button is needed only if you want to generate Pass Index for selected objects). You can use the button if you want generate Object Indexes one time only and then want to edit them manually. "For All Objects" checkbox works in a similar way for materials.

Here is a usage example on a simple scene with two cubes with the same material and a plane with PNG tree texture, it contains alpha channel. First, either set the checkboxes ("For All Objects" and "For All Materials") to generate Pass Index for all objects and materials (new objects and materials will get their Pass Index automatically while the checkboxes are set), or click corresponding buttons once each, if you only want to generate Pass Index for selected objects (if nothing is selected, it will be generated for all objects/materials).

If you click "Object ID" button, this is what the result will look like (if nothing is selected, all objects in the scene will be affected; otherwise, only selected objects):

And if you click "Material ID" button, this is what the result will look like (if nothing is selected, all objects in the scene will be affected; otherwise, only selected objects):

Usually Color ID map is good as is for most purposes without manual adjustment. But sometimes Color ID map is used as an illustration to show silhouettes or some other purpose where visual color contrast may play important role, and in such cases you sometimes may need to change object/material Pass Index manually to get a better visual contrast.

If you click "Restore Materials", the scene will look like the first image.

If current renderer is set to anything but Eevee, a warning "(Note: Switch to Eevee if you need alpha in Color ID)" will be shown to let the user know that Eevee is necessary to render Color ID with alpha. Cycles can work too for rendering Color ID maps but then the tree above will be rendered as a solid rectangle. Since for Color ID difference in AA quality between Eevee and Cycles is hardly noticeable, this shouldn't be an issue, but may require an extra click to switch render engine if alpha channel in Color ID shaders is needed.

Automatically creating Cryptomatte nodes for selected objects and exporting output as separate images

This can be useful for exporting to programs which do not support Cryptomatte directly but can import separate images as layers.

As a simple example to demonstrate how to use this feature, I have used a simple scene with three cubes selected, then I enabled "File Output" and clicked "For Each Selected Object" button. The result can be seen in the node editor: three Cryptomatte nodes were created and one File Output node with three input slots.

File format can be configured by selecting File Output node, in its Properties. If I render this example scene, I get three images with names like "CryptoObject_Cube_0001.jpg" (where "CryptoObject_" is the prefix and "_" before the frame number is the suffix). By default output path is set to current directory ("//"), usually this is the directory where the .blend file is saved (but if the scene is new and never been saved yet, the addon directory is considered the current directory). Of course you can easily configure the path to any directory you like.

By default Cryptomatte V2 nodes are created. There is also legacy Cryptomatte node support. It can be enabled with "Use Legacy Nodes" checkbox, then legacy Cryptomatte nodes will be created and their Crypto inputs will be correctly connected even if number of Cryptomatte levels was customized.

Please note that you need to enable "Use Nodes" in the Compositor, otherwise "Create Cryptomatte node" part of the GUI will be hidden!

If you have multiple Render Layers nodes, the first one will be used by default but you can select the one you need before clicking "For Each Selected Object" button, then selected Render Layers node will be used to create links to generated nodes.

"For Each Selected Material" button works in similar way, it will create Cryptomatte node for each material in selected objects.

There is new "Matte" option, you can see it after setting "File Output" checkbox, it allows to automatically connect Matte output of each Cryptomatte node instead of Image output:

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).