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.

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 there is active Cryptomatte node and it contains list of objects, pressing "Generate Object Index" button will generate Object Index for each object in the Cryptomatte node, incrementing it by 1 for each object in its list from the base value of 1. The same is true for "Generate Material Index" button, but for working with materials.

If "For All Objects" checkbox is enabled, Pass Index is generated for all 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 objects listed in the active Cryptomatte node). If you need to generate Object Indexes one-time and then want to edit them manually, just double click the checkbox, it will generate the indexes and second click will turn it off. "For All Objects" checkbox works in similar way for materials.

There are "Create Object/Material Color ID Material" buttons, each of them can add a material which will have color based on Object or Material Index. When at least one of these materials is added to the scene, you can click "Override Material" button.

In case of "Object ID Material", clicking "Override Material" button is the same as going to View Layer Properties > Override, scrolling way down, and choosing the Color ID material. If you want to set the override in new View Layer, just create new View Layer before clicking the button.

In case of "Material Color ID", clicking "Override Material" button does more than that, it will generate temporary materials and will automatically remove them when you choose to click "Restore Materials" button; your own materials will be unaffected. Here is an example how "Create Material Color ID Material" buttons works. Three cubes have two different materials, each with different Pass Index (both materials look the same).

When you press Override Materials, since three cubes have only two materials, each with unique Pass Index, two cubes share the same colors as expected:

When you press Restore Materials, original materials are restored and temporary materials are removed, and everything looks like on the first picture. It will not affect new materials you have created manually, if there are any.

This how Object Color ID material looks like which was created by clicking the button:

If "For All Objects" checkbox is enabled, each new object will get unique Object Index. If you need to generate Object Indexes one-time and then want to edit them manually, just double click the checkbox, it will generate the indexes and second click will turn it off. If in a scene with three cubes you will enable the checkbox, and click buttons to create the material and override it in current View Layer, this how the result looks:

On the right I switched to View Layer Properties to show what material was set by clicking the "Override" button. If the override is deleted by clicking "x" next to the material name, all objects will use their normal materials. Number of samples can be either left at "0" or set manually if it needs to be different from other View Layers - it will control AA quality for Color ID.

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.

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


Sales 20+
Customer Ratings 1
Average Rating
Dev Fund Contributor
Published 10 months ago
Software Version 2.83, 2.9, 2.91, 2.92, 2.93
License GPL
Have questions before purchasing?

Contact the Creator with your questions right now.

Login to Message