Cryptomatte BPY API

Since last week Blender has Cryptomatte in its core (BlenKernel module). This makes it easier to add an python API for cryptomatte. is a task that shows several ways how to setup the API. I would like to have some feedback on the proposed API.

The API can be used to extract Cycles/EEVEE cryptomatte hashes using python. An example what could be done using this API is to create a sidecar JSON file. What we also want to know are what use cases this API should be targeted at.

The proposal will add functions to the Object and Material RNA struct that returns a CryptomatteHash object. The object has functions to retrieve the representation of the hash as a float or an uint.

crypto_hash = ob.cryptomatte_hash(type='CRYPTOMATTE_ASSET', hasher='MurmurHash3_32')
crypto_hash_uint = crypto_hash.to_int() # example: 1239807102983
crypto_hash_hex = crypto_hash.to_hex() # example: F3982A8B
crypto_hash_float = crypto_hash.to_float(encoding='uint32_to_float32')

uint32_to_float32 and MurmurHash3_32 are defaults and the only available options ( It shows how the API could be enhanced when needed in the future.

The proposal was selected as code completion will guide the developer on usage and conversions are explicit. What makes the code more maintainable.


I’d like to understand the specific use case for this. If it’s mainly to generate the JSON file, perhaps we simply need an API function to generate a complete JSON string for a scene?

Because we might want to support writing that into OpenEXR metadata as part of render output, and if we do then we probably should have that implementation in C/C++. Though I’m not sure how easy it is to do e.g. escaping of name strings for JSON.

Or are there cases where users somehow want to customize the contents of that JSON file, and getting a complete JSON string would not work?

The other thing to note is that a render is done from a render mode evaluated scene, potentially with objects instances that may not exist in the original scene or the scene evaluated in viewport mode. I’m not sure if that’s an issue, or if those instances will somehow share an hash with the original object.

There is a patch for generating the cryptomatte meta data in C++. It is a copy from Cycles. There isn’t any string encoding and is easy to add.

The instanced objects should be tested. I will add it to the todos.

Ah, I think it needs string escaping for when the character contains " or \ at least, but we may have missed that in Cycles. Shouldn’t be too complicated anyway.

I wonder then what the use cases are that are not covered by providing this string through the API. Parsing the string in Python should be pretty easy with the json module as well, if needed.