AutoGineer
Generated banner for Omniverse Usd Performance Tuning
Generated logo for Omniverse Usd Performance Tuning

Omniverse Usd Performance Tuning

OpenAIOfficialCreated by NVIDIA OmniverseDistributed by OpenAI

  • Skill
  • Workflow
  • Software development
  • Apache-2.0
  • Medium risk
  • Has scripts
Download ZIP

From the author

Top-level workflow skill for USD performance diagnosis and optimization. Use for slow loading, high memory, low FPS, or 'optimize my scene' requests; delegates auth/runtime setup to Phase 0 owners.
— the description by NVIDIA Omniverse

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The omniverse-usd-performance-tuning skill provides a structured, end-to-end procedure for addressing performance bottlenecks in USD assets. It manages the lifecycle of performance tuning, from initial runtime context setup and baseline profiling to composition auditing, validation, and targeted scene optimization. The skill enforces a rigorous milestone-based approach, ensuring that all destructive operations are planned and approved, and that performance improvements are verified through comparative profiling and standardized reporting.

What it does

  • Orchestrates the end-to-end USD performance tuning lifecycle.
  • Validates runtime environments and handles authentication for remote assets.
  • Conducts composition audits and structural assessments of USD stages.
  • Executes validated optimization operations using Scene Optimizer.
  • Generates structured optimization reports comparing baseline and post-optimization metrics.
  • Enforces safety gates for destructive operations and mutation.

When to use it

  • When a USD scene exhibits slow loading times or low frame rates.
  • When memory usage is excessively high or GPU crashes occur.
  • When you need to optimize a scene for better interactivity or performance.
  • When you need to diagnose CAD conversion quality issues.
  • When you need to validate a scene before and after applying optimizations.

Advantages

  • Ensures consistent performance diagnosis through a standardized workflow.
  • Prevents accidental data loss by requiring approval for destructive operations.
  • Provides clear, evidence-based reporting on performance improvements.
  • Integrates seamlessly with existing Omniverse validation and optimization tools.
  • Maintains strict separation between diagnosis, planning, and execution phases.

Usage examples

“This USD scene loads very slowly; please triage what I should check first.”
The agent will initiate the runtime context gate, perform a composition audit, and provide a structured plan to identify the source of the slow load time.
“Optimize my CAD scene for better performance.”
The agent will verify the runtime, assess the CAD conversion quality, and propose a milestone-based optimization plan including validation and profiling.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/openai/omniverse-usd-performance-tuning/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip omniverse-usd-performance-tuning.zip -d .agents/skills

Documentation by NVIDIA Omniverse

Omniverse USD Performance Tuning

<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->

<!-- SPDX-License-Identifier: Apache-2.0 -->

When to Use

Use this workflow for broad performance asks such as slow loading, high memory, low FPS, GPU crashes, conversion-quality triage, or generic requests to optimize a USD scene.

Instructions

  1. Start from the mandatory runtime context gate before producing tuning output, unless the prompt is only asking for a static classification test.

  2. Classify broad optimization requests as ready_to_plan; reserve approval_required for prompts that explicitly name a destructive operation to execute before planning.

  3. Plan the full canonical chain through optimization-report, preserving the structured milestone order and the profile-stage:baseline / profile-stage:after labels when listing milestones.

  4. Invoke downstream skill bodies only when their phase is reached, and keep raw runtime artifacts on disk while reading compact summaries.

Frontmatter keeps version and tools at top level for agentskills.io runtime compatibility. NVCARPS discoverability fields live under metadata.

Output Format

Return a plan or status summary that names the selected entry skill, uses ready_to_plan for generic optimization requests, includes the full milestone chain through optimization-report, and labels profile phases as profile-stage:baseline and profile-stage:after. For structured outputs, the broad-optimization milestone subsequence is omniverse-usd-performance-tuning -> profile-stage:baseline -> usd-structure-assessment -> usd-validation-runner -> restructure-decision -> apply-restructure -> so-run-validators -> so-interpret-validators -> so-run-operations -> profile-stage:after -> compare-profiles -> optimization-report. End-to-end execution should produce an optimized stage when mutation runs and a report conforming to the optimization-report reference's schema (scripts/optimization-report.schema.json within that reference).

Use this workflow for broad performance asks such as slow loading, low FPS, high memory, GPU crashes, conversion quality, or "optimize my scene."

Entry skill rule

