NCP-OUSD: Data Exchange &
Pipeline Development

Before writing any importer/exporter, create a data mapping document that records:

• Source system — e.g., Maya DAG, FBX hierarchy, glTF node tree
• Target USD concept — prim type, path structure, attribute names
• Value transformations required — axis conversion, unit scaling, naming conventions

Example Mapping Table: Maya → USD

Axis & Unit Conventions

• Maya = Y-up; USD default = Y-up (Z-up also supported)
• Specify: stage.SetMetadata("upAxis", "Y")
• Unit scale: stage.SetMetadata("metersPerUnit", 0.01) for centimeter scenes
• Ambiguous mappings (e.g., instancing strategy) must be resolved and documented before coding begins

Pattern: read source data → create Usd.Stage → define prim hierarchy → set attributes → save

• Use Sdf.Layer.CreateNew() for efficient batch authoring — bypasses change notification overhead
• Sdf-level authoring: Sdf.PrimSpec, Sdf.AttributeSpec, Sdf.RelationshipSpec — faster than Usd-level for large imports
• Validate: UsdUtils.ComplianceChecker for schema compliance; UsdGeom.Imageable for renderable prims
• Time samples at Sdf level: build a timeSamples dict and set via attr.SetMetadata("timeSamples", {...})

# Sdf-level batch importer (fast)
from pxr import Sdf, Usd, UsdGeom

layer = Sdf.Layer.CreateNew("/tmp/import.usda")
with Sdf.ChangeBlock():
    prim_spec = Sdf.PrimSpec(layer, "MyMesh", Sdf.SpecifierDef, "Mesh")
    prim_spec.SetInfo("kind", "component")
    # Set a points attribute
    attr = Sdf.AttributeSpec(prim_spec, "points", Sdf.ValueTypeNames.Point3fArray)
    attr.SetMetadata("timeSamples", {1.0: [(0,0,0),(1,0,0)], 2.0: [(0,1,0),(1,1,0)]})

layer.Save()
print("Import complete:", layer.identifier)

Pattern: traverse Usd.Stage → convert USD data → write to target format

• stage.Traverse() iterates all prims; prim.GetFilteredChildren(predicate) for filtered traversal
• UsdGeomPrimvarsAPI(prim).GetPrimvars() to collect all primvars
• Instancing: prim.IsInstance(); get shared data from prim.GetPrototype()
• Time samples: attr.GetTimeSamplesInInterval(Gf.Interval(startTime, endTime))
• Flatten before export if needed: stage.Flatten() returns a single-layer Sdf.Layer

from pxr import Usd, UsdGeom, Gf

stage = Usd.Stage.Open("/path/to/scene.usda")

for prim in stage.Traverse():
    if prim.IsA(UsdGeom.Mesh):
        mesh = UsdGeom.Mesh(prim)
        pts_attr = mesh.GetPointsAttr()
        # Export time samples in the shot range
        interval = Gf.Interval(stage.GetStartTimeCode(), stage.GetEndTimeCode())
        time_samples = pts_attr.GetTimeSamplesInInterval(interval)
        print(f"{prim.GetPath()}: {len(time_samples)} time samples")
        # Handle instances
        if prim.IsInstance():
            proto = prim.GetPrototype()
            print(f"  Instance of prototype: {proto.GetPath()}")

DCC applications (Maya, Houdini) expose a plugin hook that fires during USD export. The hook can:

• Rename prims to match studio naming conventions
• Add custom metadata or attributes
• Remap material paths to the studio's asset library
• Validate output and raise errors for non-compliant exports

Registration: Maya USD uses mayaUsdTranslatorExport; Houdini uses ROP USD output driver hooks. Both register via plugInfo.json.

// plugInfo.json — registers your export hook plugin
{
    "Plugins": [{
        "Name": "StudioUSDExportHook",
        "Type": "python",
        "Info": {
            "mayaUsdTranslatorExport": {
                "exportParentScope": true
            }
        },
        "LibraryPath": ".",
        "ResourcePath": "."
    }]
}

