Surgical Mapping

Preflight is not just a viewport; it is a closed-loop repair system. Every diagnostic result aims to point toward a specific “Surgery” or a manual DCC correction.

The Surgery Count

As of current implementation, Preflight contains 18 distinct Surgical Tools (FixActions) capable of modifying USD session layers non-destructively.

---

Detection-to-Surgery Matrix

This table shows exactly which diagnostic warning triggers which surgical tool in the Preflight Agent.

Diagnostic Issue	Category	Suggested Surgery	Automation
Missing Default Prim	Loadability	fix:setDefaultPrim	✅ One-Click
Skeleton Path Mismatch	Animation	fix:remapSkeleton	✅ One-Click
Static Keyframes	Animation	fix:makeRCPReady	✅ One-Click
Z-Up Axis Mismatch	Scale	fix:setUpAxis:Y	⚠️ Advisory
Missing UV Coordinates	Materials	fix:addUVs	⚠️ Destructive
Missing Material Binding	Materials	fix:assignMaterial	✅ One-Click
Missing MaterialBindingAPI on bound prim	Materials	fix:applyMissingSchema (MaterialBindingAPI)	✅ One-Click
Empty material binding relationship	Materials	fix:assignMaterial	✅ One-Click
Broken material binding target (missing prim)	Materials	fix:assignMaterial	✅ One-Click
Material binding target is not Material type	Materials	fix:assignMaterial	✅ One-Click
MetersPerUnit Mismatch	Scale	fix:setMetersPerUnit	✅ One-Click
Missing upAxis metadata (strict profile)	Scale	fix:setUpAxis:Y	✅ One-Click
Unresolved Resource	Dependency	fix:cleanupRef	✅ One-Click
Wrong Shader Input Type	Materials	fix:fixShaderPropertyType	✅ One-Click
Primvar reader inputs:varname token/string mismatch	Materials	fix:fixShaderPropertyType	✅ One-Click
Nested Shader Prim	Materials	fix:flattenNestedShader	✅ One-Click

---

How Solutions are Proposed

The Preflight system uses a three-tier logic to propose workflows:

1. The Critical Path (Fix Plans)

The AI Agent doesn’t just list fixes; it creates an Ordered Fix Plan. It follows a strict dependency logic found in the internal Knowledge Base:

1. Stage Sanity: Fix defaultPrim first (allows QuickLook/RCP to even open the file).
2. Space & Scale: Adjust upAxis and metersPerUnit so the model is oriented correctly.
3. Visual Finish: Apply UVs and Materials.
4. Functional Sync: Finally, resolve Skeleton Path Mismatch to enable animation.

2. Workflow Orchestration

For complex issues like skeletal remapping from Mixamo, the system proposes a Workflow Object.

• Step 1: Identify the mismatched prefix (e.g., mixamorig:).
• Step 2: Preview the remapped joint hierarchy.
• Step 3: Commit the remapping to the session layer.

3. The “Line of Automation”

We bridge the gap between AI automation and human artistic choice:

• Auto-Fixable: Low-risk metadata changes (Standardized orientations, scales, default prims).
• Assisted Surgery: Actions that require user input (Picking which joint is the new root).
• DCC Required: Situations where the USD format cannot fix the underlying issue (e.g., PointInstancers must be collapsed in Blender/Maya).

---

Engine Specifications

For a detailed technical breakdown of every validation heuristic and surgical capability, see the Engine Statistics reference.

• Diagnostic Checks: 28 distinct validation heuristics.
• Surgical Actions: 18 implementation-ready fixes.
• Automation Ratio: ~70% of common RealityKit load failures are one-click repairable.

Validator Sources

Preflight uses multiple validation sources and normalizes them into one diagnostics stream:

• Custom RealityKit-focused validators (primary).
• Internal strict OpenUSD-style checks (in-process, no external usdchecker subprocess dependency).
• Optional reference mapping to usdchecker validator IDs for parity analysis/documentation.

When multiple sources detect the same issue, Preflight resolves them into a single canonical diagnosis with deterministic precedence (severity, fix availability, then source) so plan generation and health scoring stay consistent.