This skill is the named entry point for broad performance work whenever the agent has any verified way to do that work. Runtime probing details live in setup-usd-performance-tuning; this rule only decides which skill owns the user-facing performance request.

  • If the setup probe shows any verified runtime path - Kit, standalone, or even a partial stack such as Asset Validator only - enter here. If the user's requested tool is missing, return the specific blocked_code (blocked_missing_scene_optimizer, blocked_missing_so_operation, etc.) instead of substituting another workflow.

  • Enter at setup-usd-performance-tuning only when no runtime path is verified and runtime choice/setup is the first unresolved problem.

  • For omniverse:// assets, enter at omniverse-authentication first. Authentication precedes setup and triage for remote assets.

The decision is about ownership, not order. Setup, authentication, and triage all run in their normal phase order; this rule only fixes which skill the agent names as the entry skill in its response.

Runtime context — session-start gate (mandatory)

Before any other tuning output, follow the mandatory session-start gate in skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md. That reference owns output_path, the canonical setup-preflight.json location, Format A/Format B, and the "do not improvise a silent probe" anti-pattern.

Required outcomes:

  • Missing or unreadable preflight: invoke setup-usd-performance-tuning.

  • Present preflight: print Format A and wait for the user to choose Continue, Change Kit, Switch to standalone, or Re-run probe.

  • Confirmed runtime in the same session: use compact Format B for follow-up status.

[Kit: {runtime_context.kit.application} {runtime_context.kit.version}  |  SO: {runtime_context.sceneOptimizer.version}  |  AV: {runtime_context.assetValidator.version}]

Runtime artifact token budget

Before reading Kit logs, Asset Validator CSVs, Scene Optimizer logs, Tracy CSVs, or other runtime output, follow references/runtime-artifact-token-budget.md. Keep raw artifacts on disk, read summary JSON first, and use bounded log snapshots instead of full dumps or live streams.

Plan-time vs execution-time approval

approval_required at planning time is reserved for requests that explicitly name a destructive operation. Use the following rule when deciding between ready_to_plan and approval_required:

  • approval_required at planning time — the user's request itself names a destructive operation: "flatten this stage", "decimate the meshes", "merge prototypes", "delete unused prims", or any specific named mutation that cannot be undone within the same workflow. In this case the agent's first response must be an approval prompt that names the operation, before the agent commits to a plan that executes it.

  • ready_to_plan at planning time — the user's request is general: "optimize this scene", "make it load faster", "reduce GPU memory", "improve interactivity". The agent lays out the full plan, including any destructive operations the plan would invoke (for example so-run-operations with mergeMaterials), without withholding the plan itself. Approval for each destructive operation is requested alongside plan approval.

The distinction is between authorising a plan and authorising a destructive action. A general optimisation request authorises planning; it does not authorise execution of specific destructive operations.

For structured runtime-test responses and similar planning summaries:

  • A future restructure-decision prompt is a planned user-decision gate, not a reason to set the top-level response decision to approval_required for a generic optimization request.

  • For a generic optimization request, set decision: "ready_to_plan" and include the full intended chain in both committed_milestones and planned_phases, through optimization-report.

  • It is valid for gates_observed to include asks_user_for_restructure_decision while the top-level decision remains ready_to_plan.

  • Whenever a chain names profile phases, use the exact labels profile-stage:baseline and profile-stage:after; do not emit the ambiguous bare profile-stage token.

  • Start structured milestone lists with omniverse-usd-performance-tuning as the owning entry skill. Include setup-usd-performance-tuning only as additional Phase 0 context, not as a replacement for the entry skill milestone.

  • For broad optimization requests, preserve the milestone subsequence from Output Format above exactly, with optional extra analysis steps inserted only where they do not reorder it.

  • Do not list so-run-validators or so-interpret-validators before restructure-decision in broad optimization milestone summaries. Phase-aware validator routing still happens through usd-validation-runner; the SO validator executor/interpreter milestones appear after the restructure decision path in the structured plan contract.

Output expectation

End-to-end optimization work should produce both an optimized USD stage, when mutation is executed, and a structured optimization report conforming to the optimization-report reference's scripts/optimization-report.schema.json. The HTML report must be rendered from references/report-templates/optimization-report.html.template via render_preview.py — never hand-write HTML. Diagnosis-only work should still end with a report or summary that states no optimized stage was written.

Purpose

Route digital twin USD performance requests into the right diagnostic and optimization workflow while preserving evidence before mutation.

Prerequisites

  • Stage path or enough context to identify the target asset.

  • User goal: diagnosis only, validation, profiling, or processor execution.

  • Runtime availability status from setup-usd-performance-tuning when not already known.

  • Permission status for in-place mutation vs writing a separate optimized output.

Examples

  • "This USD loads slowly; triage what to check first."

  • "Route a low-FPS CAD scene through the performance workflow."

