Metadata
Learn how to access, modify, and use metadata in scenes to identify and process occurrences.
Read time 3 minutesLast updated 9 months ago
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:
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 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 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