NCP-OUSD: Customizing USD,
Debugging & Troubleshooting

USD Plugin System

All USD extensions are plugins registered via plugInfo.json. Every custom schema, file format plugin, ArResolver, and Kind registry entry must have a corresponding plugInfo.json in a directory that USD can discover.

• plugInfo.json lives in the plugin directory; USD finds it via the PXR_PLUGINPATH_NAME environment variable
• Plugin types: schema plugins, file format plugins, custom ArResolver, custom Kind registry
• After adding a plugin: restart the USD environment — plugins load at startup, not dynamically

# plugInfo.json structure
{
  "Plugins": [
    {
      "Type": "resource",
      "Name": "myStudioPlugin",
      "Root": ".",
      "Info": {
        "Types": {
          "MyAsset": {
            "bases": ["UsdTyped"],
            "alias": { "UsdSchemaBase": "MyAsset" }
          }
        }
      }
    }
  ]
}

# Shell: point USD to your plugin directory
export PXR_PLUGINPATH_NAME=/studio/plugins/myStudioPlugin

Custom IsA Schemas

An IsA schema defines a new prim type — like UsdGeomMesh, but for your studio's custom data. Prims of this type appear in the USD type registry and can be queried via prim.GetTypeName().

• Defined in schema.usda: class MyAsset "MyAsset" ( inherits = </Typed> ) { ... }
• Compiled with: usdGenSchema schema.usda — generates C++ headers and Python bindings
• Registered via plugInfo.json under "SdfMetadata" and "UsdSchemaBase"
• IsA schemas inherit from Typed — prim has a defined type in the USD type registry

# schema.usda — defining a custom IsA schema
class MyAsset "MyAsset" (
    inherits = </Typed>
    doc = "A custom studio asset type."
) {
    string asset:category = "" (doc = "Asset category, e.g. hero_prop")
    float asset:lodBias = 1.0
}

# Python: create a prim of your custom type
stage = Usd.Stage.CreateInMemory()
prim = stage.DefinePrim("/World/Hero", "MyAsset")
print(prim.GetTypeName())   # "MyAsset"

# Access generated attribute helpers (after usdGenSchema)
myAsset = MyAsset(prim)
myAsset.GetAssetCategoryAttr().Set("hero_prop")

Custom API Schemas

An API schema adds behavior to any prim without changing its type. Multiple API schemas can be applied to a single prim simultaneously — something IsA schemas cannot do.

• Defined in schema.usda: class "MyDataAPI" ( inherits = </APISchemaBase> ) { ... }
• Non-applied API schema: helper methods only, no prim modification (no apiSchemas list entry)
• Applied API schema: MyDataAPI.Apply(prim) — adds schema name to prim's apiSchemas list
• After applying: use MyDataAPI(prim).CreateMyAttrAttr(defaultValue) to author attributes

# schema.usda — defining a custom applied API schema
class "RenderTagAPI" (
    inherits = </APISchemaBase>
    customData = { token[] apiSchemaType = "singleApply" }
) {
    token render:tag = "default"
}

# Python: apply the API schema to any prim
from pxr import Usd
stage = Usd.Stage.CreateInMemory()
prim = stage.DefinePrim("/World/Cube", "Cube")

RenderTagAPI.Apply(prim)
api = RenderTagAPI(prim)
api.CreateRenderTagAttr().Set("proxy")
print(prim.GetAppliedSchemas())   # ["RenderTagAPI"]

File Format Plugins

File format plugins teach USD to open and save files in formats it doesn't natively support. Unlike schema plugins, file format plugins must be written in C++ only — Python is not supported for this plugin type.

• Implement SdfFileFormat subclass in C++
• Key methods: Read(layer, resolvedPath, metadataOnly), Write(layer, filePath, comment, args)
• Register in plugInfo.json with the file extension(s) your format handles
• USD will automatically invoke your plugin when opening files with that extension
• Use case: read proprietary binary formats, legacy ASCII formats, JSON/YAML scene descriptions
• Dynamic file format: a file format plugin that generates USD content procedurally based on arguments embedded in the asset path

// C++ — minimal SdfFileFormat subclass (header sketch)
class MyJsonFileFormat : public SdfFileFormat {
public:
    MY_API bool Read(
        SdfLayer* layer,
        const std::string& resolvedPath,
        bool metadataOnly) const override;

    MY_API bool WriteToString(
        const SdfLayer& layer,
        std::string* str,
        const std::string& comment = std::string()) const override;
};

// plugInfo.json entry for the file format
{
  "Plugins": [{
    "Type": "resource",
    "Name": "myJsonFormat",
    "Info": {
      "SdfFileFormat": {
        "Extensions": ["myjson"],
        "Target": "usd",
        "FormatId": "myJson"
      }
    }
  }]
}

Custom Model Kinds

USD has built-in kinds: component, assembly, group, subcomponent. Studios can register custom kinds that extend these for pipeline validation.

• Register custom kinds in plugInfo.json under a "Kinds" entry with parent kind specified
• Example: "hero_prop" extending "component" — validators then require hero_prop assets to carry specific attributes
• Access via Usd.ModelAPI: Usd.ModelAPI(prim).GetKind() / SetKind("hero_prop")

# plugInfo.json — registering a custom kind
{
  "Plugins": [{
    "Type": "resource",
    "Name": "studioKinds",
    "Info": {
      "Kinds": {
        "hero_prop": { "baseKind": "component" },
        "env_piece":  { "baseKind": "assembly" }
      }
    }
  }]
}

# Python — reading and setting kinds
from pxr import Usd, Kind
prim = stage.GetPrimAtPath("/World/Hero")
modelApi = Usd.ModelAPI(prim)
modelApi.SetKind("hero_prop")
print(modelApi.GetKind())   # "hero_prop"
print(Kind.Registry.IsA("hero_prop", "component"))  # True