Triage order

  1. Runtime gate. Follow the mandatory session-start gate above before validation, profiling, or optimization. Do not scan, probe, install, or pick Kit/standalone runtimes directly in this skill; setup-usd-performance-tuning owns probe/chooser/install dispatch and writes the preflight consumed here.

  2. Identify the target problem:

    • Load time.

    • FPS or interactivity.

    • GPU or system memory.

    • Crash or device lost.

    • CAD conversion quality.

    • Validation failure.

  3. Gather minimum context:

    • Stage path and size.

    • Whether the stage is local, mounted, or omniverse:// remote. For remote assets, route through omniverse-authentication before first open.

    • Kit or USD runtime.

    • Whether the workload is CAD, VFI, AIF, Isaac, or generic OpenUSD.

    • Whether in-place mutation is allowed.

    • Whether the user wants diagnosis only or processor execution.

  4. Route:

    • USD composition questions: usd-structure-assessment (composition is now part of the SA umbrella; deeper detail in skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/composition-audit.md).

    • Validation and content issues: usd-validation-runner (master router; routes to validate-* family or so-run-validators based on intent).

    • Edit/output decisions: usd-edit-target-planner (also owns variant/payload gates).

    • Repeated copied hierarchy or high mesh count with no instancing: usd-hierarchy-dedupe-candidates.

    • Restructure decision (monolithic stage, asset boundary materialization): restructure-decision.

    • CAD converter settings: read references/cad-conversion/README.md (niche pre-USD concern; see reference for details).

    • Scene Optimizer: so-run-validators, so-interpret-validators, so-run-operations.

Optimization ordering

Follow the canonical ordering in workflow.md § Operation ordering invariants. The high-level rule: prototypes first → per-asset validation → stage-level operations last. The workflow reference owns the full invariant list (meshCleanup before decimateMeshes, deduplication before decimation, never merge if instanced, etc.) and the analysis-only ops catalogue.

Rules

  • Always run composition audit before mutation.

  • Always validate before and after processor execution.

  • Optimize prototypes before per-asset validation.

  • Do not run whole-stage mesh deduplication on very large CAD scenes before checking for hierarchy-level reuse.

  • Do not recommend a fixed optimization stack without bottleneck evidence.

  • Do not invent numeric thresholds or expected percentage wins.

  • Prefer canonical SO ops over specialty / documentary ones. The op curation in references/operations/_curation.json classifies every op as canonical, specialty, analysis, documentary, or deprecated. When more than one op could resolve the same finding, recommend the canonical one first and only reach for a specialty op when the user explicitly asks or the rationale warrants it. Specifically:

    • For vertex welding, prefer canonical meshCleanup with explicit flags over the standalone mergeVertices op. The standalone op is a legacy/specialty surface; use upstream usd-optimize for the operation mechanics and local approval policy before mutating.

    • For hierarchy dedupe, recommend usd-hierarchy-dedupe-candidates + apply-restructure (the USD-authored rewrite path).

    • For per-mesh dedupe, recommend deduplicateGeometry (canonical) over findCoincidingGeometry (analysis — produces a report, not a change).

    • Do not recommend documentary-status ops (e.g., boxClip, deletePrims, removeAttributes, removeUntypedPrims, merge outside its narrow non-instanced case) without an explicit user request. Documentary ops survive in the per-op references/operations/<key>.md routing stubs for completeness but are excluded from agent-initiated recommendations.

    • Specialty ≠ documentary. Ops classified as specialty in _curation.json either (a) have validator-finding evidence that wires them into the so-interpret-validators chain (e.g. sparseMeshes, optimizePrimvars), or (b) are load-bearing escape hatches needed for specific downstream contexts (e.g. primitivesToMeshes when output must be UsdGeomMesh, utilityFunction for instancing toggles and material rebinding, pythonScript for so-create-proxy recipes). Recommend specialty ops when their validator fires OR when their downstream context applies — the suppression above only targets documentary ops.

Limitations

  • Does not replace downstream reference instructions; load each required reference before executing it.

  • Does not install runtimes directly; follow setup or install references when requirements are missing.

  • Does not authorize mutation when the user has not allowed writes.

Troubleshooting

  • If runtime status is unclear, run setup-usd-performance-tuning before profiling or validation.

  • If the reported problem is vague, gather stage path, workload type, and whether diagnosis or execution is requested.

  • If the workflow suggests mutation before evidence, return to baseline profiling and composition audit first.

References

Before routing, read:

  • skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/optimization-tradeoffs.md — identify which pipeline phase the scene is in (extraction, structuring, or optimization). The right action depends on the phase.

  • skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/factory-level-structuring.md — understand the three pillars (assets, aggregation, animation) and the seven-step structuring pattern.

If you have network access, prefer the live URLs (noted in each reference file) for the most current version.