# studio_export_hook.py — hook implementation
from pxr import Usd, UsdGeom, Sdf

def post_export_callback(stage, export_options):
    """Fired by Maya USD after each prim is exported."""
    for prim in stage.Traverse():
        # Enforce naming convention: all prims lowercase
        if prim.GetName() != prim.GetName().lower():
            stage.GetRootLayer().Rename(
                str(prim.GetPath()),
                str(prim.GetPath()).lower()
            )
        # Stamp with studio metadata
        prim.SetMetadata("customData", {"studio": "MyStudio", "pipeline": "v2"})

• Default resolver: resolves asset paths relative to the anchoring layer
• Custom ArResolver: override Ar.Resolver to implement studio-specific path resolution
• Use case: "asset:myAsset?v=3" resolved to "/studio/assets/myAsset/v003/asset.usda"
• ArResolver.Resolve(path) → returns the filesystem path for the given asset identifier
• Resolver context: ArResolverContext — pass studio session info (shot, sequence, user) to the resolver
• SearchPath: fallback resolution using a list of root directories

from pxr import Ar

class StudioResolver(Ar.Resolver):
    """Translates 'asset:NAME?v=N' URIs to real file paths."""

    def Resolve(self, path):
        if path.startswith("asset:"):
            name, _, version_str = path[6:].partition("?v=")
            version = int(version_str) if version_str else "latest"
            return f"/studio/assets/{name}/v{version:03d}/asset.usda"
        return super().Resolve(path)

    def CreateDefaultContext(self):
        # Provide shot context from environment
        import os
        return Ar.ResolverContext({"shot": os.environ.get("SHOT", ""), "user": os.environ.get("USER", "")})

Shot Pipeline Structure

• /asset/v001/ → /shot/seq/shot/anim/ → /shot/seq/shot/lighting/
• Version immutability: published versions are never edited; new work creates a new version
• Version pinning: reference "asset?v=3" (resolver handles it) vs hardcoded path
• Work-in-progress layers: artist edits a "work" layer; publishing bakes it to a versioned path
• Dependency flattening for delivery: UsdUtils.FlattenLayerStack or stage.Export() bakes all opinions into one layer; removes proprietary references

# Publish a work layer as a new versioned asset
from pxr import Usd, UsdUtils
import shutil, os

work_path = "/studio/work/myAsset/asset.usda"
publish_path = "/studio/assets/myAsset/v004/asset.usda"

# Open work layer and flatten all sublayers
stage = Usd.Stage.Open(work_path)
flat_layer = stage.Flatten(addSourceFileComment=False)

os.makedirs(os.path.dirname(publish_path), exist_ok=True)
flat_layer.Export(publish_path)
print(f"Published to {publish_path}")

• USD build config: usd_config.cmake or setup.cfg controls which plugins are included
• Proprietary dependency removal: flatten + strip custom metadata before client delivery
• stage.Flatten(addSourceFileComment=False) → one merged layer, no external references
• UsdUtils.StitchLayers — merge multiple layers into one, preserving time samples
• usdzip / usdchecker — command-line tools for packaging and validation

# Merge per-frame USD caches into a single multi-frame layer
from pxr import UsdUtils, Sdf

frame_layers = [Sdf.Layer.FindOrOpen(f"/cache/frame.{f:04d}.usd") for f in range(1001, 1049)]
merged = Sdf.Layer.CreateNew("/deliver/animation_cache.usd")
UsdUtils.StitchLayers(merged, frame_layers)
merged.Save()
print("Stitched", len(frame_layers), "frames into animation_cache.usd")

# Command-line: package scene + all dependencies into .usdz
usdzip --asset /path/to/scene.usda /path/to/output.usdz

# Validate before delivery
usdchecker /path/to/output.usdz

# Inspect merged/flat result
usdcat --flatten /path/to/scene.usda