Metadata

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:

• core.listProperties
• core.getProperty

To directly extract this information, use this function:

• scene.getMetadatasDefinitions

To retrieve occurrences that match specific metadata, use this function:

• scene.findOccurrencesByMetadata

Note

Metadata can be very usefull to identify occurrences and apply a specific process on them. But they contribute to increase the final size of your 3D file.

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 occurrence
    metadata_comp1 = scene.addComponent(occurrence1, scene.ComponentType.Metadata)
    # Add some values to this metadata
    scene.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 values
    scene.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 metadata
def 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 with
    occurrences_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