Required execution flow

Read references/workflow.md for the canonical Phase 0-7 flow, including Kit/standalone branches, validator-stack routing, operation ordering, termination conditions, duration hints, and the optional iteration pattern. The compact root map at references/skill-map.md only routes agents into this workflow.

Do not treat downstream phase names as plain checklist labels. Before executing each step, load that phase's nested README.md reference and follow its instructions. Claude Code only exposes the public catalog skill; it does not recursively inject profile-stage, usd-structure-assessment, or other nested references.

The final deliverable must come from optimization-report: save both the structured JSON report and the generated Markdown summary. Do not substitute an ad hoc SUMMARY.md or chat-only recap for the optimization report.

For deeper subtopic guidance, consult the references:

  • skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/composition-audit.md, skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/layer-health.md - subtopic detail for SA's Phase 1 checklist.

  • skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md - merge safety, decision tree for instancing choices.

  • skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/variants-payloads.md - deeper variant/payload trade-offs (gates are inline in usd-edit-target-planner).

  • references/cad-conversion/README.md - CAD converter settings.

  • references/upstreams/usd-optimize.md - upstream SO mechanics and prebuilt package resolution.

  • skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-run-validators/references/infrastructure.md - local handoff for SO validator infrastructure.

  • skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/validation-scoping.md - tier 1/2/3 plan + scene-aware adjustment.

  • skills/omniverse-usd-performance-tuning/references/optimization-report/references/optimization-report-template.md - the data contract every phase populates.

For full Kit runtime profiling (FPS, frame time, Hydra/RTX metrics), refer to the external profiling skills at NVIDIA/omniperf.

Files

references/usd-validation-runner/references/validation-scoping.md

<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->

<!-- SPDX-License-Identifier: Apache-2.0 -->

Validation Scoping — Canonical Cost Guardrails

This is the single source of truth for validation cost control in the digitaltwin-performance-skill workflow. Other references (usd-validation-runner, validate-usd-asset-validator, workflow.md) point here for tier detail, approval gates, and scoping rules rather than duplicating them.

Decision Tree (read this first)

┌─ What did structure assessment say? ─────────────────────────────────────┐
│                                                                          │
│  phase_recommendation = "structuring"                                    │
│    → Structural validators only (do not validate geometry about to be    │
│      restructured)                                                       │
│                                                                          │
│  phase_recommendation = "optimization"                                   │
│    → Tier 1: always (full stage)                                         │
│    → Tier 2: per flagged asset (or 10% sample if budget allows)          │
│    → Tier 3: only on specifically flagged targets, ALWAYS ask first      │
│                                                                          │
│  phase_recommendation = "already_optimized"                              │
│    → Tier 1 only; ask user before expanding scope                        │
│                                                                          │
│  No structure assessment available                                       │
│    → Run structure assessment first. Do not begin with validators.       │
│                                                                          │
├─ Is a full-stage Asset Validator sweep requested? ───────────────────────┤
│                                                                          │
│  Trigger the FULL-SWEEP APPROVAL GATE (§ below) when ANY of:            │
│    • Stage size is unknown                                               │
│    • Customer-scale factory/CAD/BIM/MEP/plant/city                       │
│    • SA reports large prim/mesh/prototype/material counts                │
│    • Request is performance triage (not formal conformance)              │
│                                                                          │
│  Offer: targeted rules (recommended) | full sweep + timeout | defer      │
│                                                                          │
├─ Is full-stage AV too expensive but signal is still needed? ─────────────┤
│                                                                          │
│  Use MASKED-STAGE SPOT CHECKS (§ below)                                  │
│    • ≥25% mesh coverage or explain why not                               │
│    • Label as sample evidence, not full-stage evidence                   │
│                                                                          │
├─ Is a full-stage category sweep planned on a very large mesh count? ─────┤
│                                                                          │
│  Do NOT run uncapped Basic/Layer/Geometry/etc. over the whole stage.      │
│  Use masked spot checks, or run each selected category/rule in a          │
│  subprocess with an explicit wall-clock budget and report TIMEOUT rows.   │
│                                                                          │
├─ Stage has >30K prototype meshes and per-rule attribution is needed? ────┤
│                                                                          │
│  Use PER-RULE TIMEOUT pattern (§ below)                                  │
│                                                                          │
├─ Validating post-decompose targets (payloads, assembly root)? ───────────┤
│                                                                          │
│  Each target re-enters THIS tree independently (§ Post-Restructure       │
│  Validation Strategy). Treat each payload/assembly as a fresh validation │
│  request — tier selection, approval gate, and spot-check threshold apply │
│  based on THAT target's prim count, not the original composed stage.     │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

Purpose

