Instruction file imported from NVIDIA-Omniverse/aif-pipeline-samples (.cursor/rules/usd-universal.mdc). Copyright stays with the author.

USD Quality Rules

Three tiers: Core Quality (valid, clean USD), SimReady Compliance (standardized assets per the SimReady spec), and AIF-specific (covered in .cursor/rules/usd-aif-profile.mdc).

Agent Behavior

When a user reports a USD quality issue or a validation rule failure:

1. Identify the rule name from their validation output (e.g., NormalsExistChecker, ExtentsChecker).
2. Check the Quick Lookup table below first for the most common failures.
3. For less common rules, scan the Symptom-to-Fix tables in the sections that follow.
4. If multiple fixes are needed, compose them into a preset respecting the operation ordering in .cursor/rules/scene-optimizer-presets.mdc.
5. Re-validate after applying fixes to confirm resolution.
6. If a rule is not in these tables, check .cursor/rules/usd-issues-catalog.mdc for known patterns.

Quick Rule-to-Operation Lookup

For the most common validation failures, here are direct fixes:

Symptom → Fix Reference

Use these tables to map a problem to its Scene Optimizer fix. For the full validation rule catalog, see the end of this file.

Geometry Issues

Material Issues

Hierarchy & Stage Issues

Performance Issues

SimReady Compliance

A technically valid USD file is not necessarily useful for simulation. A mesh with a million triangles is valid USD, but it's a performance nightmare in real-time physics. SimReady adds the rules that define what's good for simulation, not just what's technically possible.

Three-layer architecture:

• OpenUSD — the open-source technology (Pixar) providing the file format and composition engine
• AOUSD — the Alliance for OpenUSD, creating formal standardization rules
• SimReady — the content specification layer that defines how to structure data for geometry, materials, and physics so tools can understand, validate, and use it

Profile-based compliance: Assets don't conform to "all of SimReady" — that's not a thing. Instead, an asset conforms to a specific profile: a named, versioned bundle of features for a particular job (e.g., physics-ready prop, articulated robot, placeable visual). Profiles can be neutral (any runtime) or runtime-specific (e.g., Isaac Sim).

Spec model: Requirements (atomic checkable rules) → Capabilities (grouped requirements) → Features (runtime-specific bundles) → Profiles (complete workflows).

Stage Requirements

Hierarchy Requirements

Feature Validation

# Validate against a specific SimReady feature
aif-pipeline validate input/ output/ --feature minimal_placeable_visual

Optional SimReady Capabilities

These rules validate domain-specific capabilities (not required for all assets):

Physics Validation (Optional)

Library Scripts Quick Reference (so/generic/lib/)

Operation Ordering

Follow this order (same as so/generic/generic_preset.json):

1. editStageMetrics — Normalize units and orientation first
2. pythonScript (split_non_composed_by_geom_subsets.py) — Split GeomSubset meshes before dedup
3. pythonScript (deduplicate_hierarchies_by_display_name.py) — Dedup hierarchy branches
4. meshCleanup — Fix topology before decimation
5. decimateMeshes — Reduce polygon count
6. generateNormals — Regenerate after geometry changes
7. optimizeMaterials (mode 2) — Deduplicate materials
8. deduplicateGeometry — Instance identical meshes
9. pruneLeaves — Remove empty nodes from dedup
10. optimizePrimvars — Clean up unnecessary data
11. optimizeMaterials (mode 0) — Final material consolidation
12. pythonScript (validate_fix_material_binding_api.py) — Fix dangling bindings
13. removeSmallGeometry — Remove degenerate geometry
14. pruneLeaves — Second pass cleanup
15. computeExtents — Always last

Key ordering rules:

• Stage metrics MUST be first
• GeomSubset split MUST precede dedup
• Cleanup MUST precede decimation
• Normals MUST follow decimation
• Extents MUST be last
• Prune after dedup and after small geometry removal (two passes)
• Material dedup before geometry dedup
• MaterialBindingAPI fix after material operations

Running Validation

# OAV standalone (no Kit/GPU required) - AIF category
uv run --directory oav validate --category AIF /path/to/asset.usd
uv run --directory oav validate --rule AIFMetadataChecker /path/to/asset.usd

# Kit-based validation (full rule set including performance rules)
aif-pipeline validate input/ output/
aif-pipeline validate input/ output/ --feature minimal_placeable_visual
aif-pipeline validate input/ output/ --fine-grained  # per-rule timing

OAV runs a subset of rules standalone (no GPU). Kit validation runs the full catalog including performance rules (Usd:Performance, Omni:Geometry) with optional Scene Optimizer C-accelerated implementations.

Quick Diagnosis Flow

1. Run validation (OAV or Kit-based) → identifies specific rule failures
2. Map each failure to the symptom→fix tables above
3. Order the fixes per the operation ordering section
4. Compose a preset or run operations individually

See .cursor/rules/scene-optimizer-presets.mdc for how to compose fixes into a preset JSON.