Variant Fallback Selections

When no explicit variant selection is authored in any layer, USD uses variant fallback selections to provide default behavior. This prevents "empty" variant sets from leaving geometry incomplete.

• Set stage-wide fallback: stage.SetMetadata("variantSelections", {"lodVariant": "lo"})
• Can also be defined in plugInfo.json for environment-level defaults
• Resolver context can carry variant selection preferences per-render
• Useful for render farms: set "hi" LOD fallback for final renders, "lo" for playblasts

# Python — setting stage-wide variant fallback selections
from pxr import Usd
stage = Usd.Stage.Open("shot.usd")

# Stage-wide default: any unselected "lodVariant" defaults to "lo"
stage.SetMetadata("variantSelections", {"lodVariant": "lo"})

# Verify a prim's active variant selection
prim = stage.GetPrimAtPath("/World/Hero")
vs = prim.GetVariantSets()
sel = vs.GetVariantSelection("lodVariant")
print(sel)   # "lo" (from fallback if not explicitly authored)

Debugging: Stage Introspection

USD provides a full introspection API to diagnose composition. These methods are the first tools to reach for when attribute values are unexpected or prims are missing.

from pxr import Usd

stage = Usd.Stage.Open("complex_shot.usd")
prim = stage.GetPrimAtPath("/World/Hero")

# 1. X-ray the prim's composition
for spec in prim.GetPrimStack():
    print(spec.layer.identifier, "->", spec.path)

# 2. Diagnose a surprising attribute value
attr = prim.GetAttribute("displayColor")
for prop_spec in attr.GetPropertyStack():
    print(prop_spec.layer.identifier, "value:", prop_spec.default)

# 3. Find which layer's opinion won
resolve_info = attr.GetResolveInfo()
print("Source:", resolve_info.GetSource())
# Usd.ResolveInfoSourceDefault, TimeSamples, Fallback, NoValue

# 4. Check prim state
print("Active:", prim.IsActive())
print("Loaded:", prim.IsLoaded())
print("Has payloads:", prim.HasAuthoredPayloads())

Debugging: Composition Issues

Most debugging scenarios on the exam describe a symptom — a wrong value, a missing prim, a wrong variant — and ask what to do first. Match symptom to the right introspection tool.

• Wrong attribute value → attr.GetPropertyStack() to find all opinions, then identify the strongest spec
• Prim missing → check prim.IsDefined() and prim.IsActive(); check if payload is unloaded with prim.IsLoaded()
• Wrong variant selected → prim.GetVariantSets().GetVariantSelection("setName")
• Reference not resolving → check stage.GetUsedLayers(), check resolver search paths
• LIVERPS reminder: Local opinion always wins — if a local over exists on the prim, it beats all references, inherits, and variants
• UsdUtils.CoalescingDiagnosticDelegate: suppress redundant warning spam during debugging sessions

# Debugging workflow — unexpected variant behavior
prim = stage.GetPrimAtPath("/World/Hero")

# Step 1: which variant is actually active?
vs = prim.GetVariantSets()
active = vs.GetVariantSelection("lodVariant")
print("Active variant:", active)

# Step 2: look at all opinions on a suspicious attribute
attr = prim.GetAttribute("points")
stack = attr.GetPropertyStack()
for spec in stack:
    print(f"  [{spec.layer.identifier}] {spec.path} = {spec.default}")

# Step 3: is there a local override beating everything?
for spec in prim.GetPrimStack():
    if spec.HasInfo("active") or spec.HasInfo("specifier"):
        print(f"  Defining spec in: {spec.layer.identifier}")

Performance Optimization

Large USD scenes can be slow to load and traverse. These techniques are tested in both the Debugging and Customizing sections of the exam.

• Payload pruning: stage.Load() only paths in camera frustum; use stage.SetLoadRules() for fine control
• Prim population mask: Usd.StagePopulationMask — load only specific prim subtrees
• Layer muting: stage.MuteLayer(identifier) — exclude debugging layers in production
• Instance awareness: stage.Traverse() visits instances but not prototypes; use stage.GetPrototypes() separately
• Minimize timeSample density: use held interpolation where linear is unnecessary
• Flatten asset chains: avoid deeply nested references; flatten before publishing to reduce composition cost

from pxr import Usd

# Technique 1: Population mask — load only /World/Hero subtree
mask = Usd.StagePopulationMask(["/World/Hero"])
stage = Usd.Stage.OpenMasked("bigScene.usd", mask)
# Everything outside /World/Hero is excluded from composition

# Technique 2: Load rules — fine-grained payload control
rules = Usd.StageLoadRules()
rules.LoadAll()
rules.Unload("/World/Crowd")  # exclude crowd from loading
stage.SetLoadRules(rules)

# Technique 3: Mute a layer
layer_id = "debugging_overrides.usda"
stage.MuteLayer(layer_id)
print(stage.IsLayerMuted(layer_id))  # True

# Technique 4: Sparse traversal — skip inactive and unloaded prims
it = iter(stage.TraverseAll())
for prim in it:
    if not prim.IsActive():
        it.PruneChildren()
        continue
    process(prim)

Command-Line Debugging Tools

These tools are frequently tested — know what each one does and when to reach for it.

# Terminal examples

# Inspect a binary .usdc as if it were ASCII
usdcat hero_asset.usdc

# Run compliance checks
usdchecker shot_v03.usd
usdchecker --argsDict '{"rootLayerOnly": True}' shot_v03.usd

# Inspect prim hierarchy
usdtree complex_stage.usd

# Test asset resolver
usdresolve "omniverse://server/assets/hero.usd?v=latest"

# Open in interactive viewer
usdview shot_v03.usd