Translate structure assessment findings into a concrete validation plan that avoids running expensive validators on assets that do not need them. Use this after usd-structure-assessment produces its report and before invoking so-run-validators.

Inputs

  • Structure assessment report: flagged_assets, validation_scope, phase_recommendation.

  • User time/resource budget and approval posture for expensive checks.

  • Goal type: diagnosis-only or diagnosis plus execution.

  • Validator names available in the installed runtime.

Validator Tiers

Tier 1: Fast (seconds per asset)

Metadata and traversal only. Safe to run on all assets.

  • printStats

  • countVertices

  • rtxMeshCount

  • removeSmallGeometry (analysis mode)

  • findFlatHierarchies (analysis mode)

  • pruneLeaves (analysis mode)

  • removePrims (analysis mode — orphaned overs)

Tier 2: Medium (seconds to minutes per asset)

Per-mesh inspection. Run on flagged assets or all if budget allows.

  • meshCleanup (analysis mode)

  • optimizeMaterials (analysis mode)

  • removeUnusedUVs (analysis mode)

  • computeExtents (analysis mode)

  • generateNormals (analysis mode)

Tier 3: Expensive (minutes per asset, minutes to hours cross-component)

Spatial or pairwise analysis. Run only on specifically flagged assets/pairs. Always ask the user before running.

  • deduplicateGeometry (analysis mode) — on repetition-flagged assets

  • findCoincidingGeometry (analysis mode) — on repetition-flagged pairs

  • findOccludedMeshes (analysis mode) — on containment-flagged pairs

  • fitPrimitives (analysis mode) — on outlier-flagged or primitive-like assets

  • sparseMeshes (analysis mode) — on outlier-flagged assets

Deferred to Post-Optimization Pass

These validators are expensive AND their findings do not influence operation selection — the corresponding operations already run unconditionally based on structural signals. Running these first adds cost without changing the plan.

ValidatorWhy deferred
optimizePrimvars / IndexedPrimvarCheckerremoveUnusedUVs + optimizePrimvars already run for CAD/BIM. Checker produces 100K+ warnings (~6 min, ~156 MB) confirming what SA already told you.
SceneOptimizerNonManifoldChecker / ManifoldCheckerPer-edge topology; only relevant for simulation targets. Visualization-only workflows skip entirely.
SceneOptimizerUnusedUVsCheckerSame signal as IndexedPrimvar — the operation is already selected.

Exception: If the assessment does NOT indicate these operations should run (e.g., a non-BIM scene where UV removal is uncertain), DO run the validators — their findings provide the evidence to justify the operation.

Full-Sweep Approval Gate

Trigger before any command that enables the default AV rule set over the whole composed stage when ANY condition holds:

  1. Stage size is unknown.

  2. Target is customer-scale factory/CAD/BIM/MEP/plant/city.

  3. SA reports large prim/mesh/prototype/material counts, many payloads/references, or a monolithic root layer.

  4. Request is performance triage rather than formal conformance.

Offer the user three options:

  • Recommended: minimum-openability + targeted category/rule checks.

  • Full sweep: default AV rule set with explicit timeout and artifact dir.

  • Defer: skip AV until after SA or after mutation.

When approved, record scope: "full_stage", approved_by_user: true, timeout_seconds, and artifact paths. If not approved, do not launch.

