I85PREP
⌘ K
NCP-OUSD study materials
NCP-OUSD study resources

USDZ that only opens on the artist's machine

NCP-OUSD · Put your knowledge to work in context.

All case studies

USDZ that only opens on the artist's machine

A vendor delivers chair.usdz for AR review. On the artist's workstation, usdview chair.usdz opens and shows the chair. On the review machine, usdview reports unresolved references and the stage is empty. usdchecker --arkit chair.usdz fails with a missing default prim and lists absolute asset paths under /Users/vendor/chair_project/.... The package contains chair.usda, geo/seat.usdc, geo/legs.usdc, and textures/wood.png. The root layer references the geometry with absolute paths and uses a texture path written as textures\\wood.png. The root prim is /Chair, but no defaultPrim metadata is authored. The vendor says it works locally and asks for a quick fix. The review team must produce a portable package that passes ARKit validation and preserves the reference structure rather than flattening everything.

1. Diagnose why the package opens locally but not on the review machine, and explain each validator complaint.

Read the worked answer

The package is not self-contained. The absolute paths under /Users/vendor/chair_project/... resolve only on the vendor's machine, where those files exist on disk. On the review machine those paths are absent, so the references cannot resolve and the stage is empty. Inside a USDZ package, asset paths must resolve within the package; a USDZ cannot rely on arbitrary filesystem paths outside it.

The missing default prim is a separate packaging error. usdchecker --arkit expects the package root layer to declare a defaultPrim so a consumer can identify the asset's root without knowing the prim hierarchy. The root prim /Chair exists, but without defaultPrim = "Chair" the package is ambiguous and ARKit validation rejects it.

The backslash in textures\\wood.png is also non-portable. USD asset paths use forward slashes, and a backslash can be interpreted as a literal filename character or fail to resolve on non-Windows systems. It should be authored as textures/wood.png.

The local success is therefore misleading: the artist is validating against a developer filesystem layout, not against the packaged, portable layout that the review machine sees.

2. Give a concrete repair procedure to make the package portable and ARKit-compliant while preserving references.

Read the worked answer

A safe repair keeps the layered reference structure and fixes the packaging inputs.

  1. Open the root layer and author defaultPrim = "Chair" on it so the package has an explicit asset root.
  2. Inventory the real dependencies with UsdUtils.ComputeAllDependencies (or equivalent dependency walking) starting from the root layer. Confirm that geo/seat.usdc, geo/legs.usdc, and textures/wood.png are all inside the intended package root.
  3. Rewrite every asset path to a package-relative path, for example geo/seat.usdc and textures/wood.png. Use forward slashes. UsdUtils.ModifyAssetPaths can rewrite asset paths on a stage; alternatively, re-author the references and shader inputs with relative paths. Do not leave any absolute /Users/... path.
  4. If textures are referenced through UsdShade inputs, check those asset-valued inputs as well as prim references. A package can fail because a shader input points outside the package even when geometry references are correct.
  5. Rebuild the package with usdzip, placing the root layer and all dependencies under the package root. Keep the same relative layout that the rewritten paths expect.
  6. Validate with usdchecker --arkit on a clean machine or clean environment, then open with usdview from the package rather than from the source directory. Test both geometry and textured appearance.

Flattening can hide the problem by baking the composed result, but it discards the reference structure and may change material or variant behavior. The repair should fix paths and metadata instead.

3. The vendor cannot change the source files in time. Can the review team repackage the asset themselves? Explain the limits of that approach.

Read the worked answer

Yes, but only if the review team has access to all the referenced source files. They can open the vendor's stage in an environment where the absolute paths resolve, author a new root layer with the correct defaultPrim, rewrite asset paths to relative paths, and package that new root plus the dependencies. This is a repackaging operation, not a repair of the vendor's originals.

The limits are important:

  • If a referenced file is missing from the vendor's delivery and only exists on the vendor's machine, the review team cannot make it portable without obtaining the file. A missing dependency cannot be fixed by path rewriting alone.
  • Repackaging must include every dependency at the exact relative path used by the rewritten references. A texture referenced by a shader input but not copied into the package will still fail.
  • The review team should record that the package was repackaged and may differ from the vendor's source. If provenance matters, the vendor should fix and re-deliver.
  • A temporary resolver or search path can make usdview work on the review machine, but it does not make the USDZ portable. Validation must be done on the package as delivered, with no external search paths that mask missing dependencies.

The quickest reliable fix is to obtain the missing source files, set defaultPrim, rewrite paths to relative forward-slash paths, repackage, and validate with usdchecker --arkit in a clean environment.