Metadata#

Tools for adding structured metadata to USD assets using layer composition with type-based namespacing.

Overview#

These tools add custom properties to USD assets non-destructively using separate property layers. All numeric values use SI units (meters, kilograms, Kelvin, watts) unless otherwise noted in the property description.

Properties are organized using a two-level namespace hierarchy:

aif:core: - Common properties shared across all equipment (manufacturer, dimensions, and version info)
aif:spec: - Equipment-specific properties (cooling capacity, voltage ratings, and battery type)

Quick Start#

# Create a metadata template for specific equipment
aif-pipeline metadata create --type cdu --output cdu.json

# Edit cdu.json to customize values...

# Apply metadata to create USD property layer
aif-pipeline metadata apply cdu.json --output cdu_properties.usda --prim Root

# Update an existing property layer after template changes
aif-pipeline metadata update cdu_properties.usda

Equipment Types#

Type	Description	Properties
`cdu`	Coolant Distribution Unit	81 (20 common + 61 specific)
`crah`	Computer Room Air Handler	51 (20 common + 31 specific)
`ups`	Uninterruptible Power Supply	51 (20 common + 31 specific)
`gb300_rack`	NVIDIA DGX GB300 Rack	27 (20 common + 7 specific, pre-filled)

Workflow#

1. Create Templates#

aif-pipeline metadata create --type cdu --output cdu.json
aif-pipeline metadata create --type crah --output crah.json

2. Customize Templates#

Edit the generated JSON files to match your asset specifications:

{
    "properties": {
        "aif:core:manufacturer": {
            "type": "string",
            "value": "Your Company Name",
            "description": "Equipment manufacturer"
        },
        "aif:spec:coolingCapacity": {
            "type": "float",
            "value": 75000.0,
            "description": "Cooling capacity in Watts"
        }
    }
}

3. Generate USD Property Layers#

aif-pipeline metadata apply cdu.json --output GenericCDU_Properties.usda --prim Root
aif-pipeline metadata apply crah.json --output CW375_Properties.usda --prim Root

Note

Naming Convention Use <ModelName>_Properties.usda (for example, CW375_Properties.usda) to match the convention used for connection points files.

4. Compose Layers#

Add the property layers to your main USD asset as sublayers:

GUI (USD Composer)

Open the main asset file in USD Composer and drag the property layer into the Layers panel as a sublayer. Use the Scene Optimizer add_layers processor to automate this step in presets.

Python

from pxr import Sdf

layer = Sdf.Layer.FindOrOpen("asset.usda")
sublayers = layer.subLayerPaths
sublayers.append("cdu_props.usda")
layer.subLayerPaths = sublayers
layer.Save()

5. Update Metadata#

When templates change (new properties added, version bumped), update existing property layers independently:

# Auto-detect equipment type from aif:core:assetClass
aif-pipeline metadata update GenericCDU_Properties.usda

# Explicit type
aif-pipeline metadata update GenericCDU_Properties.usda --type cdu

# Preview changes without writing
aif-pipeline metadata update GenericCDU_Properties.usda --dry-run

The update command compares the existing .usda file against the current template, adds any missing properties, and updates aif:core:assetVersion if the template defines a different value. Existing properties are never removed.

USD Metadata Attributes Tool#

The metadata/simready_add_attributes/ directory contains a standalone tool for adding advanced metadata attributes to USD prims:

Non-visual sensors - Radar, lidar, ultrasonic, camera, IMU, GPS
Wikidata semantics - Semantic classification using Wikidata entity IDs
Dense captions - AI-generated or manual descriptions
HOOPS migration - Automatic migration of Omniverse HOOPS metadata to USD semantic schema
Physics collision meshes - Convex hull, bounding box, sphere, mesh approximations
Physics joints - Revolute, prismatic, fixed, spherical, distance, D6

# Add Wikidata semantic classification
python usd_add_metadata_attributes.py scene.usda \
    --add-wikidata /World/Car Q1420 "Automobile"

# Bulk migrate all HOOPS metadata in a file
python usd_add_metadata_attributes.py scene.usda --migrate-hoops

# Apply batch metadata from JSON config
python usd_add_metadata_attributes.py scene.usda \
    --config metadata_config_example.json