Scoping Rules

  1. Structure assessment is the first filter. Use summary_counts plus duplicate-hierarchy candidates to decide which validators can change the optimization plan. Do not start with a full default AV sweep.

  2. Start with cheap, optimization-oriented evidence. Duplicate geometry/materials, empty leaves, flat hierarchies, high vertex/mesh count summaries, unused UVs (when tolerant of noise), small/zero-extent geometry (when scoped).

  3. Keep SO analysis in the validation workflow. Use AV-registered SO checkers when available; otherwise run equivalent read-only SO analysis via so-run-validators in the same plan. Do not treat it as a separate phase.

  4. Run Tier 2 per-asset on:

    • All assets flagged by SA (any reason).

    • A sample of unflagged assets if budget allows (e.g., 10% random).

  5. Run Tier 3 only on flagged targets:

    • deduplicateGeometry: only repetition-flagged.

    • findOccludedMeshes: only containment-flagged pairs.

    • fitPrimitives / sparseMeshes: only outlier_extent or primitive-like. For CAD/BIM/MEP, pipe/duct/conduit/fitting names or high prototype mesh counts are enough evidence. Heavy existing instancing does not remove this signal.

  6. Cross-component validators require the composed stage with relevant payloads visible. Use Usd.Stage.OpenMasked() with a population mask covering only the flagged pair (and their dependency closures), OR run the validator via standalone Usd.Stage.Open() on each target file. Do NOT rely on LoadNone + selective stage.Load() — the Asset Validator discards load rules and re-opens with LoadAll (see §"LoadRules Behavior With the Asset Validator" below).

  7. If no assets are flagged: Tier 1 only. Report the scene as likely well-structured. Ask before running Tier 2-3.

  8. Defer noisy/slow full-stage rules. Do not run IndexedPrimvarChecker, CoincidingGeometryChecker, ExtentsChecker, AlmostExtremeExtentChecker, ArticulationChecker, ColliderChecker, or KindChecker globally in the preliminary pass. Run them only when the scope makes their output actionable (physics checks for simulation assets, coinciding geometry for repetition-suspect groups, etc.).

  9. Cap selected category sweeps on large stages. A category-scoped AV run is still a full-stage traversal for that category. If summary_counts.mesh_count or prototype/proxy mesh contribution is very large, do not launch uncapped Basic, Layer, Geometry, Material, or multi-category sweeps over the full composed stage. Prefer masked-stage spot checks. If a category sweep is still needed, run each selected category or rule in its own subprocess with an explicit wall-clock budget, record timeout_seconds / timeout_reason, and treat partial results as scoped evidence rather than full conformance.

  10. Prefer summaries over issue dumps. Summarize findings into target counts and operation candidates. Apply runtime-artifact-token-budget.md for CSV/log/summary handling.

Scene-Aware Tier Adjustment

The static tier assignments above are defaults. Adjust based on phase_recommendation and scene characteristics:

Scene signalAdjustment
CAD/BIM/MEP, pipe/duct-heavy, many primitive-like prototypesPromote fitPrimitives analysis into first SO pass (even when heavily instanced — instancing skips mesh dedup, not prototype primitive fitting).
Well-structured, artisticPromote deduplicateGeometry + optimizeMaterials; demote fitPrimitives.
Instancing ratio >80%Skip deduplicateGeometry.
Scene has 0 extentsAlways include computeExtents.
Enclosed buildingScope findOccludedMeshes to within-floor/within-discipline, or skip entirely.

When removeUnusedUVs and fitPrimitives both target the same CAD/BIM content, interpret fitPrimitives candidates against the post-UV-cleanup state; a pre-cleanup nonconstPrimvarMeshCount bucket is still a primitive-fit opportunity.

Masked-Stage Spot Checks

See also: "Post-Restructure Validation Strategy" below for how to validate after apply-restructure or decompose-for-selective-loading. Masked-stage techniques apply within that framework when individual targets (assembly skeleton or a single large payload) are themselves too expensive for a full sweep.

Use when full-stage AV is too expensive but prim-level findings can still change the optimization plan. This is the preferred alternative to dropping validation entirely on customer-scale assets.

When to use

  • Stage is customer-scale (CAD/BIM/MEP/factory/city, tens of thousands of prototype meshes).

  • SA can identify representative candidate subtrees.

  • Rule set is mostly CheckPrim-style geometry/material/schema checks.

  • Result is optimization evidence, not formal conformance.

Sample selection

  1. Build a cheap full-stage inventory first: top branches by mesh count, semantic names, top prototype/fingerprint groups, material-heavy branches, instance-heavy branches.

  2. Include all SA-flagged targets that may change the operation plan.

  3. Cover ≥25% of mesh-bearing content by mesh count, rtxMeshCount, or instance-proxy mesh contribution. If floor is impractical, record why and mark result as limited sample evidence.

  4. Include high-risk exemplars: largest mesh, deepest hierarchy, material-heavy mesh, repeated module, top prototype/fingerprint family, dominant mesh-bearing semantic classes (pipe/duct/conduit/fitting for MEP; equivalent for other scenes).

  5. Do not sample bare generated prototype roots unless the masked stage is verified to expose descendant meshes.

Implementation
from pxr import Sdf, Usd, UsdGeom
from omni.asset_validator import CategoryRuleRegistry, ValidationEngine

asset_abs = "/path/to/customer-scale.usd"
root_layer = Sdf.Layer.FindOrOpen(asset_abs)
default_prim_path = f"/{root_layer.defaultPrim}" if root_layer.defaultPrim else None

sampled_paths = ["/Root/Prototypes/PipeFamily_A", "/Root/Mechanical/Level_02/AHU_01"]
closure_paths = ["/Root/Looks", "/Root/Materials"]

mask = Usd.StagePopulationMask()
for path in [*sampled_paths, *closure_paths, default_prim_path]:
    if path:
        mask.Add(path)

stage = Usd.Stage.OpenMasked(root_layer, mask)
assert stage.GetDefaultPrim().IsValid(), "masked stage excluded default prim"

