Documentation

Support

Asset Transformer SDK

User Manual

Python API

C# API

Changelog

Discussions

Asset Transformer SDK

Metadata

Learn how to access, modify, and use metadata in scenes to identify and process occurrences.
Read time 2 minutesLast updated 21 hours ago
API reference Metadata are components that store basic key-value information that is retrieved from imported files. Use the API to read, add, modify, and delete metadata. To access this information, use these functions: To directly extract this information, use this function: To retrieve occurrences that match specific metadata, use this function:

Code example

Create new occurrences with metadata attached

Let's create a test scene with multiples occurrences and try to attach metadata on them. 
def createTestScene():root = scene.getRoot()occurrence1 = scene.createOccurrence(name="occ1", parent=root)# Add a metadata component to the occurrencemetadata_comp1 = scene.addComponent(occurrence1, scene.ComponentType.Metadata)# Add some values to this metadatascene.addMetadata(metadata_comp1, "m_1", "myValue1")scene.addMetadata(metadata_comp1, "m_2", "myValue2")occurrence2 = scene.createOccurrence(name="occ2", parent=occurrence1)metadata_comp2 = scene.addComponent(occurrence2, scene.ComponentType.Metadata)# More efficient way to populate metadata with multiple valuesscene.addMetadataBlock(metadata_comp2, ["m_2", "m_3", "m_4"], ["myValue3", "myValue4", "myValue5"])occurrence3 = scene.createOccurrence(name="occ3", parent=occurrence1)metadata_comp3 = scene.addComponent(occurrence3, scene.ComponentType.Metadata)scene.addMetadata(metadata_comp3, "m_3", "myValue6")occurrence4 = scene.createOccurrence(name="occ4", parent=root)

Print the hierarchy tree and the metadata attached

We want to be able to print the name of each occurrence and their associated metadata. 
# Go through the product structure using "depth first" recursive method and retrieve and display metadatadef dfPrintOccurrencesNameAndMetadata(offset, occurrence):    occurrence_info = scene.getOccurrenceName(occurrence)    # Ensure occurrence has a metadata attached before trying to access it    if scene.hasComponent(occurrence, scene.ComponentType.Metadata):        occurrence_info = occurrence_info + ", metadata: "        metadata_comp = scene.getComponent(occurrence, scene.ComponentType.Metadata)        metadata_definitions = scene.getMetadatasDefinitions([metadata_comp])[0]        for metadata in metadata_definitions:            metadata_info = f'(name: {metadata.name}, value: {metadata.value})'            occurrence_info = occurrence_info + metadata_info    print(offset + occurrence_info)    offset = offset + " |- "    for child in scene.getChildren(occurrence):        dfPrintOccurrencesNameAndMetadata(offset, child)

Output

Root |- occ1, metadata: (name: m_1, value: myValue1)(name: m_2, value: myValue2) |- |- occ2, metadata: (name: m_2, value: myValue3)(name: m_3, value: myValue4)(name: m_4, value: myValue5) |- |- occ3, metadata: (name: m_3, value: myValue6) |- occ4

Filter the metadata in the scene

To cleanup our scene, and remove useless information, we want to filter all the metadata with specific names contained in a blacklist. 
def removeBlacklistedMetadata():    # Retrieve all the occurrences in the scene    occurrences = scene.findOccurrencesByProperty("Name", ".*")    # Retrieve all the associated metadata components    metadata_components = scene.getComponentByOccurrence(occurrences, pxz.scene.ComponentType.Metadata, True)    black_listed_metadata_names = ['m_2', 'm_3']    # Change to a set structure to perform faster search    black_listed_metadata_set = set(black_listed_metadata_names)    metadata_definitions = scene.getMetadatasDefinitions(metadata_components)    for i in range(len(metadata_definitions)):        for metadata in metadata_definitions[i]:            if metadata.name in black_listed_metadata_set:                scene.removeMetadata(metadata_components[i], metadata.name)

Output

Root|- occ1, metadata: (name: m_1, value: myValue1)|-  |- occ2, metadata: (name: m_4, value: myValue5)|-  |- occ3, metadata: |- occ4

Identify an occurrence by metadata

Let's assume we want to rename every occurrence that contain a specific metadata. 
def selectOccurrencesByMetadataAndRenameThem():# We retrieve all the occurrence with a metadata containing a value "myValue1"occurrences_found_by_value = scene.findOccurrencesByMetadataValue("myValue1")for occurrence in occurrences_found_by_value:    name = scene.getOccurrenceName(occurrence)    scene.setOccurrenceName(occurrence, name + " retrieved by value")# We retrieve all the occurrence with a metadata named "m_1" no matter the value associated withoccurrences_found_by_value = scene.findOccurrencesByMetadata("m_4", ".*")for occurrence in occurrences_found_by_value:    # Another way to get occurrence name    name = core.getProperty(occurrence, "Name")    # Another way to set occurrence name. A name is a property of the occurrence    core.setProperty(occurrence, "Name", name + " retrieved by name")

Output

Root|- occ1 retrieved by value, metadata: (name: m_1, value: myValue1)|-  |- occ2 retrieved by name, metadata: (name: m_4, value: myValue5)|-  |- occ3, metadata: |- occ4