External File References
Severity: 🔴 Error
Fixable: ❌ Not Fixable (requires re-export)
Prevalence: 🔹 Low
Summary
Section titled “Summary”The USD file contains references to external files (textures, other USD files) using paths that won’t resolve on the target device or in a sandboxed environment.
Evidence
Section titled “Evidence”Community Reports
Section titled “Community Reports”TODO: Add specific forum/Stack Overflow links
When It Occurs
Section titled “When It Occurs”- Files using relative texture paths like
@./textures/wood.png@ - Files referencing other USD files not bundled together
- Files exported for local preview but deployed to device
Root Cause
Section titled “Root Cause”USD supports powerful file referencing and layering:
@path/to/file.usd@for sublayer/reference inclusion@path/to/texture.png@for asset paths
These work in desktop environments with matching file structures, but fail when:
- Deployed to iOS/visionOS (sandboxed)
- Shared without the referenced files
- Paths are absolute and machine-specific
Detection
Section titled “Detection”File: PreflightCore/USDClient.swift
TODO: Implement external reference detection
Solution
Section titled “Solution”Prevention: Use USDZ
Section titled “Prevention: Use USDZ”Package your USD as .usdz which bundles all assets:
usdzip -r output.usdz input.usda textures/Prevention: Flatten Stage
Section titled “Prevention: Flatten Stage”Export a flattened version with all references resolved:
from pxr import Usdstage = Usd.Stage.Open("input.usda")stage.Flatten().Export("flattened.usda")Validation
Section titled “Validation”Related Issues
Section titled “Related Issues”- Missing Default Prim - Another structural issue
Changelog
Section titled “Changelog”| Date | Change |
|---|---|
| 2024-12-18 | Stub created |