# Verify mesh coverage (proxy/prototype-aware)
mesh_count = sum(
    1 for prim in Usd.PrimRange.Stage(
        stage, Usd.TraverseInstanceProxies(Usd.PrimDefaultPredicate)
    ) if prim.IsA(UsdGeom.Mesh)
)
# Must be ≥25% of total_scene_mesh_count; raise if 0

registry = CategoryRuleRegistry()
normals_rule = next(
    rule for rule in registry.get_rules("Geometry") if rule.__name__ == "NormalsValidChecker"
)

engine = ValidationEngine(init_rules=False)
engine.enable_rule(normals_rule)
results = engine.validate(stage)
Constraints

  • Preserve default prim in the mask.

  • Add material scopes / relationship targets when running material rules.

  • Avoid stage-global / layer-global / dependency rules in spot mode.

  • Label output scope: "masked_stage_spot_check" with sampled paths, semantic tags, mesh coverage %, and evidence scope.

  • Reject empty samples: if proxy/prototype-aware counts report 0 meshes, resample instead of reporting "0 findings."

Post-Restructure / Post-Decompose Validation Strategy

After apply-restructure (mode=restructure) or decompose-for-selective-loading produces an assembly root + N payload/prototype files, do NOT open the full composed stage with all payloads loaded for a blanket validator sweep. That re-couples what was just decomposed and doubles validation work.

