usd-inspect-and-provenance

name	usd-inspect-and-provenance
description	Inspect a Blender-exported or supplied USD stage for composition, transforms, units, materials, cameras, render products, semantics, and physics while retaining source-to-derived provenance. Use before OVRTX/OVPhysX handoff, when a render looks wrong, or when a flattened package must be audited without mutating the original.
license	Apache-2.0
metadata	{"author":"Max Bickley","version":"0.1","team":"omniverse","domain":"physical-ai","tags":["blender","omniverse","ovrtx","usd"]}

USD inspection and provenance

Inspection is read-only. Use a copied package and write reports under a caller-selected cache directory. The OVRTX/OVPhysX add-on and runtime are installed dependencies; this skill uses documented Blender/USD tools and their supported UI/CLI entry points.

When to Use

Use this skill when inspect a Blender-exported or supplied USD stage for composition, transforms, units, materials, cameras, render products, semantics, and physics while retaining source-to-derived provenance. Use before OVRTX/OVPhysX handoff, when a render looks wrong, or when a flattened package must be audited without mutating the original.

Freeze identity

1. Hash every supplied .blend, .usd, .usda, .usdc, .usdz, texture, sidecar, and script before inspection. Record absolute paths only in a local report; use relative paths in shareable manifests.
2. Record Blender, add-on, USD utility/DCC, runtime, platform, camera, frame, and export options. Name the stage under test (source, localized, or flattened) and never overwrite a source file.
3. If the stage was generated by the add-on, retain its generation metadata and Blender-object-to-USD-prim mapping. A successful render does not prove the stage is current or that bindings are correct.

Instructions

Run scripts/inspect_usd.py through Blender's bundled Python when standalone pxr is unavailable. It emits a read-only usd_stage_inspection.v1 result and checks composition dependencies, stage metadata, prim identity, finite transforms, and mesh topology. For example:

blender --background --python scripts/inspect_usd.py -- \
  --stage /absolute/caller-owned/scene.usdc --require-resolved

Use usdcat, usdchecker, a DCC inspector, or the add-on's documented validation action for additional schema-specific checks. Check:

• layer stack, sublayers, references, payloads, clips, variants, relocates, asset paths, and unresolved external files;
• default prim, stable absolute prim paths, active/inactive and visibility state, instance/prototype relationships, and duplicate identities;
• upAxis, metersPerUnit, time codes, frame rate, authored samples, reset stack, finite transforms, and representative world-space bounds;
• mesh topology/points/indices, normals, UV primvars and interpolation;
• material bindings/GeomSubsets, texture paths and color spaces, OpenPBR or preview-surface networks, lights, camera projection/intrinsics/DOF, and render product/output-variable children;
• UsdPhysics, collider, mass/inertia, semantic/instance/ID schemas, and custom properties when the handoff claims them.

Inspect both authored and evaluated/exported geometry where possible. Missing evaluated modifiers or a stale generated overlay are stage failures, not merely look-dev differences.

Provenance and closure

Build a dependency table with each layer/asset path, resolved copied path, kind, SHA-256, and status (present, missing, external, unresolved). Compare source and derived stage identity and record every operation (export, localize, flatten, path rewrite, metadata policy). Preserve both localized and flattened variants when flattening changes opinions. Do not silently rotate or rescale geometry because metadata appears surprising; compare representative transforms first and report any corrective policy explicitly.

Acceptance

Pass requires all required dependencies resolved, no non-finite transform or identity errors, expected bindings/products present, and unchanged source hashes. blocked means an inspector, optional USD schema, add-on export, or runtime capability is unavailable; report the exact capability and continue only with checks that remain valid. A preview rendered by Blender is not proof of OVRTX ownership; label render class explicitly. Return the failed checks and relevant stage/dependency paths. Create a full JSON inventory only for batch or reproducible handoff. Keep absolute paths and raw diagnostics local and sanitize anything shared.