Surgical Toolbox

Preflight’s “Surgery Engine” uses Session Layers to apply non-destructive edits on top of your USD files. No changes are written to disk until you explicitly export.

While many of these actions can be applied automatically via the Diagnostic engine, you can also perform manual adjustments using the Inspector.

This is the complete registry of all available FixAction operations in the Preflight validation engine.

📐 Geometry & Scene Structure

Action ID	Description	Impact
fix:setUpAxis	Rotates the stage root -90° X to match RealityKit’s Y-Up coordinate system.	Updates stage metadata.
fix:setDefaultPrim	Designates a prim as the root anchor. Essential for QuickLook and RealityKit auto-loading.	Metadata only. Safe.
fix:setMetersPerUnit	Updates the scaling metadata (e.g., 0.01 for cm to 1.0 for meters).	Metadata only. Does not resize geometry.
fix:setDoubleSided	Flags specific meshes (doubleSided = true) to disable backface culling.	Renders both sides of the mesh.
fix:setSubdivisionScheme	Sets subdivision mode (e.g., to none or catmullClark).	Affects tessellation.
fix:addUVs	Generates Planar (XZ) texture coordinates for meshes missing UVs.	Destructive. Modifies geometry. Emergency use only.

🦴 Animation & Rigging

Action ID	Description	Impact
fix:remapSkeleton	Rebases animation joint paths to match a skeleton hierarchy (e.g., strips /Armature/ prefixes).	Essential for fixing Mixamo/Blender exports.
fix:mergeSkeletons	Combines fragmented root joints into a single SkelRoot.	Fixes FBX imports with multiple skeleton roots.

🎨 Materials & Textures

Action ID	Description	Impact
fix:assignMaterial	Binds a material path (e.g., /Materials/Steel) to a specific mesh prim.	Fixes “Pink Mesh” missing bindings.
fix:setTexture	Swaps a texture file path (e.g., .png → .ktx2) for a specific shader input.	Used for optimization.
fix:flattenNestedShader	Moves shaders defined inside mesh scopes to a global /Materials scope.	Enables instancing and reduces draw calls.
fix:fixShaderPropertyType	Casts a shader input value to the correct type (e.g., float to color3f, token to string for primvar names).	Prevents renderer/toolchain type coercion differences and improves round-trip stability across DCCs and runtimes.

🛠 Advanced & Utility

Action ID	Description	Impact
fix:makeRCPReady	Adds Reality Composer Pro metadata (Timeline, Behaviors, Components).	Prepares file for RCP editing.
fix:cleanupMissingReference	Removes USD references pointing to missing files.	Prevents load errors.
fix:applyMissingSchema	Adds a specific USD API schema (e.g., PhysicsRigidBodyAPI, MaterialBindingAPI) to a prim.	Makes authored relationships/schema usage explicit and portable across stricter validators, tools, and runtime parsers.
fix:applyAll	Automatically executes all safe, deterministic fixes found in validation.	Batch repair.

---

CLI Reference

All surgery tools can be invoked via the preflighttool binary for CI/CD pipelines.

Syntax

preflighttool surgery <command> <input_file> [args...]

Command Map

Internal Action	CLI Command	Example Arguments
remapSkeleton	remap-skeleton	--from "/Armature" --to "/root"
mergeSkeletons	merge-skeletons	(no args)
setUpAxis	fix-axis	Y
setMetersPerUnit	set-scale	0.01
makeRCPReady	make-rcp-ready	(no args)
setDefaultPrim	set-default-prim	"/root"
addUVs	add-uvs	"/root/Mesh"
assignMaterial	bind-material	"/root/Mesh" "/Materials/Mat1"
applyAll	apply-all	(no args)
cleanupMissingReference	cleanup-ref	"/path/to/missing/file.png"
applyMissingSchema	apply-schema	"/root" "PhysicsRigidBodyAPI"
setDoubleSided	set-double-sided	"/root/Mesh" true
setSubdivisionScheme	set-subdivision-scheme	"/root/Mesh" "none"
flattenNestedShader	flatten-nested-shader	"/root" "/root/Mesh/Shader"
setTexture	set-texture	"/root/Mesh" "diffuseColor" "new.png"
fixShaderPropertyType	fix-shader-type	"/root/Shader" "input" "color3f"