Validation Distribution

  • Assembly skeleton — open with Usd.Stage.OpenMasked() excluding payload prim paths. Run structural validators only: reference resolution, kind hierarchy, layer structure, defaultPrim, extent hints, assetInfo. Single pass.

  • Assembly root as optimization target — if the assembly root retains mesh content after extraction (ground planes, shared environment geometry, non-extracted sub-hierarchies), it is itself a Phase 4 target. Validate and optimize it like any other target via the decision tree. The manifest records this with target_class: "assembly_root".

  • Each payload/prototype (standalone) — open each file independently with Usd.Stage.Open(payload_file). Plan validation through the decision tree for each target (tier selection and approval thresholds apply per-target based on that target's prim count — a small payload may qualify for spot-check rather than a full sweep). These are independent and can run in parallel.

  • Cross-payload pairs — open with Usd.Stage.OpenMasked(root, mask) covering only the two relevant payload subtrees. Run Tier 3 only (findCoincidingGeometry, etc.) per flagged pair.

Rules

  1. Validate each payload as a standalone file. Do not rely on the assembly context for per-payload geometry validation.

  2. Validate payloads in parallel — they are independent by definition.

  3. The assembly-skeleton pass confirms composition integrity (all refs resolve, no dangling payload arcs, kind/model hierarchy correct).

  4. Cross-payload Tier 3 validators use OpenMasked to expose only the specific pair, not all payloads.

  5. Report results per-target (assembly vs each payload) so the user sees which specific payload has issues.

  6. Each target in the per-target loop re-enters THIS decision tree as if it were a fresh validation request — the tree's tier selection, spot-check threshold, and approval gate apply per-target based on that target's prim count.

Why NOT re-compose

Opening the full composed stage with all payloads loaded for validation after decompose:

  • Defeats the purpose of decomposition (cost is the same as the original).

  • Produces per-prim findings attributed to composed paths that don't map cleanly to individual payload files.

  • Prevents parallel validation of independent payloads.

  • Triggers the same cost gate the user already approved once (double-prompting).

LoadRules Behavior With the Asset Validator

The Asset Validator's ComplianceChecker opens a new stage from the input's root layer with default LoadAll semantics. The original stage's load rules (e.g. LoadNone) are discarded.

StagePopulationMask IS preserved — if the input stage was opened with Usd.Stage.OpenMasked(), the mask carries through to the validator's internal stage.

This is observable behaviour across current AV versions; do not assume future releases will behave the same. Probe the AV API/version when possible.

Consequences

  • Passing a LoadNone stage to the AV is equivalent to passing a LoadAll stage.

  • All payload content will be loaded and traversed regardless of the load predicate.

  • Usd.PrimRange.Stage(stage, Usd.TraverseInstanceProxies()) visits everything loaded.

  • Elapsed time and findings will reflect the full composed stage, not the skeleton.

What works

  • Usd.Stage.OpenMasked() — physically excludes prims from the stage's view. The AV preserves the population mask, so masked prims remain invisible to checkers.

  • Opening each payload file standalone (preferred — see "Validation Distribution" above).

What does NOT work

  • Usd.Stage.Open(root, Usd.Stage.LoadNone) — load rules are discarded by AV.

  • stage.Load(specific_path) after LoadNone — same problem, AV re-opens from root.

  • Any load-state scoping strategy that relies on StageLoadRules being preserved.

Per-Rule Timeout Pattern

For stages with very high mesh/prototype counts where total validation would exceed the time budget. Run each category or rule in its own subprocess with an explicit budget so a single slow checker does not consume the whole pass.

import subprocess, json, sys
from omni.asset_validator import CategoryRuleRegistry, ValidationEngine
from pxr import Usd

def validate_one_rule(stage_path, category, rule_name, per_rule_budget_s):
    registry = CategoryRuleRegistry()
    rule = next(
        rule for rule in registry.get_rules(category) if rule.__name__ == rule_name
    )
    engine = ValidationEngine(init_rules=False)
    engine.enable_rule(rule)
    stage = Usd.Stage.Open(stage_path)
    results = engine.validate(stage)
    return list(results.issues())

# Driver:
RULES = [
    ("Geometry", "ManifoldChecker"),
    ("Geometry", "WeldChecker"),
]
results = {}
for category, rule_name in RULES:
    try:
        out = subprocess.run(
            [sys.executable, __file__, stage_path, category, rule_name],
            timeout=per_rule_budget_s, capture_output=True, check=True,
        )
        results[f"{category}.{rule_name}"] = json.loads(out.stdout)
    except subprocess.TimeoutExpired:
        results[f"{category}.{rule_name}"] = {
            "status": "timed-out",
            "budget_s": per_rule_budget_s,
        }

When to use: >30K prototype meshes, very large summary_counts.mesh_count, suspected single-rule hang, or iterating on one rule without re-running others. For small/medium stages, use the standard tier plan via so-run-validators.

Output — Validation Plan JSON

{
  "tier1": {
    "scope": "full_stage",
    "validators": ["printStats", "countVertices", "rtxMeshCount", "..."]
  },
  "tier2": {
    "scope": "per_asset",
    "assets": ["path/to/A.geom.usd", "path/to/B.geom.usd"],
    "validators": ["meshCleanup", "optimizePrimvars", "..."]
  },
  "tier3": {
    "scope": "targeted",
    "tasks": [
      { "validator": "findOccludedMeshes", "targets": [["CabinetA", "PipeB"]] },
      { "validator": "deduplicateGeometry", "targets": ["ChairA", "ChairB"] }
    ]
  },
  "spot_checks": {
    "scope": "masked_stage_spot_check",
    "sampled_paths": ["</Root/Prototype_A>", "</Root/Mechanical/PipeFamily_01>"],
    "mesh_coverage_percent": 28.4,
    "evidence_scope": "sample"
  },
  "skip": ["list of unflagged assets - no deep validation planned"],
  "estimated_time": "fast | minutes | long"
}

This plan is passed to so-run-validators (executor) by usd-validation-runner (router).

Hard Rules

  1. Never run all validators on all assets by default.

  2. Never run Tier 3 without structural evidence from the assessment.

  3. Always ask before Tier 3 cross-component checks.

  4. Never start a performance workflow with a full default AV sweep.

  5. Prefer masked-stage spot checks over dropping validation when full-stage is too expensive.

  6. Always report what was skipped and why — the user may override.

Duration Hints (typical: ~100K prims, ~200K meshes)

ScopeExpected
Tier 1 (full stage)~5 min
Tier 2 (per flagged asset)~30 min
Tier 3 (cross-component)hours — always confirm
Structural validators only~2 min
Masked-stage spot check~5-10 min

Prerequisites

  • Structure assessment report (specifically flagged_assets and validation_scope).

  • User time/resource budget.

  • Access to validator names in the installed runtime.

Limitations

  • Scope quality depends on the structure assessment; weak evidence stays visible.

  • Tier cost estimates are defaults — they scale with scene size.

  • SO validator names must match the installed runtime.

Troubleshooting

  • No assets flagged → Tier 1 only, ask before expanding.

  • Tier 3 requested without evidence → return to usd-structure-assessment.

  • Named validator unavailable → record gap, choose nearest supported source.

Requirements and compatibility

Written for: OpenAI Codex

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

The author says: Orchestrator skill. Downstream phases may require Kit, Scene Optimizer, Asset Validator, USD Python, writable output paths, and omniverse:// authentication selected by setup-usd-performance-tuning.

Security

What our scanner noticed· Medium risk

  • Large base64-encoded blobs
  • Instructions that use the network
  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
NVIDIA Omniverse
Publisher
OpenAI (Official)
Distributed by
OpenAI
Source
openai/plugins · plugins/nvidia/skills/omniverse-usd-performance-tuning · commit d420d13
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (written by AutoGineer)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by NVIDIA Omniverse or OpenAI.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download omniverse-usd-performance-tuning.zip