| name | vfx-usd |
| description | Author and inspect Pixar Universal Scene Description (USD) files: usdcat (print/convert between .usda ASCII / .usdc crate binary / .usdz package), usdview (interactive Qt viewer), usdedit (round-trip edit via ASCII), usdzip (create/inspect .usdz AR packages), usdrecord (offline Hydra render to image sequence), usdresolve (asset path resolution), usdtree (stage hierarchy), usdchecker (validate schema + packaging), usddiff (structural diff), usdstitch / usdstitchclips (value-clip assembly), usdGenSchema (generate schema bindings). Core concepts: Stage, Layer, Prim, Attribute, Relationship, Composition Arcs (sublayer/reference/payload/inherit/specialize/variantSet - LIVRPS strength ordering). Schemas: UsdGeom, UsdLux, UsdShade, UsdSkel, UsdPhysics, UsdMedia, UsdRender, UsdVol, UsdUI. Docs at openusd.org/release/. Use when the user asks to work with USD files, convert between USD flavors, render a USD scene, validate USD for Apple AR delivery (.usdz), or author USD programmatically.
|
| argument-hint | [action] |
Vfx Usd
Context: $ARGUMENTS
Quick start
- Convert between .usda / .usdc / .usdz: -> Step 1 (
usd.py cat)
- Inspect a stage hierarchy: -> Step 2 (
usd.py info)
- Validate for delivery (Apple .usdz, studio pipeline): -> Step 3 (
usd.py validate)
- Render a frame sequence from a stage: -> Step 4 (
usd.py record)
- Pack a folder of assets into .usdz: -> Step 5 (
usd.py zip)
- Diff two stages: -> Step 6 (
usd.py diff)
- Resolve an asset path: -> Step 7 (
usd.py resolve)
- Interactive viewer: -> Step 8 (
usd.py view)
- Assemble value clips: -> Step 9 (
usd.py stitch-clips)
When to use
- User mentions Pixar USD, OpenUSD, .usd/.usda/.usdc/.usdz files, Hydra rendering, AR asset export.
- Validating a USD for Apple Quick Look AR delivery (.usdz).
- Converting between ASCII (.usda) and binary (.usdc) crate forms.
- Rendering an offline image sequence from a camera prim.
- Inspecting composition arcs (sublayer/reference/payload/inherit/specialize/variantSet).
Step 1 — Convert between USD formats
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py cat --in scene.usdc --out scene.usda
Under the hood:
usdcat scene.usdc -o scene.usda
Use --flatten to resolve all composition arcs into a single layer (baking references/payloads/variants into the output):
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py cat --in scene.usda --flatten --out scene_flat.usda
Format is auto-detected from the output extension: .usda -> ASCII, .usdc -> crate binary, .usdz -> package.
Step 2 — Inspect a stage
Hierarchy + attribute summary:
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py info scene.usda
Runs both:
usdtree scene.usda
usdchecker scene.usda
Step 3 — Validate
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py validate scene.usdz
Expands to:
usdchecker --strict scene.usdz
For Apple AR Quick Look .usdz delivery, add --arkit:
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py validate --arkit model.usdz
Step 4 — Offline render (Hydra)
Render N frames through a named camera prim, write to PNG sequence:
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py record \
--in scene.usda \
--camera /World/MainCam \
--out render.####.png \
--frames 1-240
Expands to:
usdrecord --camera /World/MainCam --frames 1:240 scene.usda render.####.png
Options: --imageWidth 1920, --renderer Storm|Embree|Arnold|Karma|RenderMan.
Step 5 — Zip / unzip a .usdz package
Pack a folder (root layer + referenced textures) into .usdz:
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py zip --dir ./asset/ --out asset.usdz
Extract contents:
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py unzip --in asset.usdz --dest ./asset/
Under the hood: usdzip, or on extract unzip / Python's zipfile (.usdz is just a zip).
Step 6 — Diff two stages
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py diff a.usda b.usda
Expands to usddiff a.usda b.usda. Structural diff — compares opinions by spec path, not line-by-line text.
Step 7 — Resolve an asset path
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py resolve "./textures/diffuse.<UDIM>.png"
Expands to usdresolve "./textures/diffuse.<UDIM>.png". Honors the current PXR_PLUGINPATH_NAME / USD_RESOLVER configuration. Useful for verifying that asset path templates resolve correctly in your pipeline.
Step 8 — Interactive viewer
Launch usdview on a stage:
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py view scene.usda
Requires Qt/PySide display; blocks until you quit. Skip on headless CI.
Step 9 — Stitch value clips
Animated "value clips" decouple per-frame layer swaps from the root layer. Build a manifest:
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py stitch-clips \
--clips-dir ./clips/ \
--topology topology.usd \
--out manifest.usd
Expands to usdstitchclips --clipPath /Set --templatePath ./clips/frame.####.usd --startTimeCode 1 --endTimeCode 240 --out manifest.usd.
Gotchas
- Canonical docs live at
https://openusd.org/release/, NOT /docs/. The /docs/ path returns 404. Pages you care about: /release/index.html, /release/intro.html, /release/glossary.html, /release/toolset.html, /release/tut_usd_tutorials.html. Quickstart PDF at /files/USD_Quickstart_Guide.pdf.
- Only four file extensions are canonical:
.usd (generic — auto-picks crate or ASCII at read time), .usda (explicitly ASCII), .usdc (crate binary), .usdz (zip package). .usdnc is NOT a standard Pixar extension — don't recommend it.
- Composition arcs have a strict strength order: LIVRPS
Local > Inherits > VariantSets > References > Payloads > Specializes. Stronger opinions override weaker ones. This is the most common pipeline footgun ("my edit isn't showing up" = there's a stronger opinion elsewhere).
.usdz is just a ZIP with zero compression and specific alignment. The alignment is what usdzip does that plain zip cannot — do NOT build .usdz with plain zip, Quick Look will reject it.- Apple's
--arkit validator is stricter than default. Rejects PBR textures outside 8-bit range, requires triangulated meshes, limits shader support to UsdPreviewSurface. Always re-validate with --arkit before Apple submission.
- Tool list verified from
openusd.org/release/toolset.html: usdcat, usdview, usdedit, usdzip, usdrecord, usdresolve, usdtree, usdchecker, usddiff, usdstitch, usdstitchclips, usdGenSchema, usdgenschemafromsdr. No "usdconv" or "usdexport" — those are NOT official tools.
- Schema docs split between user-guides and Doxygen API: UsdLux, UsdMedia, UsdRender, UsdUI, UsdVol have TOCs on
/release/. UsdGeom, UsdShade, UsdSkel, UsdPhysics only have API pages like . Read for one-liner summaries.
Examples
Example 1: "Convert a binary crate to ASCII for git diffs"
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py cat --in scene.usdc --out scene.usda
Example 2: "Validate this .usdz for Apple Quick Look"
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py validate --arkit model.usdz
Example 3: "Render frames 1-120 from the hero camera"
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py record \
--in shot.usda --camera /Render/Cameras/hero \
--frames 1-120 --out shot.####.png \
--imageWidth 1920 --renderer Storm
Example 4: "Pack this asset folder into a shareable .usdz"
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py zip --dir ./hero_prop/ --out hero_prop.usdz
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py validate --arkit hero_prop.usdz
Example 5: "Flatten all composition into one file for a hand-off"
uv run ${CLAUDE_SKILL_DIR}/scripts/usd.py cat --in shot.usda --flatten --out shot_flat.usda
Troubleshooting
Error: usdcat: command not found
Cause: USD runtime isn't installed / not on PATH.
Solution: Install via NVIDIA's build, brew install usd-core, pip install usd-core (limited Python bindings), or build from source at github.com/PixarAnimationStudios/OpenUSD.
Error: usdchecker --arkit FAILED
Cause: Apple-specific constraint (often non-triangulated mesh, missing UsdPreviewSurface, wrong texture color space, non-1-meter scale).
Solution: Read the error; common fixes: triangulate in DCC before export, convert all shaders to UsdPreviewSurface, embed textures, set metersPerUnit=1.
.usdz opens in finder but not Quick Look
Cause: Built with plain zip (wrong alignment) or includes a directory entry.
Solution: Rebuild with usdzip, not zip. Don't include __MACOSX/ or .DS_Store.
Error: Layer version too new
Cause: .usdc written by a newer USD runtime than the reader.
Solution: Convert sender-side: usdcat new.usdc -o old.usda. Or upgrade reader.
My override isn't showing up
Cause: Stronger opinion exists up the LIVRPS chain.
Solution: Use usdview → Composition tab, or usd.py info, to find who's "winning". Often a variantSet or specializes arc is overriding your layer.
usdrecord hangs on first frame
Cause: Hydra renderer loading plugins. Some renderers (Arnold) take 10-30s on first invocation.
Solution: Wait. Pre-warm by rendering a tiny scene first, or switch to Storm (--renderer Storm) for speed.
Reference docs
- Core concepts cheatsheet (Stage / Layer / Prim / Attribute / Relationship / Composition Arcs / LIVRPS) -> [
references/concepts.md]
- Schema one-liners (UsdGeom / UsdLux / UsdShade / UsdSkel / UsdPhysics / UsdMedia / UsdRender / UsdVol / UsdUI) -> [
references/schemas.md]
