diff --git a/.github/scripts/marketplace/metadata.json b/.github/scripts/marketplace/metadata.json index bc7ff30b..104a346e 100644 --- a/.github/scripts/marketplace/metadata.json +++ b/.github/scripts/marketplace/metadata.json @@ -2787,7 +2787,7 @@ { "path": "skills/omniverse-usd-performance-tuning", "name": "omniverse-usd-performance-tuning", - "description": "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.", + "description": "Top-level workflow skill for USD performance diagnosis and optimization. Handles slow loading, high memory, low FPS, and broad scene-optimization requests; delegates auth/runtime setup to Phase 0 owners.", "metadata": { "product.primary": "Omniverse", "classification.category.primary": "physical_ai", diff --git a/benchmarks.json b/benchmarks.json index 4550a735..af30f7f7 100644 --- a/benchmarks.json +++ b/benchmarks.json @@ -3967,13 +3967,13 @@ }, { "skill": "omniverse-usd-performance-tuning", - "evaluation_date": "2026-05-29", - "profile": "external", - "environment": null, + "evaluation_date": "2026-07-30", + "profile": null, + "environment": "k8s-sandbox", "tasks": null, - "attempts_per_task": null, + "attempts_per_task": 1, "pass_threshold_pct": null, - "verdict": "FAIL", + "verdict": "PASS", "agents": [], "catalog_dir": "omniverse-usd-performance-tuning", "component": "Physical AI", diff --git a/skills/omniverse-usd-performance-tuning/BENCHMARK.md b/skills/omniverse-usd-performance-tuning/BENCHMARK.md index 1778a9e1..2114af57 100644 --- a/skills/omniverse-usd-performance-tuning/BENCHMARK.md +++ b/skills/omniverse-usd-performance-tuning/BENCHMARK.md @@ -1,191 +1,101 @@ -# Evaluation Report +# Skill Benchmark: omniverse-usd-performance-tuning -Evaluation of the `omniverse-usd-performance-tuning` skill before publication through NVSkills-Eval. +> ✅ **Overall verdict: PASS — Recommended for publication** -This benchmark summarizes 3-Tier Evaluation from NVSkills-Eval results for the skill. The goal is to document whether the skill is safe, discoverable, effective, and useful for agents before it is published for broader workflow use. +## Publication Recommendation + +Recommended for publication based on the completed evaluation evidence in this report. -## Evaluation Summary +## Evaluation Metadata - Skill: `omniverse-usd-performance-tuning` -- Evaluation date: 2026-05-29 -- NVSkills-Eval profile: `external` -- Overall verdict: FAIL -- Tier 3 live agent evaluation: not available in this report - -## Agents Used - -- Tier 3 agent details were not available in this report. - -## Metrics Used - -Reported benchmark dimensions: - -- Security: checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access. -- Correctness: checks whether the agent follows the expected workflow and produces the correct final output. -- Discoverability: checks whether the agent loads the skill when relevant and avoids using it when irrelevant. -- Effectiveness: checks whether the agent performs measurably better with the skill than without it. -- Efficiency: checks whether the agent uses fewer tokens and avoids redundant work. - -Underlying evaluation signals used in this run: - -- No Tier 3 evaluation signal details were available in this report. - -## Test Tasks - -Tier 3 evaluation task details were not available in this report. - -## Results - -Tier 3 dimension rollup was not available in this report. - -## Tier 1: Static Validation Summary - -Tier 1 validation passed with observations. NVSkills-Eval ran 9 checks and found 10 total findings. - -Top findings: - -- MEDIUM PII/gps_coordinates: GPS coordinates (location information) (`references/operations/decimateMeshes.md:22`) -- MEDIUM PII/gps_coordinates: GPS coordinates (location information) (`references/profile-stage/README.md:162`) -- MEDIUM PII/gps_coordinates: GPS coordinates (location information) (`references/usd-structure-assessment/references/asset-structure-principles.md:704`) -- MEDIUM PII/gps_coordinates: GPS coordinates (location information) (`references/usd-structure-assessment/references/asset-structure-principles.md:709`) -- MEDIUM PII/gps_coordinates: GPS coordinates (location information) (`references/usd-structure-assessment/references/asset-structure-principles.md:851`) - -## Tier 2: Deduplication Summary - -Tier 2 validation reported findings. NVSkills-Eval ran 2 checks and found 17 total findings. - -Top findings: - -- HIGH DUPLICATE/duplicate: Duplicate content found across references/cad-conversion/README.md and references/compare-profiles.md and references/operations/CLASSIFICATION.md and references/operations/EXECUTION.md and references/operations/_template.md and references/operations/boxClip.md and references/operations/computeExtents.md and references/operations/countVertices.md and references/operations/decimateMeshes.md and references/operations/deduplicateGeometry.md and references/operations/deduplicateHierarchies.md and references/operations/deleteHiddenPrims.md and references/operations/deletePrims.md and references/operations/diceMeshes.md and references/operations/editStageMetrics.md and references/operations/findCoincidingGeometry.md and references/operations/findFlatHierarchies.md and references/operations/findOccludedMeshes.md and references/operations/findOverlappingMeshes.md and references/operations/fitPrimitives.md and references/operations/flattenHierarchy.md and references/operations/generateAtlasUVs.md and references/operations/generateNormals.md and references/operations/generateProjectionUVs.md and references/operations/generateScene.md and references/operations/manifoldMeshes.md and references/operations/merge.md and references/operations/mergeVertices.md and references/operations/meshCleanup.md and references/operations/optimizeMaterials.md and references/operations/optimizePrimvars.md and references/operations/optimizeSkelRoots.md and references/operations/optimizeTimeSamples.md and references/operations/organizePrototypes.md and references/operations/pivot.md and references/operations/primitivesToMeshes.md and references/operations/printStats.md and references/operations/pruneLeaves.md and references/operations/pythonScript.md and references/operations/remeshMeshes.md and references/operations/removeAttributes.md and references/operations/removePrims.md and references/operations/removeSmallGeometry.md and references/operations/removeUntypedPrims.md and references/operations/removeUnusedUVs.md and references/operations/rtxMeshCount.md and references/operations/shrinkwrap.md and references/operations/sparseMeshes.md and references/operations/splitMeshes.md and references/operations/subdivideMeshes.md and references/operations/triangulateMeshes.md and references/operations/utilityFunction.md and references/optimization-report/references/optimization-report-template.md and references/output-workspace.md and references/report-templates/README.md and references/runtime-artifact-token-budget.md and references/setup-usd-performance-tuning/references/kit-discovery.md and references/setup-usd-performance-tuning/references/runtime-context-header.md and references/setup-usd-performance-tuning/references/runtime-probe.md and references/setup-usd-performance-tuning/references/standalone-runtime.md and references/skill-map.md and references/so-run-operations/README.md and references/so-run-operations/references/batch-mode.md and references/so-run-operations/references/config-from-evidence.md and references/so-run-operations/references/invocation.md and references/so-run-operations/references/operation-safety.md and references/so-run-operations/references/pipelines.md and references/so-run-operations/references/so-create-proxy/README.md and references/so-run-operations/references/so-create-proxy/references/bounding-box-proxy-modes.md and references/so-run-operations/references/so-create-proxy/references/decimate-step-recipes.md and references/so-run-operations/references/so-create-proxy/references/decimation-tuning.md and references/so-run-operations/references/so-create-proxy/references/proxy-config-recipes.md and references/so-run-operations/references/units-and-tolerances.md and references/upstreams/usd-optimize.md and references/usd-structure-assessment/references/apply-restructure/references/hierarchy-dedupe-rewrite-tool-spec.md and references/usd-structure-assessment/references/apply-restructure/references/ref-remap-mode.md and references/usd-structure-assessment/references/apply-restructure/references/restructure-mode.md and references/usd-structure-assessment/references/asset-structure-principles.md and references/usd-structure-assessment/references/composition-audit.md and references/usd-structure-assessment/references/factory-level-structuring.md and references/usd-structure-assessment/references/instancing-readiness/references/instancing-guide.md and references/usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md and references/usd-structure-assessment/references/layer-health.md and references/usd-structure-assessment/references/optimization-tradeoffs.md and references/usd-structure-assessment/references/usd-edit-target-planner/references/output-saving.md and references/usd-structure-assessment/references/usd-edit-target-planner/references/variants-payloads.md and references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/references/instance-candidate-finder-spec.md and references/usd-validation-runner/references/so-interpret-validators/README.md and references/usd-validation-runner/references/so-interpret-validators/references/follow-up-queries.md and references/usd-validation-runner/references/so-interpret-validators/references/rule-reference.md and references/usd-validation-runner/references/so-run-validators/README.md and references/usd-validation-runner/references/so-run-validators/references/infrastructure.md and references/usd-validation-runner/references/validate-usd-asset-validator.md and references/workflow.md: - "(preamble)" in references/cad-conversion/README.md (lines 1-3) - vs "(preamble)" in references/compare-profiles.md (lines 1-3) - vs "(preamble)" in references/operations/CLASSIFICATION.md (lines 1-3) - vs "(preamble)" in references/operations/EXECUTION.md (lines 1-3) - vs "(preamble)" in references/operations/_template.md (lines 1-3) - vs "(preamble)" in references/operations/boxClip.md (lines 1-3) - vs "(preamble)" in references/operations/computeExtents.md (lines 1-3) - vs "(preamble)" in references/operations/countVertices.md (lines 1-3) - vs "(preamble)" in references/operations/decimateMeshes.md (lines 1-3) - vs "(preamble)" in references/operations/deduplicateGeometry.md (lines 1-3) - vs "(preamble)" in references/operations/deduplicateHierarchies.md (lines 1-3) - vs "(preamble)" in references/operations/deleteHiddenPrims.md (lines 1-3) - vs "(preamble)" in references/operations/deletePrims.md (lines 1-3) - vs "(preamble)" in references/operations/diceMeshes.md (lines 1-3) - vs "(preamble)" in references/operations/editStageMetrics.md (lines 1-3) - vs "(preamble)" in references/operations/findCoincidingGeometry.md (lines 1-3) - vs "(preamble)" in references/operations/findFlatHierarchies.md (lines 1-3) - vs "(preamble)" in references/operations/findOccludedMeshes.md (lines 1-3) - vs "(preamble)" in references/operations/findOverlappingMeshes.md (lines 1-3) - vs "(preamble)" in references/operations/fitPrimitives.md (lines 1-3) - vs "(preamble)" in references/operations/flattenHierarchy.md (lines 1-3) - vs "(preamble)" in references/operations/generateAtlasUVs.md (lines 1-3) - vs "(preamble)" in references/operations/generateNormals.md (lines 1-3) - vs "(preamble)" in references/operations/generateProjectionUVs.md (lines 1-3) - vs "(preamble)" in references/operations/generateScene.md (lines 1-3) - vs "(preamble)" in references/operations/manifoldMeshes.md (lines 1-3) - vs "(preamble)" in references/operations/merge.md (lines 1-3) - vs "(preamble)" in references/operations/mergeVertices.md (lines 1-3) - vs "(preamble)" in references/operations/meshCleanup.md (lines 1-3) - vs "(preamble)" in references/operations/optimizeMaterials.md (lines 1-3) - vs "(preamble)" in references/operations/optimizePrimvars.md (lines 1-3) - vs "(preamble)" in references/operations/optimizeSkelRoots.md (lines 1-3) - vs "(preamble)" in references/operations/optimizeTimeSamples.md (lines 1-3) - vs "(preamble)" in references/operations/organizePrototypes.md (lines 1-3) - vs "(preamble)" in references/operations/pivot.md (lines 1-3) - vs "(preamble)" in references/operations/primitivesToMeshes.md (lines 1-3) - vs "(preamble)" in references/operations/printStats.md (lines 1-3) - vs "(preamble)" in references/operations/pruneLeaves.md (lines 1-3) - vs "(preamble)" in references/operations/pythonScript.md (lines 1-3) - vs "(preamble)" in references/operations/remeshMeshes.md (lines 1-3) - vs "(preamble)" in references/operations/removeAttributes.md (lines 1-3) - vs "(preamble)" in references/operations/removePrims.md (lines 1-3) - vs "(preamble)" in references/operations/removeSmallGeometry.md (lines 1-3) - vs "(preamble)" in references/operations/removeUntypedPrims.md (lines 1-3) - vs "(preamble)" in references/operations/removeUnusedUVs.md (lines 1-3) - vs "(preamble)" in references/operations/rtxMeshCount.md (lines 1-3) - vs "(preamble)" in references/operations/shrinkwrap.md (lines 1-3) - vs "(preamble)" in references/operations/sparseMeshes.md (lines 1-3) - vs "(preamble)" in references/operations/splitMeshes.md (lines 1-3) - vs "(preamble)" in references/operations/subdivideMeshes.md (lines 1-3) - vs "(preamble)" in references/operations/triangulateMeshes.md (lines 1-3) - vs "(preamble)" in references/operations/utilityFunction.md (lines 1-3) - vs "(preamble)" in references/optimization-report/references/optimization-report-template.md (lines 1-3) - vs "(preamble)" in references/output-workspace.md (lines 1-3) - vs "(preamble)" in references/report-templates/README.md (lines 1-3) - vs "(preamble)" in references/runtime-artifact-token-budget.md (lines 1-3) - vs "(preamble)" in references/setup-usd-performance-tuning/references/kit-discovery.md (lines 1-3) - vs "(preamble)" in references/setup-usd-performance-tuning/references/runtime-context-header.md (lines 1-3) - vs "(preamble)" in references/setup-usd-performance-tuning/references/runtime-probe.md (lines 1-3) - vs "(preamble)" in references/setup-usd-performance-tuning/references/standalone-runtime.md (lines 1-3) - vs "(preamble)" in references/skill-map.md (lines 1-3) - vs "(preamble)" in references/so-run-operations/README.md (lines 1-3) - vs "(preamble)" in references/so-run-operations/references/batch-mode.md (lines 1-3) - vs "(preamble)" in references/so-run-operations/references/config-from-evidence.md (lines 1-3) - vs "(preamble)" in references/so-run-operations/references/invocation.md (lines 1-3) - vs "(preamble)" in references/so-run-operations/references/operation-safety.md (lines 1-3) - vs "(preamble)" in references/so-run-operations/references/pipelines.md (lines 1-3) - vs "(preamble)" in references/so-run-operations/references/so-create-proxy/README.md (lines 1-3) - vs "(preamble)" in references/so-run-operations/references/so-create-proxy/references/bounding-box-proxy-modes.md (lines 1-3) - vs "(preamble)" in references/so-run-operations/references/so-create-proxy/references/decimate-step-recipes.md (lines 1-3) - vs "(preamble)" in references/so-run-operations/references/so-create-proxy/references/decimation-tuning.md (lines 1-3) - vs "(preamble)" in references/so-run-operations/references/so-create-proxy/references/proxy-config-recipes.md (lines 1-3) - vs "(preamble)" in references/so-run-operations/references/units-and-tolerances.md (lines 1-3) - vs "(preamble)" in references/upstreams/usd-optimize.md (lines 1-3) - vs "(preamble)" in references/usd-structure-assessment/references/apply-restructure/references/hierarchy-dedupe-rewrite-tool-spec.md (lines 1-3) - vs "(preamble)" in references/usd-structure-assessment/references/apply-restructure/references/ref-remap-mode.md (lines 1-3) - vs "(preamble)" in references/usd-structure-assessment/references/apply-restructure/references/restructure-mode.md (lines 1-3) - vs "(preamble)" in references/usd-structure-assessment/references/asset-structure-principles.md (lines 1-3) - vs "(preamble)" in references/usd-structure-assessment/references/composition-audit.md (lines 1-3) - vs "(preamble)" in references/usd-structure-assessment/references/factory-level-structuring.md (lines 1-3) - vs "(preamble)" in references/usd-structure-assessment/references/instancing-readiness/references/instancing-guide.md (lines 1-3) - vs "(preamble)" in references/usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md (lines 1-3) - vs "(preamble)" in references/usd-structure-assessment/references/layer-health.md (lines 1-3) - vs "(preamble)" in references/usd-structure-assessment/references/optimization-tradeoffs.md (lines 1-3) - vs "(preamble)" in references/usd-structure-assessment/references/usd-edit-target-planner/references/output-saving.md (lines 1-3) - vs "(preamble)" in references/usd-structure-assessment/references/usd-edit-target-planner/references/variants-payloads.md (lines 1-3) - vs "(preamble)" in references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/references/instance-candidate-finder-spec.md (lines 1-3) - vs "(preamble)" in references/usd-validation-runner/references/so-interpret-validators/README.md (lines 1-3) - vs "(preamble)" in references/usd-validation-runner/references/so-interpret-validators/references/follow-up-queries.md (lines 1-3) - vs "(preamble)" in references/usd-validation-runner/references/so-interpret-validators/references/rule-reference.md (lines 1-3) - vs "(preamble)" in references/usd-validation-runner/references/so-run-validators/README.md (lines 1-3) - vs "(preamble)" in references/usd-validation-runner/references/so-run-validators/references/infrastructure.md (lines 1-3) - vs "(preamble)" in references/usd-validation-runner/references/validate-usd-asset-validator.md (lines 1-3) - vs "(preamble)" in references/workflow.md (lines 1-3) (`references/cad-conversion/README.md:1`) -- HIGH DUPLICATE/duplicate: Duplicate content found across references/usd-structure-assessment/references/apply-restructure/references/ref-remap-mode.md and references/usd-structure-assessment/references/apply-restructure/references/restructure-mode.md: - "## Output Validation" in references/usd-structure-assessment/references/apply-restructure/references/ref-remap-mode.md (lines 73-76) - vs "## Output Validation" in references/usd-structure-assessment/references/apply-restructure/references/restructure-mode.md (lines 179-183) (`references/usd-structure-assessment/references/apply-restructure/references/ref-remap-mode.md:73`) -- HIGH DUPLICATE/duplicate: Duplicate content found across references/compare-profiles/README.md and references/omniverse-authentication/README.md and references/optimization-report/README.md and references/profile-stage/README.md and references/setup-usd-performance-tuning/references/install-kit/README.md and references/setup-usd-performance-tuning/references/install-so-standalone/README.md and references/setup-usd-performance-tuning/references/install-so-via-kit/README.md and references/usd-structure-assessment/README.md and references/usd-structure-assessment/references/apply-restructure/README.md and references/usd-structure-assessment/references/instancing-readiness/README.md and references/usd-structure-assessment/references/restructure-decision/README.md and references/usd-structure-assessment/references/usd-edit-target-planner/README.md and references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/README.md: - "## Instructions" in references/compare-profiles/README.md (lines 10-17) - vs "## Instructions" in references/omniverse-authentication/README.md (lines 10-16) - vs "## Instructions" in references/optimization-report/README.md (lines 10-21) - vs "## Instructions" in references/profile-stage/README.md (lines 10-17) - vs "## Instructions" in references/setup-usd-performance-tuning/references/install-kit/README.md (lines 10-16) - vs "## Instructions" in references/setup-usd-performance-tuning/references/install-so-standalone/README.md (lines 10-16) - vs "## Instructions" in references/setup-usd-performance-tuning/references/install-so-via-kit/README.md (lines 10-16) - vs "## Instructions" in references/usd-structure-assessment/README.md (lines 10-16) - vs "## Instructions" in references/usd-structure-assessment/references/apply-restructure/README.md (lines 10-16) - vs "## Instructions" in references/usd-structure-assessment/references/instancing-readiness/README.md (lines 10-16) - vs "## Instructions" in references/usd-structure-assessment/references/restructure-decision/README.md (lines 10-17) - vs "## Instructions" in references/usd-structure-assessment/references/usd-edit-target-planner/README.md (lines 10-16) - vs "## Instructions" in references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/README.md (lines 10-16) (`references/compare-profiles/README.md:10`) -- HIGH DUPLICATE/duplicate: Duplicate content found across references/compare-profiles/README.md and references/omniverse-authentication/README.md and references/profile-stage/README.md and references/setup-usd-performance-tuning/references/install-kit/README.md and references/setup-usd-performance-tuning/references/install-so-standalone/README.md and references/setup-usd-performance-tuning/references/install-so-via-kit/README.md and references/usd-structure-assessment/README.md and references/usd-structure-assessment/references/apply-restructure/README.md and references/usd-structure-assessment/references/instancing-readiness/README.md and references/usd-structure-assessment/references/restructure-decision/README.md and references/usd-structure-assessment/references/usd-edit-target-planner/README.md and references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/README.md and references/usd-validation-runner/references/so-run-validators/README.md: - "## Output Format" in references/compare-profiles/README.md (lines 26-33) - vs "## Output Format" in references/omniverse-authentication/README.md (lines 17-20) - vs "## Output Format" in references/profile-stage/README.md (lines 28-34) - vs "## Output Format" in references/setup-usd-performance-tuning/references/install-kit/README.md (lines 17-20) - vs "## Output Format" in references/setup-usd-performance-tuning/references/install-so-standalone/README.md (lines 17-20) - vs "## Output Format" in references/setup-usd-performance-tuning/references/install-so-via-kit/README.md (lines 17-20) - vs "## Output Format" in references/usd-structure-assessment/README.md (lines 17-20) - vs "## Output Format" in references/usd-structure-assessment/references/apply-restructure/README.md (lines 17-24) - vs "## Output Format" in references/usd-structure-assessment/references/instancing-readiness/README.md (lines 17-20) - vs "## Output Format" in references/usd-structure-assessment/references/restructure-decision/README.md (lines 27-30) - vs "## Output Format" in references/usd-structure-assessment/references/usd-edit-target-planner/README.md (lines 17-20) - vs "## Output Format" in references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/README.md (lines 17-24) - vs "## Output Format" in references/usd-validation-runner/references/so-run-validators/README.md (lines 29-33) (`references/compare-profiles/README.md:26`) -- HIGH DUPLICATE/duplicate: Duplicate content found across references/usd-structure-assessment/references/asset-structure-principles.md and references/usd-structure-assessment/references/instancing-readiness/references/instancing-guide.md: - "#### Asset Parameterization" in references/usd-structure-assessment/references/asset-structure-principles.md (lines 259-286) - vs "### By parameterization" in references/usd-structure-assessment/references/instancing-readiness/references/instancing-guide.md (lines 153-188) (`references/usd-structure-assessment/references/asset-structure-principles.md:259`) +- Evaluation date: 2026-07-30 +- Evaluator version: `0.9.0` +- Agents: Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`), Codex (`openai/openai/gpt-5.5`) +- Tasks: 9 evaluation tasks (8 positive, 1 negative) +- Dataset digest: `sha256:137b9ca69a3516a7fffcdfff70f950f2851e5c425ccd4d9be11fb4ee4161ff8c` (skill-evaluator-dataset-snapshot/1) +- Attempts per task: 1 +- Environment: `k8s-sandbox` +- Tier 3 evidence: required for publication -## Publication Recommendation +Each task attempt ran in its own isolated sandbox pod. + +## What This Report Answers + +The three-tier evaluation checks whether the skill: + +- is safe to use; +- produces correct answers; +- is discovered and activated when needed; +- helps the agent complete the user's goal and expected workflow; and +- avoids wasted skill and tool usage. + +## Results at a Glance + +| Measure | Claude Code (Baseline → Skill Uplift) | Codex (Baseline → Skill Uplift) | +|---|---:|---:| +| Overall | Not available | 46% → 84% (+38 points) | +| Security | Not available | 89% → 100% (+11 points) | +| Correctness | Not available | 20% → 76% (+56 points) | +| Discoverability | Not available | 47% → 91% (+44 points) | +| Effectiveness | Not available | 37% → 63% (+26 points) | +| Efficiency | Not available | 35% → 91% (+56 points) | + +**How to read this table:** baseline is the same task attempted without the target skill. Uplift is `skill score - baseline score`, shown in percentage points. + +Example: `47% → 92% (+45 points)` means the skill-assisted run scored 92%, 45 percentage points above its 47% no-skill baseline. + +## Tier Status + +| Tier | Purpose | Status | Evidence | +|---|---|---|---| +| Tier 1 | Static validation | **PASSED WITH OBSERVATIONS** | 1 validator(s); 4 finding(s) | +| Tier 2 | Semantic deduplication | **NOT RUN** | No result was recorded | +| Tier 3 | Live agent evaluation | **PASS** | 2 agent(s); 9 task(s) | + +## Findings and Observations + +
+Show detailed findings and successful checks + +- **MEDIUM** SCHEMA/frontmatter_field_placement: Root field 'version' is ignored; use 'metadata.version' (`skills/omniverse-usd-performance-tuning/SKILL.md`) +- **MEDIUM** SCHEMA/body_recommended_section: Missing recommended section: '## Instructions' (`skills/omniverse-usd-performance-tuning/SKILL.md`) +- **MEDIUM** SCHEMA/body_recommended_section: Missing recommended section: '## Examples' (`skills/omniverse-usd-performance-tuning/SKILL.md`) +- **LOW** SCHEMA/author_format: Author must be of the form 'Name ' (`skills/omniverse-usd-performance-tuning/SKILL.md`) + +
+ +## Scoring Methodology + +
+Show dimension definitions, source signals, and thresholds + +| Dimension | Question | Scored signals | +|---|---|---| +| Security | Is it safe to use? | `security` (100%) | +| Correctness | Is the answer correct? | `accuracy` (100%) | +| Discoverability | Was the right skill loaded when needed? | `skill_execution` (100%) | +| Effectiveness | Did the skill help complete the task? | `goal_accuracy` (50%) + `behavior_check` (50%) | +| Efficiency | Did it avoid wasted tool or skill usage? | `skill_efficiency` (100%) | + +- Dimension bands: PASS at 50% or above; NEUTRAL from 40% to below 50%; FAIL below 40%. +- Overall Tier 3 lift: PASS at +5 points or more; FAIL at -10 points or less; values between those bands are NEUTRAL. +- Overall verdict: PASS only when every configured dimension passes for at least one supported agent. Lift is reported as diagnostic evidence and does not override this gate. +- The 50% attempt pass threshold is a separate per-task gate; it is not the dimension pass threshold. +- Effectiveness is the equal-weight mean of goal completion (`goal_accuracy`) and expected workflow adherence (`behavior_check`). +- Token efficiency is a separate report-only signal. It does not change a dimension score or the overall verdict. + +Signals present in this run: + +- `security` (Security): unsafe operations, secret leakage, and unauthorized access. +- `skill_execution` (Skill Execution): whether the expected skill was found and executed. +- `skill_efficiency` (Efficiency): routing quality, workspace-aware skill reads, and productive tool use. +- `accuracy` (Accuracy): final-answer correctness against the reference answer. +- `goal_accuracy` (Goal Accuracy): whether the user's goal was achieved. +- `behavior_check` (Behavior Check): whether the expected workflow behavior was followed. + +
+ +## Freshness -The skill should be reviewed before NVSkills-Eval publication. Skill owners should address the findings above and rerun NVSkills-Eval to refresh this benchmark. +Regenerate this benchmark when the skill, evaluation dataset, target agent/model, evaluator version, environment, or scoring policy changes. diff --git a/skills/omniverse-usd-performance-tuning/SKILL.md b/skills/omniverse-usd-performance-tuning/SKILL.md index e7fbee88..3b857c72 100644 --- a/skills/omniverse-usd-performance-tuning/SKILL.md +++ b/skills/omniverse-usd-performance-tuning/SKILL.md @@ -1,6 +1,6 @@ --- name: omniverse-usd-performance-tuning -description: "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." +description: "Top-level workflow skill for USD performance diagnosis and optimization. Handles slow loading, high memory, low FPS, and broad scene-optimization requests; delegates auth/runtime setup to Phase 0 owners." version: "0.1.0" license: Apache-2.0 tools: @@ -8,7 +8,7 @@ tools: - Shell - Write compatibility: > - 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. + Orchestrator skill. Downstream phases may require Kit, Usd Optimize, usd-validation-nvidia, USD Python, writable output paths, and omniverse:// authentication selected by setup-usd-performance-tuning. metadata: author: NVIDIA Omniverse tags: @@ -22,254 +22,144 @@ metadata: --- # Omniverse USD Performance Tuning - - +## Scope -## When to Use +Use for broad USD performance work: slow loading, low FPS/interactivity, high GPU or system memory, GPU crash/device lost, validation failures, CAD/conversion-quality triage, profiling, or requests to optimize a scene. This skill owns the user-facing workflow; setup, authentication, profiling, validation, mutation, and reporting are executed by phase references when reached. -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. +Frontmatter keeps `version` and `tools` at top level for agentskills.io compatibility; NVCARPS fields live under `metadata`. -## Instructions +## Mandatory session-start gate -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. For broad optimization, default to 3 scoped iterations unless the user opts out, asks for a quick pass, or stop criteria apply. -4. Invoke downstream skill bodies only when their phase is reached, and keep raw runtime artifacts on disk while reading compact summaries. +Before any tuning output, except a static classification-only answer, follow `skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md`. That reference owns `output_path`, `setup-preflight.json`, Format A/Format B, and forbids silent ad hoc probing. -Frontmatter keeps `version` and `tools` at top level for agentskills.io runtime -compatibility. NVCARPS discoverability fields live under `metadata`. +Required behavior: -## Output Format +- Missing or unreadable preflight: invoke `setup-usd-performance-tuning`. +- Present preflight: print Format A and wait for Continue, Change Kit, Switch to standalone, or Re-run probe. +- Runtime already confirmed in this session: use compact Format B: -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). Broad optimization should plan 3 scoped iterations by default; each iteration writes an interim report/update and later passes reuse prior evidence instead of restarting the full workflow. +```text +[Kit: {runtime_context.kit.application} {runtime_context.kit.version} | SO: {runtime_context.usdOptimize.version} | AV: {runtime_context.assetValidator.version}] +``` -Use this workflow for broad performance asks such as slow loading, low FPS, -high memory, GPU crashes, conversion quality, or "optimize my scene." +For standalone/usd-optimize packages, runtime evidence must include package/sentinel checks plus shared-library or import/load verification, not just the Python executable/version. For `omniverse://` assets, route through `omniverse-authentication` before setup, triage, or first open. -## Entry skill rule +## Entry-skill and decision rules -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. +- Name `omniverse-usd-performance-tuning` as the entry skill whenever any runtime path is verified: Kit, standalone, or a partial stack such as usd-validation-nvidia only. If the requested tool or operation is missing, return the specific blocker code such as `blocked_missing_usd_optimize` or `blocked_missing_usd_optimize_operation`; do not substitute a different workflow. +- Name `setup-usd-performance-tuning` as entry only when no runtime path is verified and runtime choice/setup is the first unresolved problem. +- This is ownership, not phase order: authentication, setup, and triage still run in their normal order. -- 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. +Planning decision — derive `decision` from the response's shape, never from whether the request named a destructive op (the harness enforces the shape invariants): -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. +- `ready_to_plan` — nothing in this response awaits the user; `committed_milestones` equals `planned_phases`. This is the default for generic optimization: the lossless canonical chain, plus a proactive `auto-within-tolerance` bounded-loss pass (an over-tessellated, visually-toleranced target reduced at its conservative per-target band, applied with a one-line notice rather than a prompt). +- `approval_required` — this response halts at a gate it is surfacing now; `committed_milestones` is a strict prefix of `planned_phases`, and `approval_required_reason` names the gate. The trigger is an unresolved decision the agent must surface before it can plan the op, not the fact that an op is destructive. Default primitive-fitting on a fitting-candidate scene (e.g. BIM/CAD pipe and duct runs with `fitPrimitives` at default args) is the standard, expected win and stays `ready_to_plan`, gated at execution. A bounded-loss op (`decimateMeshes`, `fitPrimitives`) becomes **inline-elicited** — its tolerance or data-preservation parameter must be answered now — only when it would run above the conservative band, on a functional-precision target (`articulated`/physics/sim-ready/metrology/variant-bearing), or under an explicit preservation intent (the user asks to keep UVs/displayColors/subsets). A `decimateMeshes` request with no stated tolerance is inline-elicited via its one upfront `mm_tolerance` question. A `restructure-decision` the response is presenting now is `approval_required` for the same reason. See `usd-optimize-run-operations/references/operation-safety.md` for the apply-authority classes. +- `blocked` — a `blocked_code` applies. +- Future gates that genuinely fire later — a downstream `restructure-decision` not yet reached, identity-gated ops collected for the Phase 7 opt-in menu — belong in `gates_observed`, never in `decision`. -## Runtime context — session-start gate (mandatory) +## Canonical plan contract -**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. +For broad optimization, structured plans/status summaries must: -Required outcomes: +- Start milestone lists with `omniverse-usd-performance-tuning`; include `setup-usd-performance-tuning` only as Phase 0 context when relevant. +- Set top-level `decision` to `ready_to_plan` for generic optimization. +- Include the chain through `optimization-report` in both `committed_milestones` and `planned_phases`. +- Use exact profile labels `profile-stage:baseline` and `profile-stage:after`; never emit bare `profile-stage`. +- Preserve this subsequence exactly, inserting optional analysis only where it does not reorder it: -- 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. +`omniverse-usd-performance-tuning` -> `profile-stage:baseline` -> `usd-structure-assessment` -> `usd-validation-runner` -> `restructure-decision` -> `apply-restructure` -> `usd-optimize-run-validators` -> `usd-optimize-interpret-validators` -> `usd-optimize-run-operations` -> `profile-stage:after` -> `compare-profiles` -> `optimization-report` -``` -[Kit: {runtime_context.kit.application} {runtime_context.kit.version} | SO: {runtime_context.sceneOptimizer.version} | AV: {runtime_context.assetValidator.version}] -``` +Two milestones are **conditionally required** — when the trigger holds they must appear as committed milestones at this position, not merely be routed to: -## Runtime artifact token budget +- `usd-hierarchy-dedupe-candidates` — after `usd-structure-assessment`, before `restructure-decision`, whenever the stage shows repeated copied hierarchy, high mesh count with little or no instancing, or a monolithic root. Do not conclude `hierarchy_dedupe.recommended: false` without it. +- `usd-edit-target-planner` — after `apply-restructure`, before the Usd Optimize validator/operations chain, whenever the stage is composed (references or payloads) and each target must be optimized as its own root layer. -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. +Do not list `usd-optimize-run-validators` or `usd-optimize-interpret-validators` before `restructure-decision` in broad optimization milestone summaries. Phase-aware validator routing still happens inside `usd-validation-runner`. -## Plan-time vs execution-time approval +Default broad optimization to three scoped iterations unless the user opts out, asks for a quick pass, or stop criteria apply. Each iteration writes an interim report/update; later passes reuse prior evidence instead of restarting the full workflow. -`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`: +## Execution discipline -- **`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**. +- Load `references/workflow.md` before end-to-end execution; it owns Phase 0-7 flow, Kit/standalone branches, validator routing, operation ordering, termination criteria, duration hints, and the default three-pass pattern. +- Do not treat nested phase names as checklist labels. Before executing a phase, load that phase's nested `README.md` or reference and follow it. Invoke downstream skill bodies only when their phase is reached. +- If local workspace instructions or helper commands are supplied, inspect them and use them to create, validate, or render required artifacts. If a file/tool is unavailable, report the observed blocker instead of fabricating completion. +- For binary or large assets, do not print raw contents. Use bounded metadata, checksums, sizes, validation/profile summaries, compact facts, or tool reports. +- Before reading Kit logs, usd-validation-nvidia CSVs, Usd Optimize 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 snapshots rather than full dumps or live streams. -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. +Minimum context to gather: target stage, problem/goal, local/mounted/remote location, runtime, workload type when known, diagnosis-only vs mutation, and permission/output target for writes. Never overwrite the source unless explicitly allowed; prefer a separate optimized output for mutation. Do not invent thresholds, percentage wins, metrics, or runtime evidence. -For structured runtime-test responses and similar planning summaries: +## Routing map -- 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. +- Composition, structure, layer health, instancing readiness: `usd-structure-assessment`. +- Validation/content issues: `usd-validation-runner`, which routes to validate-* or Usd Optimize validators as needed. +- Edit target, variant, payload, and output decisions: `usd-edit-target-planner`. +- Repeated copied hierarchy/high mesh count with no instancing: `usd-hierarchy-dedupe-candidates`. +- Monolithic stage or asset-boundary materialization: `restructure-decision` then `apply-restructure` when approved. +- CAD converter settings: `references/cad-conversion/README.md`. +- Usd Optimize execution: `usd-optimize-run-validators`, `usd-optimize-interpret-validators`, `usd-optimize-run-operations`. +- Full Kit runtime profiling such as FPS, frame time, Hydra/RTX metrics: external NVIDIA/omniperf profiling skills. -## Output expectation +Before routing broad work, read the `usd-structure-assessment` tradeoff references for pipeline phase and factory-level structuring when those decisions matter. -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. +## Mutation and operation rules -## Purpose +Follow `references/workflow.md#operation-ordering-invariants`. High-level invariant: prototypes first -> per-asset validation -> stage-level operations last. -Route digital twin USD performance requests into the right diagnostic and -optimization workflow while preserving evidence before mutation. +Always: -## Prerequisites +- Run composition audit before mutation. +- Validate before and after processor execution. +- Optimize prototypes before per-asset validation. +- Check hierarchy-level reuse before whole-stage mesh dedupe on very large CAD scenes. +- Base recommendations on bottleneck evidence; do not recommend fixed stacks without findings. +- Do not authorize mutation when writes are not allowed. -- 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. +Usd Optimize curation: -## Examples +- Prefer `canonical` operations from `references/operations/operations.json` when multiple ops could address the same finding. +- Vertex welding: prefer canonical `meshCleanup` with explicit flags over standalone `mergeVertices`; follow upstream `usd-optimize` mechanics and local approval policy before mutating. +- Hierarchy dedupe: for the Phase 2 descent, prefer `usd-hierarchy-dedupe-candidates` plus `apply-restructure` (it owns the manifest/identity contract); a standalone approved-chain dedup run drives `deduplicateHierarchies` directly, invoked per frontier region (`paths` + per-region `maxDepth`). +- Per-mesh dedupe: prefer canonical `deduplicateGeometry`; `findCoincidingGeometry` is analysis/report only. +- Do not agent-initiate `documentary` operations such as `boxClip`, `deletePrims`, `removeAttributes`, `removeUntypedPrims`, or broad `merge` except in its narrow non-instanced case, unless explicitly requested. +- `specialty` operations are allowed when validator evidence wires them into `usd-optimize-interpret-validators` or downstream context requires them, such as `sparseMeshes`, `optimizePrimvars`, `primitivesToMeshes`, `utilityFunction`, or `pythonScript` recipes. -- "This USD loads slowly; triage what to check first." -- "Route a low-FPS CAD scene through the performance workflow." +## Deliverables and final response -## Triage order +End-to-end optimization must produce an optimized USD stage when mutation runs and an `optimization-report` report. Diagnosis-only work must still end with a report or summary stating that no optimized stage was written. -0. **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. +Report requirements: -1. Identify the target problem: - - Load time. - - FPS or interactivity. - - GPU or system memory. - - Crash or device lost. - - CAD conversion quality. - - Validation failure. +- Structured JSON must conform to `optimization-report`'s `scripts/optimization-report.schema.json`. +- Save the generated Markdown summary. +- Render HTML from `references/report-templates/optimization-report.html.template` via `render_preview.py`; never hand-write HTML. +- Do not substitute an ad hoc summary file or chat-only recap for report artifacts. -2. 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. +Final runtime response must explicitly name: -3. 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`. +- selected entry skill and selected runtime/preflight state, including standalone package sentinel/load evidence when applicable; +- optimized USD output path when written, or that no mutation ran; +- source-not-overwritten/in-place mutation status; +- exact operation chain executed, especially safe/lossless chains when claimed; +- before/after validation and profile metrics available from evidence; +- validated report JSON, generated Markdown, rendered HTML, schema/validation verdict, score when present, and `workflow_mode`. -## Optimization ordering +If preflight is missing, validation/rendering failed, report artifacts are absent, or no mutation ran, say so plainly and do not replace missing artifacts with a chat-only recap. -Follow the canonical ordering in -[workflow.md § Operation ordering invariants](references/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. +## Limitations and references -## Rules +This skill does not install runtimes, replace downstream reference instructions, authenticate remote assets itself, approve unrequested destructive writes, or guarantee performance gains without evidence. If runtime status is unclear, return to the setup gate; if mutation appears before evidence, return to baseline profiling and composition audit first. -- 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/.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 default three-pass scoped -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/README.md` - tier 1/2/3 selected-probe plan, large-stage guardrails, full-sweep approval, and 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. +Primary references: + +- `references/workflow.md` +- `references/runtime-artifact-token-budget.md` +- `references/skill-map.md` +- `skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md` +- `skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/optimization-tradeoffs.md` +- `skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/factory-level-structuring.md` +- `skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/composition-audit.md` +- `skills/omniverse-usd-performance-tuning/references/usd-validation-runner/README.md` +- `skills/omniverse-usd-performance-tuning/references/optimization-report/references/optimization-report-template.md` +- `references/upstreams/usd-optimize.md` + +Use live URLs noted in reference files when network access is available and current upstream behavior matters. diff --git a/skills/omniverse-usd-performance-tuning/agents/openai.yaml b/skills/omniverse-usd-performance-tuning/agents/openai.yaml index 7c4ce812..fcfddcc7 100644 --- a/skills/omniverse-usd-performance-tuning/agents/openai.yaml +++ b/skills/omniverse-usd-performance-tuning/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "USD Performance Tuning" short_description: "Diagnose and optimize OpenUSD scene performance" - default_prompt: "Use $omniverse-usd-performance-tuning to diagnose and optimize a USD stage: confirm runtime context, capture baseline evidence, assess structure, route validation, run approved Scene Optimizer work, compare results, and produce the final optimization report." + default_prompt: "Use $omniverse-usd-performance-tuning to diagnose and optimize a USD stage: confirm runtime context, capture baseline evidence, assess structure, route validation, run approved Usd Optimize work, compare results, and produce the final optimization report." diff --git a/skills/omniverse-usd-performance-tuning/evals/evals.json b/skills/omniverse-usd-performance-tuning/evals/evals.json index a6b24b40..818f7d0d 100644 --- a/skills/omniverse-usd-performance-tuning/evals/evals.json +++ b/skills/omniverse-usd-performance-tuning/evals/evals.json @@ -1,128 +1,115 @@ -{ - "version": "0.1.0", - "skill": "omniverse-usd-performance-tuning", - "cases": [ - { - "id": "usd-performance-broad-optimization-flow", - "question": "The main factory USD stage takes minutes to open in USD Composer and likely has repeated assemblies. Please optimize it so it loads faster and produces a clear report.", - "expected_skill": "omniverse-usd-performance-tuning", - "expected_script": null, - "ground_truth": "The agent should select the USD performance tuning workflow, start with runtime/auth bring-up, then plan baseline profiling, structure assessment, validation routing, restructure decision handling, Scene Optimizer operation planning when available, after-profile comparison, and the required optimization report.", - "expected_behavior": [ - "Reads the omniverse-usd-performance-tuning SKILL.md.", - "Classifies the request as a broad USD performance optimization request rather than a direct single-operation command.", - "Starts with the mandatory runtime context gate before profiling, validation, or mutation.", - "Plans baseline profiling and usd-structure-assessment before any mutating optimization step.", - "Includes validation routing before mutation and an optimization-report deliverable after verification." - ] - }, - { - "id": "usd-performance-runtime-choice-gate", - "question": "Optimize /tmp/factory.usd. I have not said whether to use Kit or standalone libraries, and there is no existing runtime probe result.", - "expected_skill": "omniverse-usd-performance-tuning", - "expected_script": null, - "ground_truth": "The agent should not silently pick Kit or standalone. It should route to setup-usd-performance-tuning and ask for the runtime choice before opening, profiling, validating, or optimizing the stage.", - "expected_behavior": [ - "Reads the omniverse-usd-performance-tuning SKILL.md.", - "Recognizes that runtime choice is unresolved.", - "Routes to setup-usd-performance-tuning for the runtime chooser.", - "Asks for an explicit Kit or standalone runtime path before doing work.", - "Does not open, profile, validate, or mutate the stage before the runtime gate is resolved." - ] - }, - { - "id": "usd-performance-destructive-op-approval", - "question": "Flatten /tmp/factory.usd into one layer and decimate the high-poly meshes so it runs faster in our Kit-based viewer.", - "expected_skill": "omniverse-usd-performance-tuning", - "expected_script": null, - "ground_truth": "The agent should treat flattening and decimation as explicitly requested destructive operations, ask for approval before mutation, and preserve the decimation guardrails from the operation reference.", - "expected_behavior": [ - "Reads the omniverse-usd-performance-tuning SKILL.md.", - "Sets the planning decision to require approval before destructive mutation.", - "Names flattening and decimation in the approval prompt.", - "Plans structural assessment and validation before mutation if approval is granted.", - "Uses one upfront decimation prompt and preserves pinBoundaries plus floating-point stop-condition values." - ] - }, - { - "id": "usd-performance-expensive-validation-approval", - "question": "Optimize /tmp/factory.usd. The structure assessment suggests occlusion checks and cross-component duplicate checks may be useful before optimization.", - "expected_skill": "omniverse-usd-performance-tuning", - "expected_script": null, - "ground_truth": "The agent should plan targeted validation and ask before expensive cross-component validators such as occlusion, coincident-geometry, or duplicate-analysis checks run on a large or unknown-size asset.", - "expected_behavior": [ - "Reads the omniverse-usd-performance-tuning SKILL.md.", - "Routes validation through usd-validation-runner and its validation scoping guidance.", - "Treats expensive cross-component checks as opt-in.", - "Asks the user before running slow Tier 3-style validation work.", - "Keeps the final workflow anchored on an optimization-report deliverable." - ] - }, - { - "id": "usd-performance-viewer-build-distractor-negative", - "question": "Build a browser-based RTX USD viewer with camera controls, object picking, a stage tree, and render settings.", - "expected_skill": null, - "expected_script": null, - "ground_truth": "This is an application/viewer construction request, not a USD performance diagnosis or optimization workflow.", - "expected_behavior": [ - "Does not select omniverse-usd-performance-tuning.", - "Does not run profiling, validation, Scene Optimizer operations, or optimization-report steps.", - "Routes to a viewer or application-building skill if one is available." - ] - }, - { - "id": "usd-performance-structural-only-report", - "question": "Optimize /tmp/factory.usd, but Scene Optimizer is not installed in my runtime and I don't want to install anything right now. Still give me a report.", - "expected_skill": "omniverse-usd-performance-tuning", - "expected_script": null, - "ground_truth": "With Scene Optimizer unavailable and install declined, the workflow runs in structural-only mode: structure assessment plus pre-mutation USD validation, no mesh operations. The final report keeps verdict within its enum (neutral if nothing changed), sets workflow_mode to structural_only, and records the Scene Optimizer blocker in notes. It must not invent a structural-only verdict value.", - "expected_behavior": [ - "Reads the omniverse-usd-performance-tuning SKILL.md.", - "Recognizes Scene Optimizer is unavailable and install was declined, and continues in structural-only mode rather than halting or fabricating results.", - "Skips the Scene Optimizer mesh-operation phases.", - "Produces a report whose verdict stays within improved|neutral|regressed|mixed and sets workflow_mode to structural_only.", - "Records the Scene Optimizer blocker and the next profile capture needed in the report notes." - ] - }, - { - "id": "usd-performance-report-schema-conformance", - "question": "Finish the optimization run on /tmp/factory.usd and write the final report.", - "expected_skill": "omniverse-usd-performance-tuning", - "expected_script": null, - "ground_truth": "The final optimization report must conform to optimization-report.schema.json. The agent should validate the report JSON with python3 scripts/validate_report.py before treating it as final, generate HTML via the renderer with --fixture/--output, and must not emit out-of-enum verdicts or invented top-level fields.", - "expected_behavior": [ - "Reads the omniverse-usd-performance-tuning SKILL.md and the optimization-report reference.", - "Generates the report JSON against optimization-report.schema.json with verdict in improved|neutral|regressed|mixed.", - "Validates the finished report with python3 scripts/validate_report.py before finishing.", - "Generates the HTML via render_preview.py with --fixture and --output, not by hand and not argless.", - "Does not invent verdict values such as structural-only or no-op-needed." - ] - }, - { - "id": "usd-performance-no-overwrite-source", - "question": "Run mesh cleanup and decimation on /data/asset.usd to make it lighter.", - "expected_skill": "omniverse-usd-performance-tuning", - "expected_script": null, - "ground_truth": "Destructive Scene Optimizer operations must write a new optimized output path and must not overwrite the source asset in place. The agent should also ask for approval before the explicitly named destructive operations.", - "expected_behavior": [ - "Reads the omniverse-usd-performance-tuning SKILL.md.", - "Asks for approval before the explicitly named destructive operations (mesh cleanup, decimation).", - "Saves optimized output to a new path and does not overwrite the original source asset.", - "Validates before and after the operations and records the output path in the optimization report." - ] - }, - { - "id": "usd-performance-zero-work-operation", - "question": "I ran the optimization and the operation report says it completed - did anything actually change?", - "expected_skill": "omniverse-usd-performance-tuning", - "expected_script": null, - "ground_truth": "A Scene Optimizer operation can return success while changing nothing (zero prims affected). The agent should detect a successful-but-no-op result by comparing before/after metrics, report it honestly as neutral, and not claim an improvement the metrics do not support.", - "expected_behavior": [ - "Reads the omniverse-usd-performance-tuning SKILL.md.", - "Compares before/after metrics rather than trusting the operation's success status alone.", - "Recognizes a success-but-zero-work result (no prims or meshes changed) and reports it as neutral.", - "Does not present an unchanged stage as an improvement in the optimization report." - ] - } - ] -} +[ + { + "id": "usd-performance-broad-optimization-flow", + "question": "The main factory USD stage takes minutes to open in USD Composer and likely has repeated assemblies. Please optimize it so it loads faster and produces a clear report.", + "expected_skill": "omniverse-usd-performance-tuning", + "ground_truth": "The agent should select the USD performance tuning workflow, start with runtime/auth bring-up, then plan baseline profiling, structure assessment, validation routing, restructure decision handling, Usd Optimize operation planning when available, after-profile comparison, and the required optimization report.", + "expected_behavior": [ + "Reads the omniverse-usd-performance-tuning SKILL.md.", + "Classifies the request as a broad USD performance optimization request rather than a direct single-operation command.", + "Starts with the mandatory runtime context gate before profiling, validation, or mutation.", + "Plans baseline profiling and usd-structure-assessment before any mutating optimization step.", + "Includes validation routing before mutation and an optimization-report deliverable after verification." + ] + }, + { + "id": "usd-performance-runtime-choice-gate", + "question": "Optimize /tmp/factory.usd. I have not said whether to use Kit or standalone libraries, and there is no existing runtime probe result.", + "expected_skill": "omniverse-usd-performance-tuning", + "ground_truth": "The agent should not silently pick Kit or standalone. It should route to setup-usd-performance-tuning and ask for the runtime choice before opening, profiling, validating, or optimizing the stage.", + "expected_behavior": [ + "Reads the omniverse-usd-performance-tuning SKILL.md.", + "Recognizes that runtime choice is unresolved.", + "Routes to setup-usd-performance-tuning for the runtime chooser.", + "Asks for an explicit Kit or standalone runtime path before doing work.", + "Does not open, profile, validate, or mutate the stage before the runtime gate is resolved." + ] + }, + { + "id": "usd-performance-destructive-op-approval", + "question": "Flatten /tmp/factory.usd into one layer and decimate the high-poly meshes so it runs faster in our Kit-based viewer.", + "expected_skill": "omniverse-usd-performance-tuning", + "ground_truth": "The agent should treat flattening and decimation as explicitly requested destructive operations, ask for approval before mutation, and preserve the decimation guardrails from the operation reference.", + "expected_behavior": [ + "Reads the omniverse-usd-performance-tuning SKILL.md.", + "Sets the planning decision to require approval before destructive mutation.", + "Names flattening and decimation in the approval prompt.", + "Plans structural assessment and validation before mutation if approval is granted.", + "Uses one upfront decimation prompt and preserves pinBoundaries plus floating-point stop-condition values." + ] + }, + { + "id": "usd-performance-expensive-validation-approval", + "question": "Optimize /tmp/factory.usd. The structure assessment suggests occlusion checks and cross-component duplicate checks may be useful before optimization.", + "expected_skill": "omniverse-usd-performance-tuning", + "ground_truth": "The agent should plan targeted validation and ask before expensive cross-component validators such as occlusion, coincident-geometry, or duplicate-analysis checks run on a large or unknown-size asset.", + "expected_behavior": [ + "Reads the omniverse-usd-performance-tuning SKILL.md.", + "Routes validation through usd-validation-runner and its validation scoping guidance.", + "Treats expensive cross-component checks as opt-in.", + "Asks the user before running slow Tier 3-style validation work.", + "Keeps the final workflow anchored on an optimization-report deliverable." + ] + }, + { + "id": "usd-performance-viewer-build-distractor-negative", + "question": "Build a browser-based RTX USD viewer with camera controls, object picking, a stage tree, and render settings.", + "expected_skill": null, + "ground_truth": "This is an application/viewer construction request, not a USD performance diagnosis or optimization workflow.", + "expected_behavior": [ + "Does not select omniverse-usd-performance-tuning.", + "Does not run profiling, validation, Usd Optimize operations, or optimization-report steps.", + "Routes to a viewer or application-building skill if one is available." + ] + }, + { + "id": "usd-performance-structural-only-report", + "question": "Optimize /tmp/factory.usd, but Usd Optimize is not installed in my runtime and I don't want to install anything right now. Still give me a report.", + "expected_skill": "omniverse-usd-performance-tuning", + "ground_truth": "With Usd Optimize unavailable and install declined, the workflow runs in structural-only mode: structure assessment plus pre-mutation USD validation, no mesh operations. The final report keeps verdict within its enum (neutral if nothing changed), sets workflow_mode to structural_only, and records the Usd Optimize blocker in notes. It must not invent a structural-only verdict value.", + "expected_behavior": [ + "Reads the omniverse-usd-performance-tuning SKILL.md.", + "Recognizes Usd Optimize is unavailable and install was declined, and continues in structural-only mode rather than halting or fabricating results.", + "Skips the Usd Optimize mesh-operation phases.", + "Produces a report whose verdict stays within improved|neutral|regressed|mixed and sets workflow_mode to structural_only.", + "Records the Usd Optimize blocker and the next profile capture needed in the report notes." + ] + }, + { + "id": "usd-performance-report-schema-conformance", + "question": "Finish the optimization run on /tmp/factory.usd and write the final report.", + "expected_skill": "omniverse-usd-performance-tuning", + "ground_truth": "The final optimization report must conform to optimization-report.schema.json. The agent should validate the report JSON with python3 scripts/validate_report.py before treating it as final, generate HTML via the renderer with --fixture/--output, and must not emit out-of-enum verdicts or invented top-level fields.", + "expected_behavior": [ + "Reads the omniverse-usd-performance-tuning SKILL.md and the optimization-report reference.", + "Generates the report JSON against optimization-report.schema.json with verdict in improved|neutral|regressed|mixed.", + "Validates the finished report with python3 scripts/validate_report.py before finishing.", + "Generates the HTML via render_preview.py with --fixture and --output, not by hand and not argless.", + "Does not invent verdict values such as structural-only or no-op-needed." + ] + }, + { + "id": "usd-performance-no-overwrite-source", + "question": "Run mesh cleanup and decimation on /data/asset.usd to make it lighter.", + "expected_skill": "omniverse-usd-performance-tuning", + "ground_truth": "Destructive Usd Optimize operations must write a new optimized output path and must not overwrite the source asset in place. The agent should also ask for approval before the explicitly named destructive operations.", + "expected_behavior": [ + "Reads the omniverse-usd-performance-tuning SKILL.md.", + "Asks for approval before the explicitly named destructive operations (mesh cleanup, decimation).", + "Saves optimized output to a new path and does not overwrite the original source asset.", + "Validates before and after the operations and records the output path in the optimization report." + ] + }, + { + "id": "usd-performance-zero-work-operation", + "question": "I ran the optimization and the operation report says it completed - did anything actually change?", + "expected_skill": "omniverse-usd-performance-tuning", + "ground_truth": "A Usd Optimize operation can return success while changing nothing (zero prims affected). The agent should detect a successful-but-no-op result by comparing before/after metrics, report it honestly as neutral, and not claim an improvement the metrics do not support.", + "expected_behavior": [ + "Reads the omniverse-usd-performance-tuning SKILL.md.", + "Compares before/after metrics rather than trusting the operation's success status alone.", + "Recognizes a success-but-zero-work result (no prims or meshes changed) and reports it as neutral.", + "Does not present an unchanged stage as an improvement in the optimization report." + ] + } +] diff --git a/skills/omniverse-usd-performance-tuning/references/_shared/standard-instructions.md b/skills/omniverse-usd-performance-tuning/references/_shared/standard-instructions.md new file mode 100644 index 00000000..c74b65ed --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/_shared/standard-instructions.md @@ -0,0 +1,6 @@ +# Standard Instructions + +1. Confirm the target asset, artifact, or user intent and check the prerequisites listed below. +2. Read only the referenced files needed for the current phase, failure mode, or output contract. +3. Follow the workflow, rules, and safety gates in this reference before invoking downstream references or shell commands. +4. Return the result using the Output Format section and name any blocked prerequisite or unresolved user decision. diff --git a/skills/omniverse-usd-performance-tuning/references/_shared/standard-output-format.md b/skills/omniverse-usd-performance-tuning/references/_shared/standard-output-format.md new file mode 100644 index 00000000..d72ce87d --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/_shared/standard-output-format.md @@ -0,0 +1,3 @@ +# Standard Output Format + +Return a concise status or report that names the input, selected runtime or evidence source, actions planned or performed, artifacts written, blockers, and the next validation or user-decision step. When a schema or template is referenced below, conform to that contract. diff --git a/skills/omniverse-usd-performance-tuning/references/cad-conversion/README.md b/skills/omniverse-usd-performance-tuning/references/cad-conversion/README.md index df859b18..69971e7a 100644 --- a/skills/omniverse-usd-performance-tuning/references/cad-conversion/README.md +++ b/skills/omniverse-usd-performance-tuning/references/cad-conversion/README.md @@ -1,6 +1,3 @@ - - - # CAD-to-USD Conversion Advisor > CAD conversion is a pre-USD concern; `omniverse-usd-performance-tuning` cites this reference when the user reports `problem_type = conversion quality`. @@ -42,7 +39,7 @@ Guide CAD-to-USD conversion diagnosis before optimization. Capture the source fo ## Limitations -- Does not execute conversion or Scene Optimizer operations. +- Does not execute conversion or Usd Optimize operations. - Cannot guarantee a tessellation knob exists for every source format or backend. - Post-conversion performance issues still need composition audit and validation. diff --git a/skills/omniverse-usd-performance-tuning/references/compare-profiles.md b/skills/omniverse-usd-performance-tuning/references/compare-profiles.md index ad8575aa..802ff9d6 100644 --- a/skills/omniverse-usd-performance-tuning/references/compare-profiles.md +++ b/skills/omniverse-usd-performance-tuning/references/compare-profiles.md @@ -7,8 +7,6 @@ agent_next: freshness: 2026-05-20 version: "0.1.0" --- - - # Compare Profiles Contract @@ -18,13 +16,10 @@ workflow reference remains ## Required Inputs -- A baseline `profile-stage` JSON capture. -- An after/optimized `profile-stage` JSON capture. -- Matching profile mode: quick vs quick or full vs full. -- Same hardware and runtime for full-mode comparisons unless the user - explicitly accepts cross-runtime comparison. -- The operation chain, restructure step, or validation-driven fix applied - between the two captures. +See [compare-profiles/README.md § Required Inputs](compare-profiles/README.md#required-inputs) +for the authoritative input list (paired baseline/after `profile-stage` JSON, +matching mode, same hardware/runtime for full mode, and the change applied +between captures). ## Verdict Thresholds @@ -58,8 +53,6 @@ terminal optimization report. ## Regression Handling -When a metric regresses by more than 5%, name the metric, quantify the change, -and correlate it with what changed. File-size growth after Scene Optimizer -operations may indicate USDC save behavior. Prim-count growth after instancing -can be acceptable when instances compensate for added prototypes. Steady-state -frame regressions are more serious than one-time startup regressions. +See [compare-profiles/README.md § Regression handling](compare-profiles/README.md#regression-handling) +for the authoritative regression-handling steps (name the metric and quantify the +change, correlate with what changed, check known causes, and decide keep/revert/adjust). diff --git a/skills/omniverse-usd-performance-tuning/references/compare-profiles/README.md b/skills/omniverse-usd-performance-tuning/references/compare-profiles/README.md index 22f0b74b..b0d39a00 100644 --- a/skills/omniverse-usd-performance-tuning/references/compare-profiles/README.md +++ b/skills/omniverse-usd-performance-tuning/references/compare-profiles/README.md @@ -1,31 +1,25 @@ # Compare Profiles - - - ## When to Use Use when comparing matching baseline/after profiles; do not use without paired profile-stage JSON. ## Instructions -1. Confirm the target asset, artifact, or user intent and check the prerequisites listed below. -2. Read only the referenced files needed for the current phase, failure mode, or output contract. -3. Follow the workflow, rules, and safety gates in this reference before invoking downstream references or shell commands. -4. Return the result using the Output Format section and name any blocked prerequisite or unresolved user decision. - +See `references/_shared/standard-instructions.md`. ## Pre-flight Checklist Before computing the comparison verdict, re-read and confirm: -- [ ] Verdict thresholds — see the Verdict Thresholds section in this file +- [ ] Verdict thresholds — see + [compare-profiles.md § Verdict Thresholds](../compare-profiles.md#verdict-thresholds) for improvement/regression bands. - [ ] `runtime-artifact-token-budget.md` — don't dump raw profile data. - [ ] Both baseline and after profiles used same measurement method. ## Output Format -Return a concise status or report that names the input, selected runtime or evidence source, actions planned or performed, artifacts written, blockers, and the next validation or user-decision step. When a schema or template is referenced below, conform to that contract. +See `references/_shared/standard-output-format.md`. Use this reference after running `profile-stage` both before and after optimization. It compares the two result sets and reports whether the changes helped, hurt, @@ -36,13 +30,13 @@ or had no measurable effect. Before reporting the verdict, prepend the **compact one-liner** from `skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md` (Format B). The verdict is only reproducible against the runtime that produced it; users reading the verdict -later need to know which Kit / Scene Optimizer / Asset Validator versions +later need to know which Kit / Usd Optimize / usd-validation-nvidia versions were in effect. Read from the `runtime_context` block in `/setup-preflight.json` (canonical location; see `skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md` *Where artifacts live*). ``` -[Kit: {runtime_context.kit.application} {runtime_context.kit.version} | SO: {runtime_context.sceneOptimizer.version} | AV: {runtime_context.assetValidator.version}] +[Kit: {runtime_context.kit.application} {runtime_context.kit.version} | SO: {runtime_context.usdOptimize.version} | AV: {runtime_context.assetValidator.version}] ``` If a profile capture spans more than one runtime (rare — usually means the @@ -56,26 +50,28 @@ the comparison output regardless. Quantify before/after performance deltas, classify improvements and regressions, and produce an evidence-backed verdict for the optimization flow. -## Prerequisites +## Required Inputs -- Baseline and optimized JSON results from `profile-stage`. -- Matching profile mode: quick vs quick or full vs full. -- Same hardware and runtime environment for full mode comparisons. -- Knowledge of the operations applied between the two captures. +This is the authoritative input list for `compare-profiles`; the docs-class +[compare-profiles.md](../compare-profiles.md#required-inputs) points here. -## Examples +Two profile results (JSON from `profile-stage`): -- "Compare these quick profile JSON files and flag regressions." -- "Did the optimized Kit trace improve runtime frame cost?" +- `baseline` — captured before optimization. +- `optimized` (after) — captured after optimization. -## Inputs +Plus: -Two profile results (JSON from `profile-stage`): +- Matching profile mode: quick vs quick or full vs full. +- Same hardware and runtime environment for full-mode comparisons, unless the + user explicitly accepts a cross-runtime comparison. +- Knowledge of the operation chain, restructure step, or validation-driven fix + applied between the two captures. -- `baseline` — captured before optimization. -- `optimized` — captured after optimization. +## Examples -Both must use the same mode (quick or full). +- "Compare these quick profile JSON files and flag regressions." +- "Did the optimized Kit trace improve runtime frame cost?" ## Comparison metrics @@ -105,10 +101,10 @@ Both must use the same mode (quick or full). ## Significance thresholds -- **Improvement:** metric improved by >5% — report as gain. -- **Neutral:** within ±5% — report as no significant change. -- **Regression:** metric worsened by >5% — flag as potential problem. -- **Critical regression:** metric worsened by >20% — flag prominently, the optimization may have backfired. +See [compare-profiles.md § Verdict Thresholds](../compare-profiles.md#verdict-thresholds) +for the canonical improvement / neutral / regression / critical-regression bands +(>5% gain, ±5% neutral, >5% regression, >20% critical) and the "report absolute +values and percentages together" rule. ## Warm-load confidence @@ -144,7 +140,7 @@ If any metric regressed >5%: 1. Report which metric regressed and by how much. 2. Correlate with what changed — did file size grow? Did prim count increase? 3. Check for known causes: - - Size regression after SO operations → likely USDC `Layer.Save()` bloat + - Size regression after Usd Optimize operations → likely USDC `Layer.Save()` bloat (see `skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/output-saving.md`). - Load time regression after adding instancing → unexpected, investigate prototype count vs instance count ratio. @@ -163,7 +159,7 @@ omniverse-usd-performance-tuning → usd-validation-runner (master router; uses skills/omniverse-usd-performance-tuning/references/usd-validation-runner/README.md for tier detail and selected-probe policy) → restructure-decision (Phase 2e gate) → instancing-readiness (if applicable) -→ SO operations / instancing +→ Usd Optimize operations / instancing → apply-restructure (Phase 5 ref-remap) → profile-stage (AFTER) → compare-profiles diff --git a/skills/omniverse-usd-performance-tuning/references/omniverse-authentication/README.md b/skills/omniverse-usd-performance-tuning/references/omniverse-authentication/README.md index 952d9ec0..bf258d16 100644 --- a/skills/omniverse-usd-performance-tuning/references/omniverse-authentication/README.md +++ b/skills/omniverse-usd-performance-tuning/references/omniverse-authentication/README.md @@ -1,27 +1,21 @@ # Omniverse Authentication - - - ## When to Use Use when omniverse:// assets need Kit or omni.client auth preflight. Do not use for local USD files. ## Instructions -1. Confirm the target asset, artifact, or user intent and check the prerequisites listed below. -2. Read only the referenced files needed for the current phase, failure mode, or output contract. -3. Follow the workflow, rules, and safety gates in this reference before invoking downstream references or shell commands. -4. Return the result using the Output Format section and name any blocked prerequisite or unresolved user decision. +See `references/_shared/standard-instructions.md`. ## Output Format -Return a concise status or report that names the input, selected runtime or evidence source, actions planned or performed, artifacts written, blockers, and the next validation or user-decision step. When a schema or template is referenced below, conform to that contract. +See `references/_shared/standard-output-format.md`. ## Purpose Use this before opening `omniverse://` assets from Kit, USD Python, validators, -or Scene Optimizer operations. +or Usd Optimize operations. Confirm the agent can access the remote stage and explain any authentication side effects. A browser window or SSO prompt is expected on first access and is diff --git a/skills/omniverse-usd-performance-tuning/references/operations/CLASSIFICATION.md b/skills/omniverse-usd-performance-tuning/references/operations/CLASSIFICATION.md index 8e562ce5..4629bba0 100644 --- a/skills/omniverse-usd-performance-tuning/references/operations/CLASSIFICATION.md +++ b/skills/omniverse-usd-performance-tuning/references/operations/CLASSIFICATION.md @@ -8,84 +8,46 @@ agent_next: freshness: 2026-05-20 version: "0.1.0" --- - - # Operation Classification Rubric -Every entry in `references/operations/_curation.json` has a `status` field assigned by this rubric. Every entry's `rationale` field must cite the specific clause below it satisfies, with the format `: : `. +Every operation's nested `curation` block in `references/operations/operations.json` has a `status` field. **`status` is DERIVED, not hand-authored**: it is computed by the upstream status-derivation rubric (run during skill development) and materialized onto each entry, the same way the index is regenerated from source. The development-time coverage audit rewrites any drifted statuses. -This rubric is local routing policy only. Scene Optimizer operation mechanics +**The upstream status-derivation rubric is the single source of truth for the algorithm** — the derivation precedence (deprecated/specialty overrides → destructive→specialty → read-only→analysis → refs-present→canonical → else documentary), the reference-evidence rule (`wired_into` non-empty OR `pipelines` non-empty), and the clause definitions (C1/C2, S1/S2, A1–A3, D1–D3, X1/X2). This file does NOT restate them; it explains what each tier *means* for agent behavior and the hand-authored override contract. + +This rubric is local routing policy only. Usd Optimize operation mechanics belong to upstream `usd-optimize`; use [`usd-optimize` upstream handoff](../upstreams/usd-optimize.md) for the central package and operation-guide resolution rule. -## status: canonical - -The op is part of the standard 7-phase optimization flow described in -`skills/omniverse-usd-performance-tuning/references/workflow.md`. At -least one local workflow reference routes to it, or upstream `usd-optimize` -names it in a public pipeline that this workflow deliberately adopts. The -agent reaches for canonical ops by default. - -Required evidence: - -- **C1.** The op has at least one `"operation": ""` reference in the catalog skill or nested workflow references OR in an adopted upstream `usd-optimize` named pipeline, **and** -- **C2.** The op is `loss_class: lossless` or `bounded-loss` (not `destructive`). - -A `destructive` op is `specialty`, never `canonical`, regardless of how often it appears. - -## status: specialty - -The op is gated behind explicit user confirmation in `so-run-operations`'s destructive-op table, or has narrow workflow-specific applicability (e.g., `pythonScript` used by `so-create-proxy` for USD authoring glue). - -Required evidence: - -- **S1.** The op is `loss_class: destructive` and appears in the `so-run-operations` destructive-op confirmation table, **or** -- **S2.** The op is referenced in a skill body that handles a specific workflow (proxy creation, restructure orchestration, etc.) and the rationale names that workflow. - -## status: analysis +## What each tier means for agent selection -The op is read-only and produces a report/finding; used by `so-run-validators` or `so-interpret-validators`. Never mutates the stage. +The code computes the label; this is what the label means when the agent picks an op: -Required evidence: +- **`canonical`** — reach for it by default; part of the standard 7-phase optimization flow. +- **`specialty`** — reach for it only on an explicit need or named workflow (e.g. proxy creation, restructure orchestration); not a default choice. +- **`analysis`** — a read-only finding/report producer; surface it to inspect, never to mutate the stage. +- **`documentary`** — recommend only when the user explicitly names the op or describes a use case it uniquely fits. +- **`deprecated`** — warn before recommending, and name the replacement. -- **A1.** The op is `loss_class: lossless`, **and** -- **A2.** The op produces a structured finding rather than a transformed stage (often a `find*`, `count*`, or `print*` op), **and** -- **A3.** The op is either currently wired into `so-run-validators`/`so-interpret-validators` OR is a clear candidate for that wiring (`wired_into` may be empty for future-candidate analysis ops). +## Overrides and `rationale` -## status: documentary +`deprecated` and `specialty` are the only values `curation.status_override` may take — they are the two statuses the per-op data cannot express, so they are authored, not derived. Each override entry carries an authored `rationale` (forbidden on every other entry): -The op has a local routing stub for completeness but no local workflow route reaches for it. The agent is allowed to recommend it only when the user explicitly names the op or describes a use case it uniquely fits. - -Required evidence: - -- **D1.** The op has zero `"operation": ""` references in skill bodies, **and** -- **D2.** The op is not in an adopted upstream `usd-optimize` pipeline for this workflow, **and** -- **D3.** The op is not in the tuning workflow's recommended-ops sections. - -`documentary` ops MAY appear as a passing mention in the tuning workflow's -op-role index without being recommended for use — that doesn't disqualify them -from this tier. - -## status: deprecated - -The op exists upstream but this skill pack actively discourages its use. The agent should warn before recommending one. - -Required evidence: - -- **X1.** The op's upstream behavior is known to be replaced by a better-supported alternative documented in this repo, **and** -- **X2.** The rationale names the recommended replacement. - ---- +- `deprecated` — `"deprecated: : "`. +- `specialty` (S2) — `"specialty: "`. -## How to cite a clause in `rationale` +Authored shape on an override entry: -Format: `: : `. Examples: +```json +"curation": { + "status": "specialty", + "status_override": "specialty", + "rationale": "specialty: legacy standalone welder superseded by meshCleanup; reach for it only when the user explicitly needs the upstream-documented behavior.", + "wired_into": ["skills/.../workflow.md"] +} +``` -- `"canonical: C1+C2: invoked by so-run-operations destructive-op table; loss_class bounded-loss."` -- `"specialty: S1: destructive; appears in so-run-operations destructive-op confirmation table."` -- `"analysis: A1+A2: lossless finding-producer; candidate for so-interpret-validators wiring."` -- `"documentary: D1+D2+D3: no JSON references, no pipeline, no workflow recommendation."` +Non-override entries carry just the generated `status` and the authored `wired_into` evidence — no `rationale`. -The schema at `scripts/operation-curation.schema.json` enforces that every entry's `rationale` starts with `:` matching the entry's declared `status`. The coverage audit additionally verifies that `canonical`-status ops have a non-empty `wired_into`, and that each `wired_into` target file actually references the op. +The schema at `scripts/operations.schema.json` describes the `curation` block (the `status` enum, the `status_override` enum, and the `rationale`-only-on-override rule). The coverage audit enforces it: it derives `status` (failing on any mismatch with the materialized value), requires a `rationale` starting with `:` whenever `status_override` is set and forbids `rationale` otherwise, verifies `canonical`-status ops have a non-empty `wired_into`, and verifies each `wired_into` target file actually references the op. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/EXECUTION.md b/skills/omniverse-usd-performance-tuning/references/operations/EXECUTION.md index 5caad2dc..29114aa0 100644 --- a/skills/omniverse-usd-performance-tuning/references/operations/EXECUTION.md +++ b/skills/omniverse-usd-performance-tuning/references/operations/EXECUTION.md @@ -4,30 +4,28 @@ agent_routes: - omniverse-usd-performance-tuning agent_next: - README.md - - ../so-run-operations/README.md + - ../usd-optimize-run-operations/README.md freshness: 2026-05-20 version: "0.1.0" --- - - -# Scene Optimizer Execution Reference +# Usd Optimize Execution Reference -This docs-class page summarizes how agents should invoke Scene Optimizer +This docs-class page summarizes how agents should invoke Usd Optimize operations after the workflow has selected a runtime and an approved operation plan. Detailed executable guidance lives in the nested -`so-run-operations` references; this page gives repo-root agents enough shape to +`usd-optimize-run-operations` references; this page gives repo-root agents enough shape to avoid wrong turns before entering the skill bundle. -Use setup preflight plus live `sceneOptimizer.operationsAvailable` before +Use setup preflight plus live `usdOptimize.operationsAvailable` before execution. Per-operation files are routing stubs; upstream `usd-optimize` docs own parameters and defaults. Local invocation mechanics live in -`../so-run-operations/references/invocation.md`; do not invent or duplicate +`../usd-optimize-run-operations/references/invocation.md`; do not invent or duplicate Python call shapes here. ## Optional Helper Wrapper Shape -Use these wrapper paths only when the selected Scene Optimizer environment or +Use these wrapper paths only when the selected Usd Optimize environment or build checkout provides them. Do not assume a Kit or standalone install ships `tools/perf_operations`. @@ -66,15 +64,15 @@ binding interface from `omni.scene.optimizer.core.bindings._omni_scene_optimizer_core`. Before invoking any planned operation, cross-check the operation key against -`sceneOptimizer.operationsAvailable` in `/setup-preflight.json`. -If a key is missing, report `blocked_missing_so_operation` and do not silently +`usdOptimize.operationsAvailable` in `/setup-preflight.json`. +If a key is missing, report `blocked_missing_usd_optimize_operation` and do not silently substitute another operation. The operation key comes from `references/operations/README.md`. Arguments come from the per-operation page's Parameters table and starting-config JSON. Invalid keys may warn or silently no-op; do not guess argument names. -## Asset Validator Import Variant +## usd-validation-nvidia Import Variant Inside Kit, use: @@ -91,11 +89,11 @@ from omni.asset_validator import ValidationEngine Select the import that matches `/setup-preflight.json`; do not mix Kit extension imports with standalone package runs. -## Agent-Orchestrated Batch Mode +## Scheduler-Backed Batch Mode -Batch mode is an agent orchestration pattern, not a wrapper flag. The helper or -API invocation still accepts one target; the agent runs independent targets in -adaptive batches. +Batch mode is scheduler-backed. The helper or API invocation still accepts one +target; the agent writes a batch plan and runs independent targets through +`usd-optimize-run-operations/scripts/run_batch.py`. Choose concurrency from target weight and available resources rather than a fixed target-count cap. File size, mesh/vertex/material counts, op-chain cost, @@ -114,24 +112,29 @@ non-prototype mesh target before final stage-level cleanup; do not reduce it to For each target, include a stable hash of the absolute input path in optimized USD, summary, and log filenames. After every batch, verify that produced output -count matches target count before declaring success. Record a batch manifest -with targets, chosen concurrency, resource observations, output/log paths, -failures, and any remainder-script decision. +count matches target count before declaring success. Preserve the scheduler +`status.json` artifact with targets, chosen concurrency, resource observations, +output/log paths, failures, timeouts, GPU-fallback decisions, and any resume +decision. ## Save Policy -Scene Optimizer mutates the opened stage in memory. Default to exporting an +Usd Optimize mutates the opened stage in memory. Default to exporting an optimized `.usdc` output under `output_path`. Use in-place `Save()` only for newly created layers or explicitly approved source edits, and use flattened stage export only when the user asks for a flattened deliverable. ## Rules +- **Edit-target invariant:** open each target as its own root layer; never + optimize a referenced library through the composed assembly. Full rule (own-layer + edit target, `Class → Def` de-classing, standalone-resolvable libraries): + [restructure-mode.md § Edit-Target Invariant](../usd-structure-assessment/references/apply-restructure/references/restructure-mode.md#edit-target-invariant-never-optimize-through-a-reference). - Confirm bounded-loss/destructive operations before mutation. - Use selected targets from SA/validation evidence. - Store config, log, output stage, and summary artifacts. - If helper wrappers exist in the selected environment they may be used; otherwise use the Python/API executor from the invocation reference. -- Do not pass a plain `pxr.Usd.Stage` directly to Scene Optimizer operation +- Do not pass a plain `pxr.Usd.Stage` directly to Usd Optimize operation APIs. Attach it to `ExecutionContext` or use the standalone JSON helper as described in the invocation reference. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/README.md b/skills/omniverse-usd-performance-tuning/references/operations/README.md index 87bf4c81..89b2b4fb 100644 --- a/skills/omniverse-usd-performance-tuning/references/operations/README.md +++ b/skills/omniverse-usd-performance-tuning/references/operations/README.md @@ -1,117 +1,115 @@ - - - - + + # Operation Index -Catalog of all Scene Optimizer operations known to this workflow. Each row -corresponds to a local `.md` handoff stub whose YAML frontmatter carries -the same routing fields shown below. Use this to find operations by category, -loss class, or argument count; use upstream `usd-optimize` or the prebuilt -Scene Optimizer package for operation behavior, parameters, defaults, and -implementation gotchas. +Catalog of all Usd Optimize operations known to this workflow. Each row +carries the routing fields (loss class, risk, confirmation, pipelines) from the +catalog. Use this to find operations by category, loss class, or argument count; +use upstream `usd-optimize` or the prebuilt Usd Optimize package for operation +behavior, parameters, defaults, and implementation gotchas. The package resolution rule is centralized once in [`usd-optimize` upstream handoff](../upstreams/usd-optimize.md): derive the upstream operation guide from the operation key as -`.agents/operations/.md`, then resolve it under the selected -Scene Optimizer package root. Do not duplicate package URLs, root fallbacks, or -upstream parameter/default tables in the per-operation stubs. Before executing -any operation, consume `/setup-preflight.json` and confirm the op -appears in `sceneOptimizer.operationsAvailable`. +`docs/operations/.rst` (1.1.x packages), or +`.agents/operations/.md` (1.0.x packages), then resolve it under +the selected Usd Optimize package root. Do not duplicate package URLs, root fallbacks, or +upstream parameter/default tables here. Before executing any operation, consume +`/setup-preflight.json` and confirm the op appears in +`usdOptimize.operationsAvailable`. **Companion docs:** - [Execution reference](EXECUTION.md) — docs-class wrapper/API invocation shape, batch orchestration, and validator import variants. - [Classification rubric](CLASSIFICATION.md) — curation tiers and the canonical-over-specialty selection rule. -- [`pipelines.md`](../so-run-operations/references/pipelines.md) — curated multi-op chains organized by bottleneck. -- [`_template.md`](_template.md) — template for new operation guides (includes the frontmatter schema). -- [`manifest.json`](manifest.json) — machine-readable catalog (same data as below). +- [`pipelines.md`](../usd-optimize-run-operations/references/pipelines.md) — curated multi-op chains organized by bottleneck. +- [`operations.json`](operations.json) — machine-readable catalog (same data as below), including the per-op `curation` block (generated `status` + authored `wired_into`; `rationale` only on overrides). - [`usd-optimize` upstream handoff](../upstreams/usd-optimize.md) — central upstream operation-guide and prebuilt package resolution. **Loss class.** `lossless` reorganizes / dedups / regenerates derived data only. `bounded-loss` removes or modifies authored content (the agent should confirm with the user before running). `analysis-only` is read-only (`context.analysisMode = 1`). - ## Geometry | Operation | Key | Args | Loss | Risk | Confirm | Pipelines | |---|---|---|---|---|---|---| -| [Dice Meshes](diceMeshes.md) | `diceMeshes` | 22 | bounded-loss | medium | yes | — | -| [Fit Primitives](fitPrimitives.md) | `fitPrimitives` | 20 | bounded-loss | high | yes | — | -| [Split Meshes](splitMeshes.md) | `splitMeshes` | 16 | lossless | low | no | — | -| [Primitives to Meshes](primitivesToMeshes.md) | `primitivesToMeshes` | 13 | lossless | low | no | — | -| [Mesh Cleanup](meshCleanup.md) | `meshCleanup` | 11 | bounded-loss | low | yes | `mesh-count-reduction`, `data-quality-baseline` | -| [De-duplicate Geometry](deduplicateGeometry.md) | `deduplicateGeometry` | 9 | lossless | low | no | `safe-cleanup`, `memory-reduction`, `mesh-count-reduction` | -| [Decimate Meshes](decimateMeshes.md) | `decimateMeshes` | 8 | bounded-loss | medium | yes | `mesh-count-reduction` | -| [Shrinkwrap](shrinkwrap.md) | `shrinkwrap` | 7 | bounded-loss | high | yes | — | -| [Generate Normals](generateNormals.md) | `generateNormals` | 6 | lossless | low | no | `data-quality-baseline` | -| [Merge Vertices](mergeVertices.md) | `mergeVertices` | 5 | lossless | low | no | — | -| [Subdivide Meshes](subdivideMeshes.md) | `subdivideMeshes` | 5 | lossless | low | no | — | -| [Remesh Meshes](remeshMeshes.md) | `remeshMeshes` | 4 | bounded-loss | high | yes | — | -| [Remove Small Geometry](removeSmallGeometry.md) | `removeSmallGeometry` | 4 | bounded-loss | medium | yes | `mesh-count-reduction` | -| [Triangulate Meshes](triangulateMeshes.md) | `triangulateMeshes` | 2 | lossless | low | no | — | -| [Manifold Meshes](manifoldMeshes.md) | `manifoldMeshes` | 1 | bounded-loss | medium | yes | — | -| [Sparse Meshes](sparseMeshes.md) | `sparseMeshes` | 0 | bounded-loss | medium | yes | — | +| Dice Meshes | `diceMeshes` | 22 | bounded-loss | medium | yes | — | +| Fit Primitives | `fitPrimitives` | 20 | bounded-loss | high | yes | — | +| Split Meshes | `splitMeshes` | 16 | lossless | low | no | — | +| Primitives to Meshes | `primitivesToMeshes` | 13 | lossless | low | no | — | +| Mesh Cleanup | `meshCleanup` | 11 | lossless | low | yes | `mesh-count-reduction`, `data-quality-baseline` | +| De-duplicate Geometry | `deduplicateGeometry` | 9 | lossless | low | no | `safe-cleanup`, `memory-reduction`, `mesh-count-reduction` | +| Decimate Meshes | `decimateMeshes` | 8 | bounded-loss | medium | yes | `mesh-count-reduction` | +| Shrinkwrap | `shrinkwrap` | 7 | bounded-loss | high | yes | — | +| Generate Normals | `generateNormals` | 6 | lossless | low | no | `data-quality-baseline` | +| Merge Vertices | `mergeVertices` | 5 | lossless | low | no | — | +| Subdivide Meshes | `subdivideMeshes` | 5 | lossless | low | no | — | +| Remesh Meshes | `remeshMeshes` | 4 | bounded-loss | high | yes | — | +| Remove Small Geometry | `removeSmallGeometry` | 4 | bounded-loss | medium | yes | `mesh-count-reduction` | +| Triangulate Meshes | `triangulateMeshes` | 2 | lossless | low | no | — | +| Manifold Meshes | `manifoldMeshes` | 1 | bounded-loss | medium | yes | — | +| Sparse Meshes | `sparseMeshes` | 0 | bounded-loss | medium | yes | — | ## Hierarchy | Operation | Key | Args | Loss | Risk | Confirm | Pipelines | |---|---|---|---|---|---|---| -| [Remove Prims](removePrims.md) | `removePrims` | 8 | bounded-loss | high | yes | — | -| [Prune Leaves](pruneLeaves.md) | `pruneLeaves` | 3 | lossless | low | no | `safe-cleanup`, `memory-reduction`, `load-time-reduction` | -| [Flatten Hierarchy](flattenHierarchy.md) | `flattenHierarchy` | 2 | lossless | medium | no | — | -| [Organize Prototypes](organizePrototypes.md) | `organizePrototypes` | 2 | lossless | low | no | — | -| [Delete Prims](deletePrims.md) | `deletePrims` | 1 | bounded-loss | high | yes | — | -| [De-duplicate Hierarchies](deduplicateHierarchies.md) | `deduplicateHierarchies` | 0 | lossless | medium | yes | `memory-reduction`, `mesh-count-reduction`, `instancing` | -| [Delete Hidden Prims](deleteHiddenPrims.md) | `deleteHiddenPrims` | 0 | bounded-loss | medium | yes | — | -| [Optimize Skeleton Roots](optimizeSkelRoots.md) | `optimizeSkelRoots` | 0 | lossless | low | no | — | -| [Remove Untyped Prims](removeUntypedPrims.md) | `removeUntypedPrims` | 0 | bounded-loss | low | yes | — | +| Remove Prims | `removePrims` | 8 | bounded-loss | high | yes | — | +| De-duplicate Hierarchies | `deduplicateHierarchies` | 4 | lossless | medium | yes | `memory-reduction`, `mesh-count-reduction`, `instancing` | +| Prune Leaves | `pruneLeaves` | 3 | lossless | low | no | `safe-cleanup`, `memory-reduction`, `load-time-reduction` | +| Flatten Hierarchy | `flattenHierarchy` | 2 | lossless | medium | no | — | +| Organize Prototypes | `organizePrototypes` | 2 | lossless | low | no | — | +| Delete Prims | `deletePrims` | 1 | bounded-loss | high | yes | — | +| Delete Hidden Prims | `deleteHiddenPrims` | 0 | bounded-loss | medium | yes | — | +| Optimize Skeleton Roots | `optimizeSkelRoots` | 0 | lossless | low | no | — | +| Remove Untyped Prims | `removeUntypedPrims` | 0 | bounded-loss | low | yes | — | ## Materials | Operation | Key | Args | Loss | Risk | Confirm | Pipelines | |---|---|---|---|---|---|---| -| [Optimize Materials](optimizeMaterials.md) | `optimizeMaterials` | 4 | lossless | low | no | `safe-cleanup`, `memory-reduction`, `load-time-reduction` | +| Optimize Materials | `optimizeMaterials` | 4 | lossless | low | no | `safe-cleanup`, `memory-reduction`, `load-time-reduction` | ## Uv | Operation | Key | Args | Loss | Risk | Confirm | Pipelines | |---|---|---|---|---|---|---| -| [generateAtlasUVs](generateAtlasUVs.md) | `generateAtlasUVs` | 7 | lossless | medium | no | — | -| [Generate Projection UVs](generateProjectionUVs.md) | `generateProjectionUVs` | 7 | lossless | low | no | — | -| [Remove Unused UVs](removeUnusedUVs.md) | `removeUnusedUVs` | 3 | lossless | low | no | — | +| generateAtlasUVs | `generateAtlasUVs` | 7 | lossless | medium | no | — | +| Generate Projection UVs | `generateProjectionUVs` | 7 | lossless | low | no | — | +| Remove Unused UVs | `removeUnusedUVs` | 3 | lossless | low | no | — | ## Metadata | Operation | Key | Args | Loss | Risk | Confirm | Pipelines | |---|---|---|---|---|---|---| -| [Optimize Primvars](optimizePrimvars.md) | `optimizePrimvars` | 6 | lossless | low | no | — | -| [Optimize Time Samples](optimizeTimeSamples.md) | `optimizeTimeSamples` | 6 | lossless | low | no | `safe-cleanup`, `load-time-reduction` | -| [Edit Stage Metrics](editStageMetrics.md) | `editStageMetrics` | 4 | lossless | low | no | — | -| [Remove Attributes](removeAttributes.md) | `removeAttributes` | 3 | bounded-loss | medium | yes | — | -| [Compute Extents](computeExtents.md) | `computeExtents` | 1 | lossless | low | no | `safe-cleanup`, `load-time-reduction`, `data-quality-baseline` | +| Optimize Primvars | `optimizePrimvars` | 6 | lossless | low | no | — | +| Optimize Time Samples | `optimizeTimeSamples` | 6 | lossless | low | no | `safe-cleanup`, `load-time-reduction` | +| Edit Stage Metrics | `editStageMetrics` | 4 | lossless | low | no | — | +| Remove Attributes | `removeAttributes` | 3 | bounded-loss | medium | yes | — | +| Compute Extents | `computeExtents` | 1 | lossless | low | no | `safe-cleanup`, `load-time-reduction`, `data-quality-baseline` | ## Transform | Operation | Key | Args | Loss | Risk | Confirm | Pipelines | |---|---|---|---|---|---|---| -| [Merge Static Meshes](merge.md) | `merge` | 14 | bounded-loss | high | yes | — | -| [Box Clip](boxClip.md) | `boxClip` | 11 | bounded-loss | high | yes | — | -| [Compute Pivot](pivot.md) | `pivot` | 4 | lossless | low | no | — | +| Merge Static Meshes | `merge` | 14 | bounded-loss | high | yes | — | +| Box Clip | `boxClip` | 11 | bounded-loss | high | yes | — | +| Compute Pivot | `pivot` | 4 | lossless | low | no | — | ## Analysis | Operation | Key | Args | Loss | Risk | Confirm | Pipelines | |---|---|---|---|---|---|---| -| [Find Occluded Meshes](findOccludedMeshes.md) | `findOccludedMeshes` | 7 | analysis-only | medium | yes | — | -| [Find Coinciding Geometry](findCoincidingGeometry.md) | `findCoincidingGeometry` | 4 | analysis-only | low | no | — | -| [Find Overlapping Meshes](findOverlappingMeshes.md) | `findOverlappingMeshes` | 4 | analysis-only | low | no | — | -| [Count Vertices](countVertices.md) | `countVertices` | 3 | analysis-only | low | no | — | -| [Find Flat Hierarchies](findFlatHierarchies.md) | `findFlatHierarchies` | 3 | analysis-only | low | no | — | -| [Print Stats](printStats.md) | `printStats` | 3 | analysis-only | low | no | — | -| [RTX Mesh Count](rtxMeshCount.md) | `rtxMeshCount` | 1 | analysis-only | low | no | — | +| Find Occluded Meshes | `findOccludedMeshes` | 7 | analysis-only | medium | yes | — | +| Find Coinciding Geometry | `findCoincidingGeometry` | 4 | analysis-only | low | no | — | +| Find Overlapping Meshes | `findOverlappingMeshes` | 4 | analysis-only | low | no | — | +| Count Vertices | `countVertices` | 3 | analysis-only | low | no | — | +| Find Flat Hierarchies | `findFlatHierarchies` | 3 | analysis-only | low | no | — | +| Print Stats | `printStats` | 3 | analysis-only | low | no | — | +| RTX Mesh Count | `rtxMeshCount` | 1 | analysis-only | low | no | — | ## Utility | Operation | Key | Args | Loss | Risk | Confirm | Pipelines | |---|---|---|---|---|---|---| -| [Generate Scene](generateScene.md) | `generateScene` | 12 | lossless | low | no | — | -| [Utility Function](utilityFunction.md) | `utilityFunction` | 2 | lossless | low | no | — | -| [Python Script](pythonScript.md) | `pythonScript` | 1 | bounded-loss | high | yes | — | +| Generate Scene | `generateScene` | 12 | lossless | low | no | — | +| Utility Function | `utilityFunction` | 2 | lossless | low | no | — | +| Python Script | `pythonScript` | 1 | bounded-loss | high | yes | — | + +> **Security warning — `pythonScript` executes arbitrary Python code** with the privileges of the running process. Never agent-initiated (specialty escape-hatch; see `CLASSIFICATION.md`): require a user-supplied or reviewed script and explicit confirmation before execution (`operation-safety.md`). ## Summary @@ -124,3 +122,13 @@ Total operations: **47** - transform: 3 - analysis: 7 - utility: 3 + +## Catalog currency + +The checked-in probe snapshot (`probe-snapshots/usd-optimize-1.0.4.json`) +reflects usd-optimize 1.0.4, captured live from the GitHub release package. +It is not authoritative at runtime: +the live `operationsAvailable` list from the session's setup-preflight always +wins. When the pinned install version moves, refresh the snapshot (re-run the +setup probe against the new runtime and check in the emitted JSON) so the +catalog's availability examples stay representative. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/_curation.json b/skills/omniverse-usd-performance-tuning/references/operations/_curation.json deleted file mode 100644 index 7055c9a3..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/_curation.json +++ /dev/null @@ -1,312 +0,0 @@ -{ - "meshCleanup": { - "status": "canonical", - "rationale": "canonical: C1+C2: invoked by so-run-operations and the data-quality-baseline / mesh-count-reduction pipelines; loss_class bounded-loss.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/operation-safety.md", - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md", - "skills/omniverse-usd-performance-tuning/references/workflow.md" - ] - }, - "deduplicateGeometry": { - "status": "canonical", - "rationale": "canonical: C1+C2: invoked by so-run-operations and safe-cleanup / memory-reduction pipelines; lossless.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/operation-safety.md", - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md", - "skills/omniverse-usd-performance-tuning/references/workflow.md" - ] - }, - "deduplicateHierarchies": { - "status": "canonical", - "rationale": "canonical: C1+C2: hierarchy-level instancing via restructure-decision Phase 2e deduplicate-internally path. Requires user confirmation (replaces subtrees with instanceable references to shared prototypes).", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/restructure-decision/README.md", - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/operation-safety.md", - "skills/omniverse-usd-performance-tuning/references/workflow.md" - ] - }, - "pruneLeaves": { - "status": "canonical", - "rationale": "canonical: C1+C2: invoked by so-run-operations safe-cleanup pipeline; lossless.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/operation-safety.md", - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md", - "skills/omniverse-usd-performance-tuning/references/workflow.md" - ] - }, - "computeExtents": { - "status": "canonical", - "rationale": "canonical: C1+C2: invoked by so-run-operations safe-cleanup pipeline; lossless.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/operation-safety.md", - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md" - ] - }, - "optimizeMaterials": { - "status": "canonical", - "rationale": "canonical: C1+C2: invoked by so-run-operations safe-cleanup pipeline; lossless at default (convertToColor=false).", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/operation-safety.md", - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md" - ] - }, - "optimizeTimeSamples": { - "status": "canonical", - "rationale": "canonical: C1+C2: invoked by so-run-operations safe-cleanup pipeline; lossless.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/operation-safety.md", - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md" - ] - }, - "removeUnusedUVs": { - "status": "canonical", - "rationale": "canonical: C1+C2: lossless mesh-cleanup op surfaced as a local routing key in pipelines.md for CAD/BIM cleanup (named pipeline recipes live upstream); routing skill points at pipelines.md rather than naming the op directly.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md" - ] - }, - "generateNormals": { - "status": "canonical", - "rationale": "canonical: C1+C2: invoked by data-quality-baseline pipeline; lossless when normals not user-authored.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md", - "skills/omniverse-usd-performance-tuning/references/workflow.md" - ] - }, - "decimateMeshes": { - "status": "specialty", - "rationale": "specialty: S1: destructive (drops vertices); listed in so-run-operations operation-safety table with maxMeanError vs reductionFactor guidance.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/operation-safety.md", - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md", - "skills/omniverse-usd-performance-tuning/references/workflow.md" - ] - }, - "removeSmallGeometry": { - "status": "specialty", - "rationale": "specialty: S1: bounded-loss (removes prims below screen-space threshold); in so-run-operations operation-safety table.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/operation-safety.md", - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md" - ] - }, - "removePrims": { - "status": "specialty", - "rationale": "specialty: S2: stage-mutating; agent must surface impacted prims before invoking. Used as a cleanup tool in so-run-operations.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/operation-safety.md" - ] - }, - "flattenHierarchy": { - "status": "specialty", - "rationale": "specialty: S1: lossless Xform-collapse cleanup reached for via validator findings (SceneOptimizerFlatHierarchiesChecker -> flattenHierarchy) and local workflow routing. Not a composition-arc flattener despite the name; upstream usd-optimize owns operation mechanics.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/rule-reference.md" - ] - }, - "pythonScript": { - "status": "specialty", - "rationale": "specialty: S2: escape-hatch op used by so-create-proxy's USD-authoring recipes; not for general flow. JSON example added to pipelines.md by this PR.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/so-create-proxy/README.md", - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md" - ] - }, - "mergeVertices": { - "status": "specialty", - "rationale": "specialty: S2: hidden legacy standalone welder. Prefer canonical meshCleanup for local recommendations; reach for this op only when the user explicitly needs its upstream-documented behavior.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/workflow.md" - ] - }, - "findCoincidingGeometry": { - "status": "analysis", - "rationale": "analysis: A1+A2: lossless coincidence analyzer; wired into the so-interpret-validators interpretation map (SceneOptimizerCoincidingGeometryChecker -> spatial_coinciding) and the workflow analysis-op guidance. Prefer deduplicateGeometry before destructive deletion.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/rule-reference.md", - "skills/omniverse-usd-performance-tuning/references/workflow.md" - ] - }, - "findOccludedMeshes": { - "status": "canonical", - "rationale": "canonical: C1+C2: wired into Phase 4 op chain as first-priority internal geometry removal; analysis-only detection followed by removePrims action. Scoped to SA containment-flagged pairs with opaque enclosures.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/rule-reference.md", - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/config-from-evidence.md", - "skills/omniverse-usd-performance-tuning/references/workflow.md" - ] - }, - "findFlatHierarchies": { - "status": "analysis", - "rationale": "analysis: A1+A2: lossless hierarchy-shape finder; wired into the so-interpret-validators interpretation map (SceneOptimizerFlatHierarchiesChecker -> flattenHierarchy) and the workflow analysis-op guidance.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/rule-reference.md", - "skills/omniverse-usd-performance-tuning/references/workflow.md" - ] - }, - "fitPrimitives": { - "status": "canonical", - "rationale": "canonical: C1+C2: bounded-loss geometry op surfaced as a local routing key in pipelines.md for CAD/BIM cleanup (named pipeline recipes live upstream); critical for CAD/BIM/MEP scenes. Requires user confirmation (replaces meshes with analytic primitives).", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md", - "skills/omniverse-usd-performance-tuning/references/operations/fitPrimitives.md" - ] - }, - "rtxMeshCount": { - "status": "analysis", - "rationale": "analysis: A1+A2: lossless RTX-bucket counter; mentioned in workflow's analysis-only ops section.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/workflow.md" - ] - }, - "printStats": { - "status": "analysis", - "rationale": "analysis: A1+A2: lossless stats reporter; mentioned in workflow's analysis-only ops section.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/workflow.md" - ] - }, - "countVertices": { - "status": "analysis", - "rationale": "analysis: A1+A2: lossless vertex counter.", - "wired_into": [] - }, - "boxClip": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: no JSON references, no pipeline mention, no workflow recommendation.", - "wired_into": [] - }, - "deleteHiddenPrims": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: never invoked by current flow.", - "wired_into": [] - }, - "deletePrims": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: never invoked by current flow.", - "wired_into": [] - }, - "diceMeshes": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: never invoked by current flow.", - "wired_into": [] - }, - "editStageMetrics": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: stage-metrics editor; outside the optimization flow's scope.", - "wired_into": [] - }, - "generateAtlasUVs": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: UV-atlas authoring; outside scope.", - "wired_into": [] - }, - "generateProjectionUVs": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: projected-UV authoring; outside scope.", - "wired_into": [] - }, - "generateScene": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: scene authoring; outside the optimization flow's scope.", - "wired_into": [] - }, - "manifoldMeshes": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: standalone manifold repair; meshCleanup.makeManifold is the active path.", - "wired_into": [] - }, - "merge": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: static-mesh merge is destructive and has known instancing conflicts; mostly user-initiated for specific GPU-pressure scenarios and not in the canonical CAD/BIM cleanup flow. Upstream usd-optimize owns operation mechanics.", - "wired_into": [] - }, - "optimizePrimvars": { - "status": "specialty", - "rationale": "specialty: S2: validator-finding evidence (SceneOptimizerIndexedPrimvarChecker T1 in rule-reference.md) wires it into the so-interpret-validators chain. Upstream usd-optimize owns enum semantics and operation mechanics.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/rule-reference.md" - ] - }, - "optimizeSkelRoots": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: skel-specific; outside the CAD-centric focus of the current flow.", - "wired_into": [] - }, - "organizePrototypes": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: prototype-organization; superseded by apply-restructure for most use cases.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/workflow.md" - ] - }, - "pivot": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: pivot-point authoring; outside scope.", - "wired_into": [] - }, - "primitivesToMeshes": { - "status": "specialty", - "rationale": "specialty: S3: load-bearing escape hatch. The canonical CAD flow prefers fitPrimitives (analytic primitives), but primitivesToMeshes is the only path to convert primitives back to UsdGeomMesh for downstream tools that don't accept analytic primitives (some renderers, physics, exporters). Recommend only when the downstream context explicitly requires mesh output.", - "wired_into": [] - }, - "remeshMeshes": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: remeshing; bounded-loss but outside default flow.", - "wired_into": [] - }, - "removeAttributes": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: bulk attribute remover; never invoked by current flow.", - "wired_into": [] - }, - "removeUntypedPrims": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: never invoked by current flow.", - "wired_into": [] - }, - "sparseMeshes": { - "status": "specialty", - "rationale": "specialty: S2: validator-finding evidence (SceneOptimizerSparseMeshChecker T2 in rule-reference.md) wires it into the so-interpret-validators chain. Analysis-only op that classifies meshes by spatial density and surfaces split / dice candidates; surfaces from usd-validation-runner Tier 3 policy (outlier_extent-flagged assets). Outside the default canonical flow but actionable when the checker fires.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/rule-reference.md", - "skills/omniverse-usd-performance-tuning/references/workflow.md" - ] - }, - "splitMeshes": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: splitting; outside default flow.", - "wired_into": [] - }, - "subdivideMeshes": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: subdivision; outside default flow.", - "wired_into": [] - }, - "triangulateMeshes": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: triangulation; outside default flow.", - "wired_into": [] - }, - "utilityFunction": { - "status": "specialty", - "rationale": "specialty: S3: provides four useful structural sub-functions not covered by any other op (Deinstance, Unbind Materials, Set Instanceable, Flatten Instances). Used for instancing-state toggles and material-binding cleanup that don't fit the standard mesh-cleanup or geometry-reduction flow. Recommend when the user asks about instancing toggle or material rebinding.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/workflow.md" - ] - }, - "findOverlappingMeshes": { - "status": "analysis", - "rationale": "analysis: A1+A2: lossless overlap analyzer; wired into the so-interpret-validators interpretation map (SceneOptimizerFindOverlappingMeshesChecker -> spatial_overlapping) and the workflow analysis-op guidance.", - "wired_into": [ - "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/rule-reference.md", - "skills/omniverse-usd-performance-tuning/references/workflow.md" - ] - }, - "shrinkwrap": { - "status": "documentary", - "rationale": "documentary: D1+D2+D3: specialty geometry op; use only after live operationsAvailable confirms support.", - "wired_into": [] - } -} diff --git a/skills/omniverse-usd-performance-tuning/references/operations/_template.md b/skills/omniverse-usd-performance-tuning/references/operations/_template.md deleted file mode 100644 index 97e122f2..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/_template.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: -title: -source: scene-optimizer-core/source/operations//.cpp -category: geometry -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 0 -requires_mesh: true -pipelines: [] -keywords: [] -since_version: 2026-01-01T00:00:00Z -requires_extension: omni.scene.optimizer.core -# parameter_prerequisites: (add for bounded-loss/destructive ops) -# - field: asset_physical_context. -# source: sa_report.json -# required: true -# - elicit_from_user: -# canonical_question: "" -# defaults: [, ] -# default_option: "" -# skip_option: "skip " -# conversion: "" ---- - - - -# - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/boxClip.md b/skills/omniverse-usd-performance-tuning/references/operations/boxClip.md deleted file mode 100644 index 0170b487..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/boxClip.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: boxClip -title: Box Clip -source: scene-optimizer-core/source/operations/boxClip/BoxClip.cpp -category: transform -loss_class: bounded-loss -requires_confirmation: true -risk_class: high -args_count: 11 -requires_mesh: false -pipelines: [] -keywords: [clip, bounding-box, aabb, trim, crop] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Box Clip - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/computeExtents.md b/skills/omniverse-usd-performance-tuning/references/operations/computeExtents.md deleted file mode 100644 index eea46f57..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/computeExtents.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: computeExtents -title: Compute Extents -source: scene-optimizer-core/source/operations/computeExtents/ComputeExtentsPlugin.cpp -category: metadata -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 1 -requires_mesh: true -pipelines: [safe-cleanup, load-time-reduction, data-quality-baseline] -keywords: [extent, bounding-box, metadata, culling] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Compute Extents - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/countVertices.md b/skills/omniverse-usd-performance-tuning/references/operations/countVertices.md deleted file mode 100644 index 6b297257..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/countVertices.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: countVertices -title: Count Vertices -source: scene-optimizer-core/source/operations/countVertices/CountVertices.cpp -category: analysis -loss_class: analysis-only -requires_confirmation: false -risk_class: low -args_count: 3 -requires_mesh: true -pipelines: [] -keywords: [count, vertices, stats, analysis] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Count Vertices - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/decimateMeshes.md b/skills/omniverse-usd-performance-tuning/references/operations/decimateMeshes.md deleted file mode 100644 index 3799078c..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/decimateMeshes.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: decimateMeshes -title: Decimate Meshes -source: scene-optimizer-core/source/operations/decimateMeshes/OmniMeshDecimate.cpp -category: geometry -loss_class: bounded-loss -requires_confirmation: true -risk_class: medium -args_count: 8 -requires_mesh: true -pipelines: [mesh-count-reduction] -keywords: [decimate, polygon-count, lod, qem, silhouette] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core -parameter_prerequisites: - - field: asset_physical_context.metersPerUnit - source: sa_report.json - required: true - - elicit_from_user: mm_tolerance - canonical_question: "What's the smallest surface detail (in mm) you need to preserve?" - defaults: [0.1, 0.5, 1.0, 2.0, 5.0] - skip_option: "skip decimation" - conversion: "maxMeanError = mm_tolerance / (metersPerUnit * 1000)" -recommendation_signals: - - source: SceneOptimizerMeshDensityChecker - signal: "High-density outlier meshes detected — meshes with triangle density disproportionate to their physical extent are strong candidates for decimation." - - source: sa_report.flagged_assets (when extentsHint authored) - reason: outlier_extent - signal: "SA flagged meshes with authored extents disproportionate to their hierarchy level — possible over-tessellation candidates." - - note: > - maxMeanError is inherently scale-aware: over-tessellated meshes (e.g. a - 1M-poly screw at 20mm) lose most triangles because nearly all vertices - fall within the error budget. Under-tessellated meshes barely change. - No per-mesh targeting is needed — apply uniformly to all meshes. -anti_patterns: - - "Do not frame as 'reduce by X%'. Rate-mode bypasses the silhouette-preserving error budget." - - "Do not ask which meshes to target. maxMeanError handles density differences automatically." - - "Do not offer triangle-count or percentage options unless the user explicitly provides a rate-based constraint." ---- - - - -# Decimate Meshes - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/deduplicateGeometry.md b/skills/omniverse-usd-performance-tuning/references/operations/deduplicateGeometry.md deleted file mode 100644 index 2f82b47d..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/deduplicateGeometry.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: deduplicateGeometry -title: De-duplicate Geometry -source: scene-optimizer-core/source/operations/deduplicateGeometry/DeduplicateGeometry.cpp -category: geometry -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 9 -requires_mesh: true -pipelines: [safe-cleanup, memory-reduction, mesh-count-reduction] -keywords: [dedup, instancing, memory, mesh] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# De-duplicate Geometry - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/deduplicateHierarchies.md b/skills/omniverse-usd-performance-tuning/references/operations/deduplicateHierarchies.md deleted file mode 100644 index e892ec27..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/deduplicateHierarchies.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: deduplicateHierarchies -title: De-duplicate Hierarchies -source: scene-optimizer-core/source/operations/deduplicateHierarchies/DeduplicateHierarchies.cpp -category: hierarchy -loss_class: lossless -requires_confirmation: true -risk_class: medium -args_count: 0 -requires_mesh: false -pipelines: [memory-reduction, mesh-count-reduction, instancing] -keywords: [dedup, instancing, hierarchy, prototype, reference] -since_version: 2026-04-17T00:00:00Z -requires_extension: omni.scene.optimizer.core ---- - - - -# De-duplicate Hierarchies - -Identifies structurally-identical sub-hierarchies within a stage and collapses -them into shared prototypes referenced from each original site. The referencing -prims are marked `instanceable=true`. - -Unlike `deduplicateGeometry` (which operates on individual mesh data), -`deduplicateHierarchies` operates at the subtree level — entire prim -hierarchies are compared and deduplicated. - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/deleteHiddenPrims.md b/skills/omniverse-usd-performance-tuning/references/operations/deleteHiddenPrims.md deleted file mode 100644 index 93200570..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/deleteHiddenPrims.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: deleteHiddenPrims -title: Delete Hidden Prims -source: scene-optimizer-core/source/operations/deleteHiddenPrims/__init__.py -category: hierarchy -loss_class: bounded-loss -requires_confirmation: true -risk_class: medium -args_count: 0 -requires_mesh: false -pipelines: [] -keywords: [delete, hidden, visibility, prune] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Delete Hidden Prims - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/deletePrims.md b/skills/omniverse-usd-performance-tuning/references/operations/deletePrims.md deleted file mode 100644 index 79b89a76..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/deletePrims.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: deletePrims -title: Delete Prims -source: scene-optimizer-core/source/operations/deletePrims/DeletePrimsPlugin.cpp -category: hierarchy -loss_class: bounded-loss -requires_confirmation: true -risk_class: high -args_count: 1 -requires_mesh: false -pipelines: [] -keywords: [delete, prim, prune] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Delete Prims - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/diceMeshes.md b/skills/omniverse-usd-performance-tuning/references/operations/diceMeshes.md deleted file mode 100644 index c78239b4..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/diceMeshes.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: diceMeshes -title: Dice Meshes -source: scene-optimizer-core/source/operations/diceMeshes/DiceMeshes.cpp -category: geometry -loss_class: bounded-loss -requires_confirmation: true -risk_class: medium -args_count: 22 -requires_mesh: true -pipelines: [] -keywords: [dice, subdivide, chunk, tile, streaming] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Dice Meshes - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/editStageMetrics.md b/skills/omniverse-usd-performance-tuning/references/operations/editStageMetrics.md deleted file mode 100644 index f29a0232..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/editStageMetrics.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: editStageMetrics -title: Edit Stage Metrics -source: scene-optimizer-core/source/operations/editStageMetrics/EditStageMetrics.cpp -category: metadata -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 4 -requires_mesh: false -pipelines: [] -keywords: [stage, metrics, metersPerUnit, upAxis, metadata] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Edit Stage Metrics - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/findCoincidingGeometry.md b/skills/omniverse-usd-performance-tuning/references/operations/findCoincidingGeometry.md deleted file mode 100644 index 534b348b..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/findCoincidingGeometry.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: findCoincidingGeometry -title: Find Coinciding Geometry -source: scene-optimizer-core/source/operations/findCoincidingGeometry/FindCoincidingGeometry.cpp -category: analysis -loss_class: analysis-only -requires_confirmation: false -risk_class: low -args_count: 4 -requires_mesh: true -pipelines: [] -keywords: [find, coinciding, overlap, analysis] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Find Coinciding Geometry - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/findFlatHierarchies.md b/skills/omniverse-usd-performance-tuning/references/operations/findFlatHierarchies.md deleted file mode 100644 index 4351ee18..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/findFlatHierarchies.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: findFlatHierarchies -title: Find Flat Hierarchies -source: scene-optimizer-core/source/operations/findFlatHierarchies/FindFlatHierarchiesOperation.cpp -category: analysis -loss_class: analysis-only -requires_confirmation: false -risk_class: low -args_count: 3 -requires_mesh: false -pipelines: [] -keywords: [find, hierarchy, flat, analysis] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Find Flat Hierarchies - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/findOccludedMeshes.md b/skills/omniverse-usd-performance-tuning/references/operations/findOccludedMeshes.md deleted file mode 100644 index 3ba3c667..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/findOccludedMeshes.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: findOccludedMeshes -title: Find Occluded Meshes -source: scene-optimizer-core/source/operations/findOccludedMeshes/FindOccludedMeshes.cpp -category: analysis -loss_class: analysis-only -requires_confirmation: true -risk_class: medium -args_count: 7 -requires_mesh: true -pipelines: [] -keywords: [find, occluded, interior, hidden, analysis, internal, enclosed] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core -parameter_prerequisites: - ordering: - position: first - rationale: > - Remove internal geometry before spending compute on meshCleanup, - deduplicateGeometry, decimation, or any other op. Dead weight is - removed first. - invariants: - - "findOccludedMeshes + removePrims BEFORE meshCleanup" - - "findOccludedMeshes + removePrims BEFORE deduplicateGeometry" - - "findOccludedMeshes + removePrims BEFORE decimateMeshes" - - "findOccludedMeshes + removePrims BEFORE removeSmallGeometry" - scoping: - trigger: SA flagged_assets with reason=containment AND enclosure_opaque=true - exclude: > - Pairs where the enclosing geometry has a transparent/translucent - material (opacity < 1.0, transmission shader, glass MDL, alpha-blend - mode). Objects visible through transparent enclosures must NOT be - removed. - asset_types: > - Equipment, machines, vehicles, cabinets, housings, enclosures, pumps, - motors, compressors, sealed assemblies — anything with an opaque - shell/casing that could hide internal parts. - fields: - - field: containment_pairs - source: SA flagged_assets where reason=containment AND enclosure_opaque=true - required: true - description: > - List of (inner_asset, enclosing_asset) pairs from SA §2.2 where the - enclosure is confirmed opaque. Without this, findOccludedMeshes has - no scope and must not run on the full stage. - elicit_from_user: - - id: confirm_analysis - canonical_question: > - These enclosed assets contain internal geometry that may be invisible - from outside. Run occlusion analysis? (Tier 3 cost: minutes per pair) - context: Present the containment pair list from SA with asset names. - skip_option: "Skip occlusion removal" - action_chain: - analysis_op: findOccludedMeshes - action_op: removePrims - pattern: > - Run findOccludedMeshes in analysis mode on the scoped pairs. It - produces a list of fully-occluded prim paths. Feed those paths to - removePrims (requires separate user confirmation for the deletion - step). - two_stage_approval: - stage_1: "Approve running the analysis (T3 cost gate)" - stage_2: "Approve removing the discovered occluded meshes (destructive gate)" ---- - - - -# Find Occluded Meshes - -Detects geometry that is completely hidden inside other geometry and therefore -never visible from outside. Used as the first step of internal geometry removal -— the highest-priority optimization in the Phase 4 op chain. - -## Integration Pattern - -This is a **two-step detect→act** operation: - -1. **Detect:** `findOccludedMeshes` (analysis-only) reports fully-occluded prim paths. -2. **Act:** `removePrims` (destructive) deletes those paths after user confirmation. - -The two steps are consecutive — no other ops run between them. The prim paths -from step 1 feed directly into step 2. - -## Scoping: Opaque Enclosures Only - -Run only on SA-flagged `containment` pairs where `enclosure_opaque: true`. - -**Excluded from analysis:** -- Transparent enclosures (glass, acrylic, mesh screens) -- Enclosures with opacity < 1.0 on their bound material -- Assets with transmission/glass shaders (MDL glass, UsdPreviewSurface with opacity) -- Runtime-toggled visibility (animation channels on visibility attribute) - -If the enclosing geometry is see-through, the internal parts ARE visible and -must not be candidates for removal. - -## Ordering - -**First in the Phase 4 op chain.** Remove dead weight before spending compute on: -- meshCleanup (why repair topology on meshes you'll delete?) -- deduplicateGeometry (why instance internal junk across enclosures?) -- decimateMeshes (why reduce vertices on invisible geometry?) -- removeSmallGeometry (occlusion removal handles these in context) - -## Upstream Mechanics - -This file's YAML frontmatter is the local routing stub source for operation -selection, risk, confirmation, ordering, and workflow metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/findOverlappingMeshes.md b/skills/omniverse-usd-performance-tuning/references/operations/findOverlappingMeshes.md deleted file mode 100644 index 29aac264..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/findOverlappingMeshes.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: findOverlappingMeshes -title: Find Overlapping Meshes -source: scene-optimizer-core/source/operations/findOverlappingMeshes/FindOverlappingMeshesOperation.cpp -category: analysis -loss_class: analysis-only -requires_confirmation: false -risk_class: low -args_count: 4 -requires_mesh: true -pipelines: [] -keywords: [find, overlap, intersect, analysis] -since_version: 2026-05-08T22:40:32Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Find Overlapping Meshes - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/fitPrimitives.md b/skills/omniverse-usd-performance-tuning/references/operations/fitPrimitives.md deleted file mode 100644 index 442fdae3..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/fitPrimitives.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: fitPrimitives -title: Fit Primitives -source: scene-optimizer-core/source/operations/fitPrimitives/Primitive.cpp -category: geometry -loss_class: bounded-loss -requires_confirmation: true -risk_class: high -args_count: 20 -requires_mesh: true -pipelines: [] -keywords: [fit, primitive, cube, sphere, cylinder, approximate] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Fit Primitives - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/flattenHierarchy.md b/skills/omniverse-usd-performance-tuning/references/operations/flattenHierarchy.md deleted file mode 100644 index 68c33ac2..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/flattenHierarchy.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: flattenHierarchy -title: Flatten Hierarchy -source: scene-optimizer-core/source/operations/flattenHierarchy/FlattenHierarchy.cpp -category: hierarchy -loss_class: lossless -requires_confirmation: false -risk_class: medium -args_count: 2 -requires_mesh: false -pipelines: [] -keywords: [flatten, hierarchy, scenegraph] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Flatten Hierarchy - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/generateAtlasUVs.md b/skills/omniverse-usd-performance-tuning/references/operations/generateAtlasUVs.md deleted file mode 100644 index 2bb18001..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/generateAtlasUVs.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: generateAtlasUVs -title: generateAtlasUVs -source: scene-optimizer-core/source/operations/generateAtlasUVs/GenerateAtlasUVs.cpp -category: uv -loss_class: lossless -requires_confirmation: false -risk_class: medium -args_count: 7 -requires_mesh: true -pipelines: [] -keywords: [uv, atlas, unwrap, texture] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# generateAtlasUVs - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/generateNormals.md b/skills/omniverse-usd-performance-tuning/references/operations/generateNormals.md deleted file mode 100644 index cc7851c4..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/generateNormals.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: generateNormals -title: Generate Normals -source: scene-optimizer-core/source/operations/generateNormals/GenerateNormals.cpp -category: geometry -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 6 -requires_mesh: true -pipelines: [data-quality-baseline] -keywords: [normals, shading, smooth, regenerate] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Generate Normals - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/generateProjectionUVs.md b/skills/omniverse-usd-performance-tuning/references/operations/generateProjectionUVs.md deleted file mode 100644 index 8e47f0d7..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/generateProjectionUVs.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: generateProjectionUVs -title: Generate Projection UVs -source: scene-optimizer-core/source/operations/generateProjectionUVs/GenerateProjectionUVs.cpp -category: uv -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 7 -requires_mesh: true -pipelines: [] -keywords: [uv, projection, planar, texture] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Generate Projection UVs - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/generateScene.md b/skills/omniverse-usd-performance-tuning/references/operations/generateScene.md deleted file mode 100644 index 91f59578..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/generateScene.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: generateScene -title: Generate Scene -source: scene-optimizer-core/source/operations/generateScene/GenerateScene.cpp -category: utility -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 12 -requires_mesh: false -pipelines: [] -keywords: [generate, scene, synthetic, test, demo] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Generate Scene - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/manifoldMeshes.md b/skills/omniverse-usd-performance-tuning/references/operations/manifoldMeshes.md deleted file mode 100644 index daf0abce..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/manifoldMeshes.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: manifoldMeshes -title: Manifold Meshes -source: scene-optimizer-core/source/operations/manifoldMeshes/Manifold.cpp -category: geometry -loss_class: bounded-loss -requires_confirmation: true -risk_class: medium -args_count: 1 -requires_mesh: true -pipelines: [] -keywords: [manifold, watertight, close-holes, topology] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Manifold Meshes - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/merge.md b/skills/omniverse-usd-performance-tuning/references/operations/merge.md deleted file mode 100644 index 1a64458f..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/merge.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: merge -title: Merge Static Meshes -source: scene-optimizer-core/source/operations/merge/Merge.cpp -category: transform -loss_class: bounded-loss -requires_confirmation: true -risk_class: high -args_count: 14 -requires_mesh: true -pipelines: [] -keywords: [merge, combine, consolidate, instancing-conflict] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Merge Static Meshes - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/mergeVertices.md b/skills/omniverse-usd-performance-tuning/references/operations/mergeVertices.md deleted file mode 100644 index c9f85466..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/mergeVertices.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: mergeVertices -title: Merge Vertices -source: scene-optimizer-core/source/operations/mergeVertices/MergeVertices.cpp -category: geometry -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 5 -requires_mesh: true -pipelines: [] -keywords: [weld, merge, vertices, tolerance] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Merge Vertices - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/meshCleanup.md b/skills/omniverse-usd-performance-tuning/references/operations/meshCleanup.md deleted file mode 100644 index 4a11c195..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/meshCleanup.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: meshCleanup -title: Mesh Cleanup -source: scene-optimizer-core/source/operations/meshCleanup/MeshCleanup.cpp -category: geometry -loss_class: bounded-loss -requires_confirmation: true -risk_class: low -args_count: 11 -requires_mesh: true -pipelines: [mesh-count-reduction, data-quality-baseline] -keywords: [cleanup, degenerate, isolated, topology, fix] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Mesh Cleanup - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/manifest.json b/skills/omniverse-usd-performance-tuning/references/operations/operations.json similarity index 54% rename from skills/omniverse-usd-performance-tuning/references/operations/manifest.json rename to skills/omniverse-usd-performance-tuning/references/operations/operations.json index 996cef51..492ee672 100644 --- a/skills/omniverse-usd-performance-tuning/references/operations/manifest.json +++ b/skills/omniverse-usd-performance-tuning/references/operations/operations.json @@ -1,15 +1,16 @@ { "$comment": "SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.\nSPDX-License-Identifier: Apache-2.0", "schema": "scene_optimizer_operation_catalog", - "source": "operation catalog; routing fields are mirrored in references/operations/.md frontmatter", + "source": "Usd Optimize operation catalog; single source of truth for op existence, routing metadata (manifest fields), and this-repo curation (status/rationale/wired_into). Replaces the former manifest.json + _curation.json + per-op .md split.", "operations": [ { "key": "boxClip", "title": "Box Clip", "category": "transform", "loss_class": "bounded-loss", - "requires_confirmation": true, "risk_class": "high", + "requires_confirmation": true, + "apply_authority": "intent-gated", "args_count": 11, "requires_mesh": false, "pipelines": [], @@ -21,18 +22,22 @@ "crop" ], "source": "scene-optimizer-core/source/operations/boxClip/BoxClip.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/boxClip.md", "summary": "Box Clip removes or retains geometry based on an axis-aligned bounding box (AABB) region.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "computeExtents", "title": "Compute Extents", "category": "metadata", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 1, "requires_mesh": true, "pipelines": [ @@ -47,18 +52,25 @@ "culling" ], "source": "scene-optimizer-core/source/operations/computeExtents/ComputeExtentsPlugin.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/computeExtents.md", "summary": "Compute Extents calculates and authors the `extent` attribute for meshes.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/operation-safety.md", + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md" + ] + } }, { "key": "countVertices", "title": "Count Vertices", "category": "analysis", "loss_class": "analysis-only", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 3, "requires_mesh": true, "pipelines": [], @@ -69,18 +81,22 @@ "analysis" ], "source": "scene-optimizer-core/source/operations/countVertices/CountVertices.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/countVertices.md", "summary": "Count Vertices is a hidden analysis utility that categorizes meshes by vertex count into high, very high, and extreme buckets.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "analysis", + "wired_into": [] + } }, { "key": "decimateMeshes", "title": "Decimate Meshes", "category": "geometry", "loss_class": "bounded-loss", - "requires_confirmation": true, "risk_class": "medium", + "requires_confirmation": true, + "apply_authority": "auto-within-tolerance", "args_count": 8, "requires_mesh": true, "pipelines": [ @@ -94,18 +110,60 @@ "silhouette" ], "source": "scene-optimizer-core/source/operations/decimateMeshes/OmniMeshDecimate.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/decimateMeshes.md", "summary": "Decimate Meshes reduces polygon count while preserving mesh shape as much as possible.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/operation-safety.md", + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md", + "skills/omniverse-usd-performance-tuning/references/workflow.md" + ] + }, + "parameter_prerequisites": [ + { + "field": "asset_physical_context.metersPerUnit", + "source": "sa_report.json", + "required": true + }, + { + "elicit_from_user": "mm_tolerance", + "canonical_question": "What's the smallest surface detail (in mm) you need to preserve?", + "defaults": [ + 0.1, + 0.5, + 1.0, + 2.0, + 5.0 + ], + "skip_option": "skip decimation", + "conversion": "maxMeanError = mm_tolerance / (metersPerUnit * 1000)" + } + ], + "recommendation_signals": [ + { + "source": "SceneOptimizerMeshDensityChecker", + "signal": "High-density outlier meshes detected — meshes with triangle density disproportionate to their physical extent are strong candidates for decimation. This Phase-2c validator reads actual geometry and is the canonical over-tessellation signal (SA does not flag density; it reads no geometry arrays)." + }, + { + "note": "maxMeanError is inherently scale-aware: over-tessellated meshes (e.g. a 1M-poly screw at 20mm) lose most triangles because nearly all vertices fall within the error budget. Under-tessellated meshes barely change. No per-mesh targeting is needed — apply uniformly to all meshes." + } + ], + "anti_patterns": [ + "Do not frame as 'reduce by X%'. Rate-mode bypasses the silhouette-preserving error budget.", + "Do not ask which meshes to target. maxMeanError handles density differences automatically.", + "Do not offer triangle-count or percentage options unless the user explicitly provides a rate-based constraint." + ] }, { "key": "deduplicateGeometry", "title": "De-duplicate Geometry", "category": "geometry", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 9, "requires_mesh": true, "pipelines": [ @@ -120,19 +178,27 @@ "mesh" ], "source": "scene-optimizer-core/source/operations/deduplicateGeometry/DeduplicateGeometry.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/deduplicateGeometry.md", "summary": "De-duplicate Geometry finds meshes that are geometrically identical (or near-identical) and replaces duplicates with instances of a single prototype.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/operation-safety.md", + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md", + "skills/omniverse-usd-performance-tuning/references/workflow.md" + ] + } }, { "key": "deduplicateHierarchies", "title": "De-duplicate Hierarchies", "category": "hierarchy", "loss_class": "lossless", - "requires_confirmation": true, "risk_class": "medium", - "args_count": 0, + "requires_confirmation": true, + "apply_authority": "intent-gated", + "args_count": 4, "requires_mesh": false, "pipelines": [ "memory-reduction", @@ -147,18 +213,27 @@ "reference" ], "source": "scene-optimizer-core/source/operations/deduplicateHierarchies/DeduplicateHierarchies.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/deduplicateHierarchies.md", "summary": "De-duplicate Hierarchies identifies structurally-identical sub-hierarchies and collapses them into shared prototypes with instanceable references at each original site.", "since_version": "2026-04-17T00:00:00Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/restructure-decision/README.md", + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/operation-safety.md", + "skills/omniverse-usd-performance-tuning/references/workflow.md" + ] + }, + "notes": "Collapses structurally-identical sub-hierarchies into shared prototypes referenced from each original site (referencing prims marked instanceable=true). Contrast deduplicateGeometry, which operates on individual mesh data. paths starts the breadth-first walk at the CHILDREN of each listed frontier prim (empty = children of the default prim). maxDepth caps the TOTAL breadth-first levels descended, counting those children as level 1; 0 = unbounded — a global cap on the whole walk, not a per-prototype recursion budget. The remaining two args tune duplicate matching, not grain: tolerance (default 0.001 stage units; 0 = bitwise-exact) is the float slack for property-value comparison, and ignoreShaderOutputs (default true) skips shader output attributes in that comparison. Grain follows depth: a low maxDepth shares at coarse named components; unbounded lets the value-hash reach the finest leaf library, which over-shares below the named unit and dissolves part identity, so unbounded is not a default endpoint. Invoke it per frontier region — one call per region, paths scoped to that region, maxDepth chosen for that region's structure. A single stage-wide maxDepth applied to every branch is forbidden: named units sit at varying depths, so no one cut lands on them (issue #175, an 85,871-mesh automotive battery-assembly stage: maxDepth 3 → 1 prototype, 4 → 38, 5 → 3,061, while the real named-unit frontier of ~48 falls between depth 4 and depth 5). Measured depth→grain and placement (issue #168, gb300_tray.proto.usdc, 7,711 meshes): maxDepth 1 → 1 prototype / 1 instance / 7,700 authored meshes; 2 → 11 / 47 / 6,510; 0 (unbounded) → 623 / 3,072 / 6,220; rendered mesh count preserved 7,711 at every depth; world-translation drift 0.0 at every depth. Placement-correct by construction: root xformOp:* excluded from identity, the duplicate's local transform preserved (no hand-rolled transform-correct placement needed). Role: the op is the per-region authoring primitive for instanceable-reference collapse. Inside the Phase 2f/2g descent pipeline the phase contract binds (restructure-role manifest, frontier/identity gating, kept_inline_for_merge tagging, recorded convergence), so the deduplicate-internally branch routes through apply-restructure, whose per-level driver drives this op per descent region and emits that manifest. Passing paths + maxDepth directly with no manifest is canonical only for standalone, already-approved dedup runs outside the Phase 0-7 pipeline (usd-optimize-run-operations). deduplicateGeometry remains the last-mile per-mesh leaf cleanup after hierarchy dedup." }, { "key": "deleteHiddenPrims", "title": "Delete Hidden Prims", "category": "hierarchy", "loss_class": "bounded-loss", - "requires_confirmation": true, "risk_class": "medium", + "requires_confirmation": true, + "apply_authority": "intent-gated", "args_count": 0, "requires_mesh": false, "pipelines": [], @@ -169,18 +244,22 @@ "prune" ], "source": "scene-optimizer-core/source/operations/deleteHiddenPrims/__init__.py", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/deleteHiddenPrims.md", "summary": "Delete Hidden Prims finds and deletes all prims that have their visibility set to `invisible`.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "deletePrims", "title": "Delete Prims", "category": "hierarchy", "loss_class": "bounded-loss", - "requires_confirmation": true, "risk_class": "high", + "requires_confirmation": true, + "apply_authority": "intent-gated", "args_count": 1, "requires_mesh": false, "pipelines": [], @@ -190,18 +269,22 @@ "prune" ], "source": "scene-optimizer-core/source/operations/deletePrims/DeletePrimsPlugin.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/deletePrims.md", "summary": "Delete Prims is a hidden utility operation that permanently removes specified prims from the stage's edit target layer.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "diceMeshes", "title": "Dice Meshes", "category": "geometry", "loss_class": "bounded-loss", - "requires_confirmation": true, "risk_class": "medium", + "requires_confirmation": true, + "apply_authority": "intent-gated", "args_count": 22, "requires_mesh": true, "pipelines": [], @@ -213,18 +296,22 @@ "streaming" ], "source": "scene-optimizer-core/source/operations/diceMeshes/DiceMeshes.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/diceMeshes.md", - "summary": "Dice Meshes cuts meshes into smaller pieces along a 3D grid \u2014 like slicing a block of cheese with a wire grid.", + "summary": "Dice Meshes cuts meshes into smaller pieces along a 3D grid — like slicing a block of cheese with a wire grid.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "editStageMetrics", "title": "Edit Stage Metrics", "category": "metadata", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 4, "requires_mesh": false, "pipelines": [], @@ -236,18 +323,22 @@ "metadata" ], "source": "scene-optimizer-core/source/operations/editStageMetrics/EditStageMetrics.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/editStageMetrics.md", - "summary": "Edit Stage Metrics modifies a stage's global metrics \u2014 up axis and linear units.", + "summary": "Edit Stage Metrics modifies a stage's global metrics — up axis and linear units.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "findCoincidingGeometry", "title": "Find Coinciding Geometry", "category": "analysis", "loss_class": "analysis-only", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 4, "requires_mesh": true, "pipelines": [], @@ -258,18 +349,25 @@ "analysis" ], "source": "scene-optimizer-core/source/operations/findCoincidingGeometry/FindCoincidingGeometry.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/findCoincidingGeometry.md", - "summary": "Find Coinciding Geometry detects meshes that occupy the same space \u2014 overlapping or near-identical geometry that causes z-fighting and wasted rendering.", + "summary": "Find Coinciding Geometry detects meshes that occupy the same space — overlapping or near-identical geometry that causes z-fighting and wasted rendering.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "analysis", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-interpret-validators/references/rule-reference.md", + "skills/omniverse-usd-performance-tuning/references/workflow.md" + ] + } }, { "key": "findFlatHierarchies", "title": "Find Flat Hierarchies", "category": "analysis", "loss_class": "analysis-only", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 3, "requires_mesh": false, "pipelines": [], @@ -280,18 +378,25 @@ "analysis" ], "source": "scene-optimizer-core/source/operations/findFlatHierarchies/FindFlatHierarchiesOperation.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/findFlatHierarchies.md", - "summary": "Find Flat Hierarchies identifies prims with an excessively large number of children \u2014 \"flat\" hierarchy patterns where a single prim has hundreds or thousands of direct children.", + "summary": "Find Flat Hierarchies identifies prims with an excessively large number of children — \"flat\" hierarchy patterns where a single prim has hundreds or thousands of direct children.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "analysis", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-interpret-validators/references/rule-reference.md", + "skills/omniverse-usd-performance-tuning/references/workflow.md" + ] + } }, { - "key": "findOccludedMeshes", + "key": "findOccludedMeshes", "title": "Find Occluded Meshes", "category": "analysis", "loss_class": "analysis-only", - "requires_confirmation": true, "risk_class": "medium", + "requires_confirmation": true, + "apply_authority": "intent-gated", "args_count": 7, "requires_mesh": true, "pipelines": [], @@ -305,18 +410,68 @@ "enclosed" ], "source": "scene-optimizer-core/source/operations/findOccludedMeshes/FindOccludedMeshes.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/findOccludedMeshes.md", "summary": "Find Occluded Meshes detects geometry that is completely hidden inside other geometry and therefore never visible.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "analysis", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-interpret-validators/references/rule-reference.md", + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/config-from-evidence.md", + "skills/omniverse-usd-performance-tuning/references/workflow.md" + ] + }, + "parameter_prerequisites": { + "ordering": { + "position": "first", + "rationale": "Remove internal geometry before spending compute on meshCleanup, deduplicateGeometry, decimation, or any other op. Dead weight is removed first.", + "invariants": [ + "findOccludedMeshes + removePrims BEFORE meshCleanup", + "findOccludedMeshes + removePrims BEFORE deduplicateGeometry", + "findOccludedMeshes + removePrims BEFORE decimateMeshes", + "findOccludedMeshes + removePrims BEFORE removeSmallGeometry" + ] + }, + "scoping": { + "trigger": "SA validation_scope.cross_component_pairs not explicitly transparent (enclosure_opaque true or unset)", + "exclude": "Pairs where the enclosing geometry has a transparent/translucent material (opacity < 1.0, transmission shader, glass MDL, alpha-blend mode). Objects visible through transparent enclosures must NOT be removed.", + "asset_types": "Equipment, machines, vehicles, cabinets, housings, enclosures, pumps, motors, compressors, sealed assemblies — anything with an opaque shell/casing that could hide internal parts." + }, + "fields": [ + { + "field": "containment_pairs", + "source": "SA validation_scope.cross_component_pairs not explicitly transparent (enclosure_opaque true or unset)", + "required": true, + "description": "Enclosing/enclosed boundary-ID pairs from SA §2.1, derived from boundary nomination (candidate_source hash OR semantics) and resolved to prim paths via asset_boundary_suggestions.boundaries[]. Pairs explicitly marked transparent (enclosure_opaque: false) are excluded; true or unset qualify (unknown opacity is resolved by the probe). Without scoped pairs, findOccludedMeshes has no scope and must not run on the full stage." + } + ], + "elicit_from_user": [ + { + "id": "confirm_removal", + "canonical_question": "These enclosed assets contain internal geometry invisible from outside. Remove the occluded prims found by the scoped probe? (you lose the internals)", + "context": "Present per asset on the Phase 7 iteration-2 opt-in menu, with the occluded-prim count and saving from the already-run scoped probe.", + "skip_option": "Keep internal geometry" + } + ], + "action_chain": { + "analysis_op": "findOccludedMeshes", + "action_op": "removePrims", + "pattern": "Run findOccludedMeshes in analysis mode on the scoped pairs in Phase 4 (scoped Tier 3 probe, no approval). It produces a list of fully-occluded prim paths. Feed those paths to removePrims; only the deletion step is intent-gated (Phase 7 iteration-2 opt-in)." + }, + "apply_approval": { + "detection": "Scoped probe runs in Phase 4 without approval (bounded by scope + timeout_recorded).", + "deletion": "Removing the discovered occluded prims is intent-gated — offered per asset on the Phase 7 iteration-2 opt-in menu." + } + } }, { "key": "findOverlappingMeshes", "title": "Find Overlapping Meshes", "category": "analysis", "loss_class": "analysis-only", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 4, "requires_mesh": true, "pipelines": [], @@ -327,18 +482,25 @@ "analysis" ], "source": "scene-optimizer-core/source/operations/findOverlappingMeshes/FindOverlappingMeshesOperation.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/findOverlappingMeshes.md", - "summary": "Find Overlapping Meshes detects interfering geometry \u2014 meshes whose surfaces intersect or penetrate each other.", + "summary": "Find Overlapping Meshes detects interfering geometry — meshes whose surfaces intersect or penetrate each other.", "since_version": "2026-05-08T22:40:32Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "analysis", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-interpret-validators/references/rule-reference.md", + "skills/omniverse-usd-performance-tuning/references/workflow.md" + ] + } }, { "key": "fitPrimitives", "title": "Fit Primitives", "category": "geometry", "loss_class": "bounded-loss", - "requires_confirmation": true, "risk_class": "high", + "requires_confirmation": true, + "apply_authority": "auto-within-tolerance", "args_count": 20, "requires_mesh": true, "pipelines": [], @@ -351,18 +513,24 @@ "approximate" ], "source": "scene-optimizer-core/source/operations/fitPrimitives/Primitive.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/fitPrimitives.md", "summary": "Fit Primitives analyzes meshes and replaces them with simpler geometric primitives (spheres, cylinders, cones, cubes) when the mesh closely matches one of those shapes.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md" + ] + } }, { "key": "flattenHierarchy", "title": "Flatten Hierarchy", "category": "hierarchy", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "medium", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 2, "requires_mesh": false, "pipelines": [], @@ -372,18 +540,24 @@ "scenegraph" ], "source": "scene-optimizer-core/source/operations/flattenHierarchy/FlattenHierarchy.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/flattenHierarchy.md", "summary": "Flatten Hierarchy removes redundant Xform prims from a stage's hierarchy, reducing prim count.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-interpret-validators/references/rule-reference.md" + ] + } }, { "key": "generateAtlasUVs", "title": "generateAtlasUVs", "category": "uv", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "medium", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 7, "requires_mesh": true, "pipelines": [], @@ -394,18 +568,22 @@ "texture" ], "source": "scene-optimizer-core/source/operations/generateAtlasUVs/GenerateAtlasUVs.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/generateAtlasUVs.md", "summary": "Auto UV Unwrap generates texture coordinates (UVs) by unfolding mesh surfaces into 2D.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "generateNormals", "title": "Generate Normals", "category": "geometry", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 6, "requires_mesh": true, "pipelines": [ @@ -418,18 +596,25 @@ "regenerate" ], "source": "scene-optimizer-core/source/operations/generateNormals/GenerateNormals.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/generateNormals.md", "summary": "Generate Normals computes and authors vertex normals for meshes.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md", + "skills/omniverse-usd-performance-tuning/references/workflow.md" + ] + } }, { "key": "generateProjectionUVs", "title": "Generate Projection UVs", "category": "uv", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 7, "requires_mesh": true, "pipelines": [], @@ -440,18 +625,22 @@ "texture" ], "source": "scene-optimizer-core/source/operations/generateProjectionUVs/GenerateProjectionUVs.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/generateProjectionUVs.md", "summary": "Generate Projection UVs creates texture coordinates by projecting them onto meshes using one of several projection methods (planar, cylindrical, spherical, cubic, or triplanar).", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "generateScene", "title": "Generate Scene", "category": "utility", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 12, "requires_mesh": false, "pipelines": [], @@ -463,18 +652,22 @@ "demo" ], "source": "scene-optimizer-core/source/operations/generateScene/GenerateScene.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/generateScene.md", "summary": "Generate Scene creates synthetic test scenes by procedurally placing meshes in a layout.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "manifoldMeshes", "title": "Manifold Meshes", "category": "geometry", "loss_class": "bounded-loss", - "requires_confirmation": true, "risk_class": "medium", + "requires_confirmation": true, + "apply_authority": "intent-gated", "args_count": 1, "requires_mesh": true, "pipelines": [], @@ -485,21 +678,29 @@ "topology" ], "source": "scene-optimizer-core/source/operations/manifoldMeshes/Manifold.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/manifoldMeshes.md", - "summary": "**Legacy command \u2014 use `meshCleanup` with `makeManifold: true` instead.** This operation exists for backward compatibility.", + "summary": "**Legacy command — use `meshCleanup` with `makeManifold: true` instead.** This operation exists for backward compatibility.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "deprecated", + "status_override": "deprecated", + "rationale": "deprecated: meshCleanup: legacy hole-closing command superseded by meshCleanup with makeManifold:true.", + "wired_into": [] + } }, { "key": "merge", "title": "Merge Static Meshes", "category": "transform", "loss_class": "bounded-loss", - "requires_confirmation": true, "risk_class": "high", + "requires_confirmation": true, + "apply_authority": "intent-gated", "args_count": 14, "requires_mesh": true, - "pipelines": [], + "pipelines": [ + "mesh-count-reduction" + ], "keywords": [ "merge", "combine", @@ -507,18 +708,28 @@ "instancing-conflict" ], "source": "scene-optimizer-core/source/operations/merge/Merge.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/merge.md", "summary": "Merge Static Meshes combines multiple meshes that share common properties into single merged meshes.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/operation-safety.md", + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md", + "skills/omniverse-usd-performance-tuning/references/workflow.md", + "skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/mesh-merge-rewrite-spec.md" + ], + "notes": "First-class but intent-gated Phase-4 step that EXECUTES the manifest `merge` disposition (usd-structure-assessment disposition matrix). Runs WITHIN a prototype only (merge once, benefit N instances), never across an instance boundary; ordered after occluded-geometry removal and ahead of the meshCleanup -> deduplicateGeometry -> computeExtents tail. Fails closed on strong-identity units (only weak/none identity may be fused) and on bounds-incoherent fusions (mesh-merge-rewrite-spec.md §9 merge-eligibility guard). Credited as an axis-B prim-count / scene-graph reduction (traversal + stage-open + memory + draw calls), NEVER as a disk win; a conditional vertex-weld tail credits reclaimed bytes on axis C via disk_win_source=vertex_weld." + } }, { "key": "mergeVertices", "title": "Merge Vertices", "category": "geometry", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 5, "requires_mesh": true, "pipelines": [], @@ -529,18 +740,26 @@ "tolerance" ], "source": "scene-optimizer-core/source/operations/mergeVertices/MergeVertices.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/mergeVertices.md", - "summary": "**Legacy command \u2014 use `meshCleanup` instead.** This operation exists for backward compatibility.", + "summary": "**Legacy command — use `meshCleanup` instead.** This operation exists for backward compatibility.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "deprecated", + "status_override": "deprecated", + "rationale": "deprecated: meshCleanup: legacy standalone vertex welder superseded by meshCleanup.", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/workflow.md" + ] + } }, { "key": "meshCleanup", "title": "Mesh Cleanup", "category": "geometry", - "loss_class": "bounded-loss", - "requires_confirmation": true, + "loss_class": "lossless", "risk_class": "low", + "requires_confirmation": true, + "apply_authority": "intent-gated", "args_count": 11, "requires_mesh": true, "pipelines": [ @@ -555,18 +774,26 @@ "fix" ], "source": "scene-optimizer-core/source/operations/meshCleanup/MeshCleanup.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/meshCleanup.md", "summary": "Mesh Cleanup performs a suite of mesh repair operations to fix common topological defects.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/operation-safety.md", + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md", + "skills/omniverse-usd-performance-tuning/references/workflow.md" + ] + } }, { "key": "optimizeMaterials", "title": "Optimize Materials", "category": "materials", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 4, "requires_mesh": false, "pipelines": [ @@ -581,18 +808,25 @@ "consolidate" ], "source": "scene-optimizer-core/source/operations/optimizeMaterials/OptimizeMaterials.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/optimizeMaterials.md", "summary": "Optimize Materials reduces the number of materials in a scene by deduplicating identical materials and consolidating similar ones.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/operation-safety.md", + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md" + ] + } }, { "key": "optimizePrimvars", "title": "Optimize Primvars", "category": "metadata", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 6, "requires_mesh": true, "pipelines": [], @@ -603,18 +837,24 @@ "compress" ], "source": "scene-optimizer-core/source/operations/optimizePrimvars/OptimizePrimvars.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/optimizePrimvars.md", "summary": "Optimize Primvars reduces memory usage by optimizing how primvar (per-vertex/per-face attributes like UVs, colors) data is stored.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-interpret-validators/references/rule-reference.md" + ] + } }, { "key": "optimizeSkelRoots", "title": "Optimize Skeleton Roots", "category": "hierarchy", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 0, "requires_mesh": false, "pipelines": [], @@ -625,18 +865,22 @@ "animation" ], "source": "scene-optimizer-core/source/operations/optimizeSkelRoots/OptimizeSkelRoots.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/optimizeSkelRoots.md", "summary": "Optimize Skeleton Roots merges all skinned meshes within each UsdSkelRoot to improve GPU skinning performance.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "optimizeTimeSamples", "title": "Optimize Time Samples", "category": "metadata", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 6, "requires_mesh": false, "pipelines": [ @@ -650,18 +894,25 @@ "constant" ], "source": "scene-optimizer-core/source/operations/optimizeTimeSamples/OptimizeTimeSamples.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/optimizeTimeSamples.md", "summary": "Optimize Time Samples removes redundant time samples from animated attributes.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/operation-safety.md", + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md" + ] + } }, { "key": "organizePrototypes", "title": "Organize Prototypes", "category": "hierarchy", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 2, "requires_mesh": false, "pipelines": [], @@ -672,18 +923,24 @@ "scenegraph" ], "source": "scene-optimizer-core/source/operations/organizePrototypes/OrganizePrototypes.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/organizePrototypes.md", "summary": "Organize Prototypes moves internal scene-graph instance prototypes under a user-specified namespace (class prim).", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/workflow.md" + ] + } }, { "key": "pivot", "title": "Compute Pivot", "category": "transform", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 4, "requires_mesh": true, "pipelines": [], @@ -694,18 +951,22 @@ "xform" ], "source": "scene-optimizer-core/source/operations/pivot/Pivot.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/pivot.md", "summary": "Compute Pivot recalculates and sets pivot points (transform origins) for meshes or transforms.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "primitivesToMeshes", "title": "Primitives to Meshes", "category": "geometry", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 13, "requires_mesh": false, "pipelines": [], @@ -716,18 +977,24 @@ "mesh" ], "source": "scene-optimizer-core/source/operations/primitivesToMeshes/PrimitiveToMesh.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/primitivesToMeshes.md", "summary": "Primitives to Meshes converts USD geometric primitives (UsdGeomSphere, UsdGeomCylinder, UsdGeomCone, UsdGeomCube) into polygon mesh representations.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "specialty", + "status_override": "specialty", + "rationale": "specialty: escape-hatch — the only path to convert analytic primitives back to UsdGeomMesh for downstream tools that reject primitives (some renderers, physics, exporters). Recommend only when the downstream context explicitly requires mesh output.", + "wired_into": [] + } }, { "key": "printStats", "title": "Print Stats", "category": "analysis", "loss_class": "analysis-only", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 3, "requires_mesh": false, "pipelines": [], @@ -738,18 +1005,24 @@ "analysis" ], "source": "scene-optimizer-core/source/operations/printStats/PrintStats.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/printStats.md", "summary": "Print Stats is a hidden diagnostic operation that outputs scene statistics including prim counts, mesh counts, vertex/face totals, and optionally primvar and timing information.", "since_version": "2026-05-08T22:40:32Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "analysis", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/workflow.md" + ] + } }, { "key": "pruneLeaves", "title": "Prune Leaves", "category": "hierarchy", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 3, "requires_mesh": false, "pipelines": [ @@ -764,18 +1037,26 @@ "cleanup" ], "source": "scene-optimizer-core/source/operations/pruneLeaves/PruneLeaves.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/pruneLeaves.md", - "summary": "Prune Leaves finds and removes leaf grouping primitives \u2014 Xforms and Scopes that contain no meaningful children (or only other empty groups).", + "summary": "Prune Leaves finds and removes leaf grouping primitives — Xforms and Scopes that contain no meaningful children (or only other empty groups).", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/operation-safety.md", + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md", + "skills/omniverse-usd-performance-tuning/references/workflow.md" + ] + } }, { "key": "pythonScript", "title": "Python Script", "category": "utility", "loss_class": "bounded-loss", - "requires_confirmation": true, "risk_class": "high", + "requires_confirmation": true, + "apply_authority": "intent-gated", "args_count": 1, "requires_mesh": false, "pipelines": [], @@ -786,18 +1067,28 @@ "user-code" ], "source": "scene-optimizer-core/source/operations/pythonScript/__init__.py", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/pythonScript.md", - "summary": "Python Script executes a user-defined Python script as a Scene Optimizer operation.", + "summary": "Python Script executes a user-defined Python script as a Usd Optimize operation.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "specialty", + "status_override": "specialty", + "rationale": "specialty: escape-hatch op used by usd-optimize-create-proxy's USD-authoring recipes; not part of the general optimization flow.", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/usd-optimize-create-proxy/README.md", + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md" + ] + }, + "notes": "SECURITY: executes arbitrary user-supplied Python code with the privileges of the running process. Never agent-initiated (specialty escape-hatch, see CLASSIFICATION.md); require a user-supplied or reviewed script and explicit confirmation before execution (operation-safety.md). Omitted from probe-snapshot operations_available captures (documented, not granted)." }, { "key": "remeshMeshes", "title": "Remesh Meshes", "category": "geometry", "loss_class": "bounded-loss", - "requires_confirmation": true, "risk_class": "high", + "requires_confirmation": true, + "apply_authority": "intent-gated", "args_count": 4, "requires_mesh": true, "pipelines": [], @@ -808,18 +1099,22 @@ "regenerate" ], "source": "scene-optimizer-core/source/operations/remeshMeshes/Remesh.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/remeshMeshes.md", "summary": "Remesh Meshes regenerates mesh topology to create a more uniform triangle distribution while preserving the original shape.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "removeAttributes", "title": "Remove Attributes", "category": "metadata", "loss_class": "bounded-loss", - "requires_confirmation": true, "risk_class": "medium", + "requires_confirmation": true, + "apply_authority": "intent-gated", "args_count": 3, "requires_mesh": false, "pipelines": [], @@ -830,18 +1125,22 @@ "cleanup" ], "source": "scene-optimizer-core/source/operations/removeAttributes/RemoveAttributes.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/removeAttributes.md", "summary": "Remove Attributes removes or blocks specified attributes from prims.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "removePrims", "title": "Remove Prims", "category": "hierarchy", "loss_class": "bounded-loss", - "requires_confirmation": true, "risk_class": "high", + "requires_confirmation": true, + "apply_authority": "intent-gated", "args_count": 8, "requires_mesh": false, "pipelines": [], @@ -852,18 +1151,24 @@ "delete" ], "source": "scene-optimizer-core/source/operations/removePrims/RemovePrimsPlugin.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/removePrims.md", "summary": "Remove Prims identifies and removes invisible prims and orphaned overs from a USD stage.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/operation-safety.md" + ] + } }, { "key": "removeSmallGeometry", "title": "Remove Small Geometry", "category": "geometry", "loss_class": "bounded-loss", - "requires_confirmation": true, "risk_class": "medium", + "requires_confirmation": true, + "apply_authority": "intent-gated", "args_count": 4, "requires_mesh": true, "pipelines": [ @@ -877,18 +1182,25 @@ "cleanup" ], "source": "scene-optimizer-core/source/operations/removeSmallGeometry/RemoveSmallGeometry.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/removeSmallGeometry.md", "summary": "Remove Small Geometry finds and removes meshes that are below a size threshold.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/operation-safety.md", + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md" + ] + } }, { "key": "removeUntypedPrims", "title": "Remove Untyped Prims", "category": "hierarchy", "loss_class": "bounded-loss", - "requires_confirmation": true, "risk_class": "low", + "requires_confirmation": true, + "apply_authority": "intent-gated", "args_count": 0, "requires_mesh": false, "pipelines": [], @@ -899,18 +1211,22 @@ "cleanup" ], "source": "scene-optimizer-core/source/operations/removeUntypedPrims/__init__.py", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/removeUntypedPrims.md", "summary": "Remove Untyped Prims deletes prims that have no USD schema type.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "removeUnusedUVs", "title": "Remove Unused UVs", "category": "uv", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 3, "requires_mesh": true, "pipelines": [], @@ -921,18 +1237,24 @@ "cleanup" ], "source": "scene-optimizer-core/source/operations/removeUnusedUVs/RemoveUnusedUVs.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/removeUnusedUVs.md", "summary": "Remove Unused UVs finds and removes texture coordinate (UV) attributes that are not referenced by any bound material.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "canonical", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md" + ] + } }, { "key": "rtxMeshCount", "title": "RTX Mesh Count", "category": "analysis", "loss_class": "analysis-only", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 1, "requires_mesh": true, "pipelines": [], @@ -943,18 +1265,24 @@ "stats" ], "source": "scene-optimizer-core/source/operations/rtxMeshCount/RtxMeshCount.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/rtxMeshCount.md", "summary": "RTX Mesh Count is a hidden analysis operation that counts the number of RTX acceleration structures, RTX meshes, and unique RTX meshes in the scene.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "analysis", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/workflow.md" + ] + } }, { "key": "shrinkwrap", "title": "Shrinkwrap", "category": "geometry", "loss_class": "bounded-loss", - "requires_confirmation": true, "risk_class": "high", + "requires_confirmation": true, + "apply_authority": "intent-gated", "args_count": 7, "requires_mesh": true, "pipelines": [], @@ -965,18 +1293,22 @@ "lod" ], "source": "scene-optimizer-core/source/operations/shrinkwrap/Shrinkwrap.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/shrinkwrap.md", "summary": "Shrinkwrap converts a polygon soup into a bounding watertight mesh, with controllable mechanisms to generate loose and tight surface proxies.", "since_version": "2026-03-05T22:02:49Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "sparseMeshes", "title": "Sparse Meshes", "category": "geometry", "loss_class": "bounded-loss", - "requires_confirmation": true, "risk_class": "medium", + "requires_confirmation": true, + "apply_authority": "intent-gated", "args_count": 0, "requires_mesh": true, "pipelines": [], @@ -987,18 +1319,27 @@ "geometry" ], "source": "scene-optimizer-core/source/operations/sparseMeshes/SparseMeshes.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/sparseMeshes.md", - "summary": "Sparse Meshes is a hidden analysis operation that identifies meshes with poor spatial density \u2014 geometry that occupies a large bounding box relative to its actual surface area.", + "summary": "Sparse Meshes reduces meshes with poor spatial density — geometry that occupies a large bounding box relative to its actual surface area.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "specialty", + "status_override": "specialty", + "rationale": "specialty: bespoke triage — surfaced from usd-validation-runner Tier 2 sparse-mesh findings; reach for it on user request, not from a named pipeline.", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-interpret-validators/references/rule-reference.md", + "skills/omniverse-usd-performance-tuning/references/workflow.md" + ] + } }, { "key": "splitMeshes", "title": "Split Meshes", "category": "geometry", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 16, "requires_mesh": true, "pipelines": [], @@ -1009,18 +1350,22 @@ "geometry" ], "source": "scene-optimizer-core/source/operations/splitMeshes/SplitMeshes.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/splitMeshes.md", "summary": "Split Meshes breaks meshes into smaller pieces based on geometric connectivity or spatial clustering.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "subdivideMeshes", "title": "Subdivide Meshes", "category": "geometry", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 5, "requires_mesh": true, "pipelines": [], @@ -1031,18 +1376,22 @@ "geometry" ], "source": "scene-optimizer-core/source/operations/subdivideMeshes/Subdivide.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/subdivideMeshes.md", "summary": "Subdivide Meshes increases mesh polygon density by subdividing faces.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "triangulateMeshes", "title": "Triangulate Meshes", "category": "geometry", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 2, "requires_mesh": true, "pipelines": [], @@ -1053,18 +1402,22 @@ "geometry" ], "source": "scene-optimizer-core/source/operations/triangulateMeshes/Triangulate.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/triangulateMeshes.md", "summary": "Triangulate Meshes converts all polygon faces to triangles.", "since_version": "2026-02-11T07:51:19Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "documentary", + "wired_into": [] + } }, { "key": "utilityFunction", "title": "Utility Function", "category": "utility", "loss_class": "lossless", - "requires_confirmation": false, "risk_class": "low", + "requires_confirmation": false, + "apply_authority": "auto", "args_count": 2, "requires_mesh": false, "pipelines": [], @@ -1074,10 +1427,17 @@ "internal" ], "source": "scene-optimizer-core/source/operations/utilityFunction/UtilityFunction.cpp", - "doc": "skills/omniverse-usd-performance-tuning/references/operations/utilityFunction.md", "summary": "Utility Function is a container for small one-off operations that don't merit their own plugin.", "since_version": "2026-05-08T22:40:32Z", - "requires_extension": "omni.scene.optimizer.core" + "requires_extension": "omni.scene.optimizer.core", + "curation": { + "status": "specialty", + "status_override": "specialty", + "rationale": "specialty: bespoke ad-hoc SO scripting (Deinstance / Unbind Materials / Set Instanceable / Flatten Instances); recommend only when a recipe needs one of those structural sub-functions.", + "wired_into": [ + "skills/omniverse-usd-performance-tuning/references/workflow.md" + ] + } } ] } diff --git a/skills/omniverse-usd-performance-tuning/references/operations/optimizeMaterials.md b/skills/omniverse-usd-performance-tuning/references/operations/optimizeMaterials.md deleted file mode 100644 index 7d0e26b3..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/optimizeMaterials.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: optimizeMaterials -title: Optimize Materials -source: scene-optimizer-core/source/operations/optimizeMaterials/OptimizeMaterials.cpp -category: materials -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 4 -requires_mesh: false -pipelines: [safe-cleanup, memory-reduction, load-time-reduction] -keywords: [materials, shader, dedup, consolidate] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Optimize Materials - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/optimizePrimvars.md b/skills/omniverse-usd-performance-tuning/references/operations/optimizePrimvars.md deleted file mode 100644 index e9d8d738..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/optimizePrimvars.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: optimizePrimvars -title: Optimize Primvars -source: scene-optimizer-core/source/operations/optimizePrimvars/OptimizePrimvars.cpp -category: metadata -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 6 -requires_mesh: true -pipelines: [] -keywords: [primvars, interpolation, constant, compress] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Optimize Primvars - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/optimizeSkelRoots.md b/skills/omniverse-usd-performance-tuning/references/operations/optimizeSkelRoots.md deleted file mode 100644 index d26dfe52..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/optimizeSkelRoots.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: optimizeSkelRoots -title: Optimize Skeleton Roots -source: scene-optimizer-core/source/operations/optimizeSkelRoots/OptimizeSkelRoots.cpp -category: hierarchy -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 0 -requires_mesh: false -pipelines: [] -keywords: [skeleton, skelroot, rigging, animation] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Optimize Skeleton Roots - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/optimizeTimeSamples.md b/skills/omniverse-usd-performance-tuning/references/operations/optimizeTimeSamples.md deleted file mode 100644 index 93c50176..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/optimizeTimeSamples.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: optimizeTimeSamples -title: Optimize Time Samples -source: scene-optimizer-core/source/operations/optimizeTimeSamples/OptimizeTimeSamples.cpp -category: metadata -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 6 -requires_mesh: false -pipelines: [safe-cleanup, load-time-reduction] -keywords: [time-samples, animation, compress, constant] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Optimize Time Samples - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/organizePrototypes.md b/skills/omniverse-usd-performance-tuning/references/operations/organizePrototypes.md deleted file mode 100644 index 6229237d..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/organizePrototypes.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: organizePrototypes -title: Organize Prototypes -source: scene-optimizer-core/source/operations/organizePrototypes/OrganizePrototypes.cpp -category: hierarchy -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 2 -requires_mesh: false -pipelines: [] -keywords: [prototypes, instanceable, organize, scenegraph] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Organize Prototypes - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/pivot.md b/skills/omniverse-usd-performance-tuning/references/operations/pivot.md deleted file mode 100644 index 7de9fd5b..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/pivot.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: pivot -title: Compute Pivot -source: scene-optimizer-core/source/operations/pivot/Pivot.cpp -category: transform -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 4 -requires_mesh: true -pipelines: [] -keywords: [pivot, transform, origin, xform] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Compute Pivot - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/primitivesToMeshes.md b/skills/omniverse-usd-performance-tuning/references/operations/primitivesToMeshes.md deleted file mode 100644 index 58fb3a0d..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/primitivesToMeshes.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: primitivesToMeshes -title: Primitives to Meshes -source: scene-optimizer-core/source/operations/primitivesToMeshes/PrimitiveToMesh.cpp -category: geometry -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 13 -requires_mesh: false -pipelines: [] -keywords: [primitive, convert, tessellate, mesh] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Primitives to Meshes - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/printStats.md b/skills/omniverse-usd-performance-tuning/references/operations/printStats.md deleted file mode 100644 index de3a3e5d..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/printStats.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: printStats -title: Print Stats -source: scene-optimizer-core/source/operations/printStats/PrintStats.cpp -category: analysis -loss_class: analysis-only -requires_confirmation: false -risk_class: low -args_count: 3 -requires_mesh: false -pipelines: [] -keywords: [stats, print, report, analysis] -since_version: 2026-05-08T22:40:32Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Print Stats - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/probe-snapshots/so-110.0.4.json b/skills/omniverse-usd-performance-tuning/references/operations/probe-snapshots/so-110.0.4.json deleted file mode 100644 index 0f49360f..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/probe-snapshots/so-110.0.4.json +++ /dev/null @@ -1,53 +0,0 @@ -{ - "kit_application": "USD Composer 110.1.0", - "so_extension_version": "110.0.4", - "so_build_date": "2026-02-12T00:00:00Z", - "operations_available": [ - "boxClip", - "computeExtents", - "countVertices", - "decimateMeshes", - "deduplicateGeometry", - "deleteHiddenPrims", - "deletePrims", - "diceMeshes", - "editStageMetrics", - "findCoincidingGeometry", - "findFlatHierarchies", - "findOccludedMeshes", - "fitPrimitives", - "flattenHierarchy", - "generateAtlasUVs", - "generateNormals", - "generateProjectionUVs", - "generateScene", - "manifoldMeshes", - "merge", - "mergeVertices", - "meshCleanup", - "optimizeMaterials", - "optimizePrimvars", - "optimizeSkelRoots", - "optimizeTimeSamples", - "organizePrototypes", - "pivot", - "primitivesToMeshes", - "printStats", - "pruneLeaves", - "pythonScript", - "remeshMeshes", - "removeAttributes", - "removePrims", - "removeSmallGeometry", - "removeUntypedPrims", - "removeUnusedUVs", - "rtxMeshCount", - "sparseMeshes", - "splitMeshes", - "subdivideMeshes", - "triangulateMeshes", - "utilityFunction" - ], - "probed_at": "2026-05-14T07:47:57Z", - "notes": "Captured under USD Composer 110.1.0 + Kit Python with omni.scene.optimizer.core enabled, --no-window. so_build_date set to 2026-02-12T00:00:00Z — an approximation a day after the public-source-dump cut, sufficient to cover ops committed during the dump (which carry UTC timestamps around 2026-02-11T07:51Z). Exact build date is unknown because the SO extension package metadata does not expose buildTime or a build SHA. so_extension_version manually copied from the Kit log line '[ext: omni.scene.optimizer.core-110.0.4]' since get_extension_dict returned an empty package block in this build." -} diff --git a/skills/omniverse-usd-performance-tuning/references/operations/probe-snapshots/usd-optimize-1.0.4.json b/skills/omniverse-usd-performance-tuning/references/operations/probe-snapshots/usd-optimize-1.0.4.json new file mode 100644 index 00000000..807b8cf0 --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/operations/probe-snapshots/usd-optimize-1.0.4.json @@ -0,0 +1,54 @@ +{ + "kit_application": "standalone (no Kit) - usd-optimize 1.0.4 prebuilt package", + "so_extension_version": "1.0.4", + "so_build_date": "2026-06-09T00:00:00Z", + "operations_available": [ + "boxClip", + "computeExtents", + "countVertices", + "decimateMeshes", + "deduplicateGeometry", + "deduplicateHierarchies", + "deleteHiddenPrims", + "deletePrims", + "diceMeshes", + "editStageMetrics", + "findCoincidingGeometry", + "findFlatHierarchies", + "findOccludedMeshes", + "findOverlappingMeshes", + "fitPrimitives", + "flattenHierarchy", + "generateAtlasUVs", + "generateNormals", + "generateProjectionUVs", + "generateScene", + "manifoldMeshes", + "merge", + "mergeVertices", + "meshCleanup", + "optimizeMaterials", + "optimizePrimvars", + "optimizeSkelRoots", + "optimizeTimeSamples", + "organizePrototypes", + "pivot", + "primitivesToMeshes", + "printStats", + "pruneLeaves", + "remeshMeshes", + "removeAttributes", + "removePrims", + "removeSmallGeometry", + "removeUntypedPrims", + "removeUnusedUVs", + "rtxMeshCount", + "shrinkwrap", + "sparseMeshes", + "splitMeshes", + "subdivideMeshes", + "triangulateMeshes" + ], + "probed_at": "2026-06-11T09:49:31Z", + "notes": "Captured standalone from the GitHub release asset for usd_optimize_usd_25.11_py_3.12 (version 1.0.4, manylinux_2_35_x86_64 release; build-specific suffix omitted) via UsdOptimizeCore.getInstance().getOperations() (PYTHONPATH=/python:/usdpy, LD_LIBRARY_PATH=/lib:/extraLibs, system Python 3.12.3). 45 operations listed: the 110.0.4 Kit-bundled snapshot's 44 plus deduplicateHierarchies, findOverlappingMeshes, shrinkwrap. The 2 documentary ops (pythonScript, utilityFunction) are omitted from operations_available: the skill documents but never agent-initiates them (references/operations/CLASSIFICATION.md), and listing them here is not a capability grant. so_build_date is the 1.0.4 release-notes date (2026-06-09); the package exposes no buildTime. so_extension_version is the release semver - the standalone 1.0.x scheme replaced the Kit-bundled 110.x scheme when Scene Optimizer was renamed to Usd Optimize." +} diff --git a/skills/omniverse-usd-performance-tuning/references/operations/probe-snapshots/usd-optimize-1.1.1.json b/skills/omniverse-usd-performance-tuning/references/operations/probe-snapshots/usd-optimize-1.1.1.json new file mode 100644 index 00000000..e1d75375 --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/operations/probe-snapshots/usd-optimize-1.1.1.json @@ -0,0 +1,54 @@ +{ + "kit_application": "standalone (no Kit) - usd-optimize 1.1.1 prebuilt package", + "so_extension_version": "1.1.1", + "so_build_date": "2026-07-15T00:00:00Z", + "operations_available": [ + "boxClip", + "computeExtents", + "countVertices", + "decimateMeshes", + "deduplicateGeometry", + "deduplicateHierarchies", + "deleteHiddenPrims", + "deletePrims", + "diceMeshes", + "editStageMetrics", + "findCoincidingGeometry", + "findFlatHierarchies", + "findOccludedMeshes", + "findOverlappingMeshes", + "fitPrimitives", + "flattenHierarchy", + "generateAtlasUVs", + "generateNormals", + "generateProjectionUVs", + "generateScene", + "manifoldMeshes", + "merge", + "mergeVertices", + "meshCleanup", + "optimizeMaterials", + "optimizePrimvars", + "optimizeSkelRoots", + "optimizeTimeSamples", + "organizePrototypes", + "pivot", + "primitivesToMeshes", + "printStats", + "pruneLeaves", + "remeshMeshes", + "removeAttributes", + "removePrims", + "removeSmallGeometry", + "removeUntypedPrims", + "removeUnusedUVs", + "rtxMeshCount", + "shrinkwrap", + "sparseMeshes", + "splitMeshes", + "subdivideMeshes", + "triangulateMeshes" + ], + "probed_at": "2026-07-17T00:00:00Z", + "notes": "Operation inventory and all argument sets identical to 1.0.4; per-op docs moved from .agents/operations/*.md to docs/operations/*.rst. Derived from the 2026-07-16 forward-compatibility audit of scene-optimizer-core (VERSION.md=1.1.1, HEAD 7653623d dated 2026-07-15) against tag 1.0.4: op inventory (47), every op's argument set, all defaults, deduplicateHierarchies behavior, and the deduplicateGeometry.duplicateMethod enum are byte-identical at the source level. so_build_date reflects the upstream 1.1.1 HEAD date; the package exposes no buildTime. CHANGELOG 1.0.4->1.1.1 entries are crash/robustness fixes, reporting, CI, docs, and packaging (1.1.1 added THIRD_PARTY_NOTICES / PACKAGE-LICENSES); none add, remove, or rename an operation parameter. The 2 documentary ops (pythonScript, utilityFunction) are omitted from operations_available: the skill documents but never agent-initiates them (references/operations/CLASSIFICATION.md), and listing them here is not a capability grant." +} diff --git a/skills/omniverse-usd-performance-tuning/references/operations/pruneLeaves.md b/skills/omniverse-usd-performance-tuning/references/operations/pruneLeaves.md deleted file mode 100644 index 91fd8785..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/pruneLeaves.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: pruneLeaves -title: Prune Leaves -source: scene-optimizer-core/source/operations/pruneLeaves/PruneLeaves.cpp -category: hierarchy -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 3 -requires_mesh: false -pipelines: [safe-cleanup, memory-reduction, load-time-reduction] -keywords: [prune, empty, leaves, cleanup] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Prune Leaves - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/pythonScript.md b/skills/omniverse-usd-performance-tuning/references/operations/pythonScript.md deleted file mode 100644 index e5221770..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/pythonScript.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: pythonScript -title: Python Script -source: scene-optimizer-core/source/operations/pythonScript/__init__.py -category: utility -loss_class: bounded-loss -requires_confirmation: true -risk_class: high -args_count: 1 -requires_mesh: false -pipelines: [] -keywords: [python, script, custom, user-code] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Python Script - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/remeshMeshes.md b/skills/omniverse-usd-performance-tuning/references/operations/remeshMeshes.md deleted file mode 100644 index 99facbe6..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/remeshMeshes.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: remeshMeshes -title: Remesh Meshes -source: scene-optimizer-core/source/operations/remeshMeshes/Remesh.cpp -category: geometry -loss_class: bounded-loss -requires_confirmation: true -risk_class: high -args_count: 4 -requires_mesh: true -pipelines: [] -keywords: [remesh, retopology, uniform, regenerate] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Remesh Meshes - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/removeAttributes.md b/skills/omniverse-usd-performance-tuning/references/operations/removeAttributes.md deleted file mode 100644 index 22189a52..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/removeAttributes.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: removeAttributes -title: Remove Attributes -source: scene-optimizer-core/source/operations/removeAttributes/RemoveAttributes.cpp -category: metadata -loss_class: bounded-loss -requires_confirmation: true -risk_class: medium -args_count: 3 -requires_mesh: false -pipelines: [] -keywords: [remove, attribute, metadata, cleanup] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Remove Attributes - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/removePrims.md b/skills/omniverse-usd-performance-tuning/references/operations/removePrims.md deleted file mode 100644 index 4d2995e3..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/removePrims.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: removePrims -title: Remove Prims -source: scene-optimizer-core/source/operations/removePrims/RemovePrimsPlugin.cpp -category: hierarchy -loss_class: bounded-loss -requires_confirmation: true -risk_class: high -args_count: 8 -requires_mesh: false -pipelines: [] -keywords: [remove, prim, filter, delete] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Remove Prims - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/removeSmallGeometry.md b/skills/omniverse-usd-performance-tuning/references/operations/removeSmallGeometry.md deleted file mode 100644 index b705bbc5..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/removeSmallGeometry.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: removeSmallGeometry -title: Remove Small Geometry -source: scene-optimizer-core/source/operations/removeSmallGeometry/RemoveSmallGeometry.cpp -category: geometry -loss_class: bounded-loss -requires_confirmation: true -risk_class: medium -args_count: 4 -requires_mesh: true -pipelines: [mesh-count-reduction] -keywords: [remove, small, screen-space, lod, cleanup] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Remove Small Geometry - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/removeUntypedPrims.md b/skills/omniverse-usd-performance-tuning/references/operations/removeUntypedPrims.md deleted file mode 100644 index 5a9e9f5e..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/removeUntypedPrims.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: removeUntypedPrims -title: Remove Untyped Prims -source: scene-optimizer-core/source/operations/removeUntypedPrims/__init__.py -category: hierarchy -loss_class: bounded-loss -requires_confirmation: true -risk_class: low -args_count: 0 -requires_mesh: false -pipelines: [] -keywords: [remove, untyped, scope, cleanup] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Remove Untyped Prims - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/removeUnusedUVs.md b/skills/omniverse-usd-performance-tuning/references/operations/removeUnusedUVs.md deleted file mode 100644 index 5d97ed56..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/removeUnusedUVs.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: removeUnusedUVs -title: Remove Unused UVs -source: scene-optimizer-core/source/operations/removeUnusedUVs/RemoveUnusedUVs.cpp -category: uv -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 3 -requires_mesh: true -pipelines: [] -keywords: [uv, unused, remove, cleanup] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Remove Unused UVs - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/rtxMeshCount.md b/skills/omniverse-usd-performance-tuning/references/operations/rtxMeshCount.md deleted file mode 100644 index 27f194b1..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/rtxMeshCount.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: rtxMeshCount -title: RTX Mesh Count -source: scene-optimizer-core/source/operations/rtxMeshCount/RtxMeshCount.cpp -category: analysis -loss_class: analysis-only -requires_confirmation: false -risk_class: low -args_count: 1 -requires_mesh: true -pipelines: [] -keywords: [rtx, mesh-count, raytracing, stats] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# RTX Mesh Count - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/scripts/operation-curation.schema.json b/skills/omniverse-usd-performance-tuning/references/operations/scripts/operation-curation.schema.json deleted file mode 100644 index 07d6a1d8..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/scripts/operation-curation.schema.json +++ /dev/null @@ -1,29 +0,0 @@ -{ - "$comment": "SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.\nSPDX-License-Identifier: Apache-2.0", - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "Scene Optimizer Operation Curation (this-repo)", - "description": "Sidecar for this-repo-only curation fields. Survives an upstream re-ingest because it never lives upstream. Keyed by op key.", - "type": "object", - "patternProperties": { - "^[a-zA-Z][a-zA-Z0-9]*$": { - "type": "object", - "required": ["status", "wired_into", "rationale"], - "properties": { - "status": { - "type": "string", - "enum": ["canonical", "specialty", "analysis", "documentary", "deprecated"] - }, - "wired_into": { - "type": "array", - "items": { "type": "string" } - }, - "rationale": { - "type": "string", - "pattern": "^(canonical|specialty|analysis|documentary|deprecated):", - "description": "Must start with ':' matching the entry's status. Format: ': : '. See references/operations/CLASSIFICATION.md." - } - } - } - }, - "additionalProperties": false -} diff --git a/skills/omniverse-usd-performance-tuning/references/operations/scripts/operation-manifest.schema.json b/skills/omniverse-usd-performance-tuning/references/operations/scripts/operation-manifest.schema.json deleted file mode 100644 index fb366012..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/scripts/operation-manifest.schema.json +++ /dev/null @@ -1,42 +0,0 @@ -{ - "$comment": "SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.\nSPDX-License-Identifier: Apache-2.0", - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "Scene Optimizer Operation Manifest", - "description": "Machine-readable catalog for SO ops this skill pack documents. Used to generate references/operations/README.md and to audit routing-critical metadata mirrored in per-op guide frontmatter. This-repo recommendation posture (status, wired_into, rationale) lives in _curation.json.", - "type": "object", - "required": ["operations"], - "properties": { - "schema": { - "type": "string", - "description": "Optional historical identifier kept for compatibility with the pre-existing manifest shape." - }, - "source": { - "type": "string", - "description": "Optional note describing how catalog data relates to per-op guide frontmatter mirrors." - }, - "operations": { - "type": "array", - "items": { - "type": "object", - "required": ["key", "since_version", "requires_extension"], - "properties": { - "key": { - "type": "string", - "pattern": "^[a-zA-Z][a-zA-Z0-9]*$", - "description": "Canonical op key as registered in scene-optimizer-core." - }, - "since_version": { - "type": "string", - "format": "date-time", - "description": "ISO 8601 UTC date the op first appeared in scene-optimizer-core. Used as the comparison key against probe-snapshot so_build_date. Use 2026-02-10T00:00:00Z for ops present in the initial public source dump." - }, - "requires_extension": { - "type": "string", - "description": "Kit extension that owns the op (e.g. 'omni.scene.optimizer.core')." - } - } - }, - "uniqueItems": true - } - } -} diff --git a/skills/omniverse-usd-performance-tuning/references/operations/scripts/operations.schema.json b/skills/omniverse-usd-performance-tuning/references/operations/scripts/operations.schema.json new file mode 100644 index 00000000..98ed90cb --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/operations/scripts/operations.schema.json @@ -0,0 +1,115 @@ +{ + "$comment": "SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.\nSPDX-License-Identifier: Apache-2.0", + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Usd Optimize Operation Catalog", + "description": "Single source of truth for the Usd Optimize ops this skill pack documents. Merges the former operation-manifest.schema.json (op existence + routing-critical mechanics metadata) and operation-curation.schema.json (this-repo recommendation posture). Validation is hand-rolled in tests/operations/test_manifest_schema.py to keep the suite stdlib-only. Concept->op linkage is the FK validator-concepts.json.concepts[].backing_op -> operations[].key.", + "type": "object", + "required": ["operations"], + "properties": { + "$comment": { "type": "string" }, + "schema": { + "type": "string", + "description": "Historical identifier kept for compatibility (scene_optimizer_operation_catalog)." + }, + "source": { + "type": "string", + "description": "Free-text note describing the catalog's role." + }, + "operations": { + "type": "array", + "uniqueItems": true, + "items": { + "type": "object", + "required": ["key", "curation"], + "properties": { + "key": { + "type": "string", + "pattern": "^[a-zA-Z][a-zA-Z0-9]*$", + "description": "Canonical op key as registered in scene-optimizer-core." + }, + "title": { "type": "string" }, + "category": { "type": "string" }, + "loss_class": { + "type": "string", + "enum": ["lossless", "bounded-loss", "analysis-only"] + }, + "risk_class": { + "type": "string", + "enum": ["low", "medium", "high"] + }, + "requires_confirmation": { "type": "boolean" }, + "apply_authority": { + "type": "string", + "enum": ["auto", "auto-within-tolerance", "intent-gated"], + "description": "Machine-readable BASE/default apply-authority class for this op (the single source the prose references; conceptual model owned by usd-optimize-run-operations/references/operation-safety.md 'Apply authority'). 'auto' = lossless / always-safe, runs unattended. 'auto-within-tolerance' = bounded-loss op with a deviation parameter the plan runs by default at the conservative per-target band (runs with a notice). 'intent-gated' = identity-losing / above-band / destructive, always presented for an explicit decision. This static field is the BASE class ONLY: it is subject to the target-conditional functional-tolerance downgrade (auto-within-tolerance -> intent-gated on functional-precision / above-band targets) described in operation-safety.md, which is intentionally NOT encoded here. Cross-check: requires_confirmation == (apply_authority != 'auto')." + }, + "args_count": { "type": "integer", "minimum": 0 }, + "requires_mesh": { "type": "boolean" }, + "pipelines": { + "type": "array", + "items": { "type": "string" } + }, + "keywords": { + "type": "array", + "items": { "type": "string" } + }, + "source": { "type": "string" }, + "summary": { "type": "string" }, + "since_version": { + "type": "string", + "format": "date-time", + "description": "Optional provenance: ISO 8601 UTC date the op first appeared in scene-optimizer-core. Documentary only — no tool reads it; demoted from required so it is not mandatory output. When present it must still be a valid ISO 8601 UTC date-time (checked in tests)." + }, + "requires_extension": { + "type": "string", + "description": "Optional provenance: Kit extension that owns the op (e.g. 'omni.scene.optimizer.core'). Documentary only — no tool reads it (the operationsAvailable check lives in prose); demoted from required so it is not mandatory output." + }, + "curation": { + "type": "object", + "description": "This-repo recommendation posture (was _curation.json). status is now DERIVED by the upstream status-derivation rubric (run during skill development) and materialized here; only status_override + rationale are authored.", + "required": ["status", "wired_into"], + "additionalProperties": false, + "properties": { + "status": { + "type": "string", + "enum": ["canonical", "specialty", "analysis", "documentary", "deprecated"], + "description": "GENERATED + materialized: must equal the rubric-derived status (override wins, else the rule result). Regenerated by the upstream coverage audit during skill development." + }, + "status_override": { + "type": "string", + "enum": ["specialty", "deprecated"], + "description": "Authored override for the two statuses the data cannot express: 'deprecated' (needs the named replacement) and 'specialty' (S2 narrow-workflow). When present, status must equal it and rationale is required." + }, + "rationale": { + "type": "string", + "description": "Allowed ONLY on override entries (status_override present); carries the non-derivable info (named replacement / narrow workflow). Must start with ':' (enforced in tests/audit)." + }, + "wired_into": { + "type": "array", + "items": { "type": "string" }, + "description": "Authored evidence: repo paths that route/recommend this op. Non-empty when status is canonical; one of the reference-evidence inputs to the derivation." + } + } + }, + "parameter_prerequisites": { + "description": "Optional per-op preflight/elicitation contract migrated from per-op .md frontmatter. Shape is op-specific (array of field/elicit entries, or a structured object) and intentionally unconstrained.", + "type": ["array", "object"] + }, + "recommendation_signals": { + "type": "array", + "description": "Optional evidence signals that recommend this op." + }, + "anti_patterns": { + "type": "array", + "items": { "type": "string" }, + "description": "Optional framing/anti-pattern guidance for this op." + }, + "notes": { + "type": "string", + "description": "Optional free-text guidance migrated from a per-op .md body." + } + } + } + } + } +} diff --git a/skills/omniverse-usd-performance-tuning/references/operations/shrinkwrap.md b/skills/omniverse-usd-performance-tuning/references/operations/shrinkwrap.md deleted file mode 100644 index 970ca3dd..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/shrinkwrap.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: shrinkwrap -title: Shrinkwrap -source: scene-optimizer-core/source/operations/shrinkwrap/Shrinkwrap.cpp -category: geometry -loss_class: bounded-loss -requires_confirmation: true -risk_class: high -args_count: 7 -requires_mesh: true -pipelines: [] -keywords: [shrinkwrap, wrap, proxy, lod] -since_version: 2026-03-05T22:02:49Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Shrinkwrap - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/sparseMeshes.md b/skills/omniverse-usd-performance-tuning/references/operations/sparseMeshes.md deleted file mode 100644 index c8792ea2..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/sparseMeshes.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: sparseMeshes -title: Sparse Meshes -source: scene-optimizer-core/source/operations/sparseMeshes/SparseMeshes.cpp -category: geometry -loss_class: bounded-loss -requires_confirmation: true -risk_class: medium -args_count: 0 -requires_mesh: true -pipelines: [] -keywords: [sparse, decimate, reduce, geometry] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Sparse Meshes - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/splitMeshes.md b/skills/omniverse-usd-performance-tuning/references/operations/splitMeshes.md deleted file mode 100644 index efda397c..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/splitMeshes.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: splitMeshes -title: Split Meshes -source: scene-optimizer-core/source/operations/splitMeshes/SplitMeshes.cpp -category: geometry -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 16 -requires_mesh: true -pipelines: [] -keywords: [split, partition, chunk, geometry] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Split Meshes - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/subdivideMeshes.md b/skills/omniverse-usd-performance-tuning/references/operations/subdivideMeshes.md deleted file mode 100644 index ded2d643..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/subdivideMeshes.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: subdivideMeshes -title: Subdivide Meshes -source: scene-optimizer-core/source/operations/subdivideMeshes/Subdivide.cpp -category: geometry -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 5 -requires_mesh: true -pipelines: [] -keywords: [subdivide, tessellate, smooth, geometry] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Subdivide Meshes - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/triangulateMeshes.md b/skills/omniverse-usd-performance-tuning/references/operations/triangulateMeshes.md deleted file mode 100644 index ce1ff361..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/triangulateMeshes.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: triangulateMeshes -title: Triangulate Meshes -source: scene-optimizer-core/source/operations/triangulateMeshes/Triangulate.cpp -category: geometry -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 2 -requires_mesh: true -pipelines: [] -keywords: [triangulate, quad, topology, geometry] -since_version: 2026-02-11T07:51:19Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Triangulate Meshes - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/operations/utilityFunction.md b/skills/omniverse-usd-performance-tuning/references/operations/utilityFunction.md deleted file mode 100644 index efc9b6cd..00000000 --- a/skills/omniverse-usd-performance-tuning/references/operations/utilityFunction.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -doc_type: scene_optimizer_operation -operation: utilityFunction -title: Utility Function -source: scene-optimizer-core/source/operations/utilityFunction/UtilityFunction.cpp -category: utility -loss_class: lossless -requires_confirmation: false -risk_class: low -args_count: 2 -requires_mesh: false -pipelines: [] -keywords: [utility, helper, internal] -since_version: 2026-05-08T22:40:32Z -requires_extension: omni.scene.optimizer.core ---- - - - -# Utility Function - -This local file is a routing stub only. Its YAML frontmatter is the local -catalog source for operation selection, risk, confirmation, and workflow -metadata. - -For Scene Optimizer operation mechanics, parameters, defaults, and implementation -notes, use [Operation Index](README.md) and the centralized [`usd-optimize` -upstream handoff](../upstreams/usd-optimize.md). Resolve the package operation -guide by the `operation` key in this file; do not restate upstream mechanics -here. diff --git a/skills/omniverse-usd-performance-tuning/references/optimization-report/README.md b/skills/omniverse-usd-performance-tuning/references/optimization-report/README.md index 9f0af6b3..df8c0952 100644 --- a/skills/omniverse-usd-performance-tuning/references/optimization-report/README.md +++ b/skills/omniverse-usd-performance-tuning/references/optimization-report/README.md @@ -1,24 +1,17 @@ # Optimization Report - - - ## When to Use Use this reference only at the end of the workflow after profile comparison and validation evidence are available. ## Instructions -1. Confirm the target asset, artifact, or user intent and check the prerequisites listed below. -2. Read only the referenced files needed for the current phase, failure mode, or output contract. -3. Follow the workflow, rules, and safety gates in this reference before invoking downstream references or shell commands. -4. Return the result using the Output Format section and name any blocked prerequisite or unresolved user decision. +See `references/_shared/standard-instructions.md`. Use this reference as the final step in the optimization flow — after `compare-profiles` has produced its verdict. This reference assembles the complete optimization story into a structured report. - ## Pre-flight Checklist Before generating the report, re-read and confirm: @@ -79,7 +72,7 @@ Collect from prior steps: `/setup-preflight.json` verbatim (canonical location; see `skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md` *Where artifacts live*). The report must record exactly which Kit - application, Scene Optimizer version, and Asset Validator version produced + application, Usd Optimize version, and usd-validation-nvidia version produced the result so a later reader can reproduce or audit the run. - **Measurement context** — for the stage/composition measurements used in the score. @@ -141,14 +134,14 @@ Structure: "path": "D:\\build\\chk\\usd_composer-fat\\110.1.0+main.…\\kit", "build": "110.1.0+main.10181.f4b28ef2.gl.windows-x86_64.release" }, - "sceneOptimizer": { + "usdOptimize": { "extension": "omni.scene.optimizer.core", "version": "110.0.4" }, "assetValidator": { "package": "omniverse-asset-validator", "version": "1.x.y", - "source": "kit-extension" + "source": "pip" } }, "optimization_score": 7.8, @@ -277,7 +270,7 @@ plus a `complete` boolean — to mirror the validation report rather than nestin or unresolved target keeps `complete` false and the report is not final. - `skipped_zero_meshes` is valid only when `mesh_count == 0` (the default-predicate count). A non-zero target cannot be skipped. -- A diagnosis-only / optimize-as-is run with no Phase-4 work is valid with +- A `no_op` / optimize-as-is run with no Phase-4 work is valid with `entries: []` and `complete: true`. A `monolith`-only run records its single target and needs no manifest. @@ -318,6 +311,39 @@ NVIDIA/omniperf. This report is the consumer; the producer contract is: - Keep these values out of `metric_groups[]` and `metrics[]` so the stage score stays composition-only while the runtime numbers remain visible in the report. +## Footprint attribution (repack-normalized baseline) + +Disk-size headlines are only honest once the **free crate re-encode** is split +out from the **structural optimization**. An in-place `Save()` does not compact +a USDC; an `Export()` does — so any export already shrinks the file before a +single mesh op runs. Attributing that whole compaction to dedupe/instancing +double-counts the repack (on a large-asset run the apparent footprint headline +was really a large free re-crate plus a smaller actual structural win off the +re-crated baseline; a binding-only re-export with zero dedupe already accounted +for a substantial fraction of the apparent saving). + +When the run makes any footprint claim, populate the optional top-level +`footprint` block and **report all three sizes**: + +- `raw_input_bytes` — the input as delivered (total referenced footprint). +- `repack_normalized_baseline_bytes` — the input losslessly re-crated to the + same target encoding / USD version with **zero dedupe**. This is the baseline. +- `optimized_bytes` — the optimized output. + +and **attribute the split** with `repack_delta_pct` (raw → normalized; the free +re-encode), `structural_delta_pct` (normalized → optimized; the real win), and +optionally `raw_delta_pct` (raw → optimized; the total disk saving the user +observes). Set `scored_against: "repack_normalized"`. + +**Score and gate against the normalized baseline.** The storage dimension of the +Stage Optimization Score and the report's footprint scoring both measure +`structural_delta_pct`, not the raw headline — so the report measures the +*skill*, not USD's crate writer. `validate_report.py` checks the arithmetic and +**fails closed** when the only reduction is the repack (structural shrink ≈ 0 +off the normalized baseline while raw → optimized shows a saving): presenting a +repack — or an unshared disaggregation — as the optimization win is a +fail-closed reporting error. + ## Markdown template The Markdown summary is **generated from the report JSON**, never hand-written. @@ -373,10 +399,10 @@ present); Metric Evidence; Operations; and Validators. - Always present the markdown to the user in chat. - Always produce the static HTML report when writing report artifacts, and run `python3 scripts/validate_report.py` on the report JSON before finishing. - `scored_static_html_report_required` is an agent-asserted planning guardrail — - list it in `phase_guardrails` when planning this final report contract — not an - automated gate. The automated conformance check is `python3 scripts/validate_report.py` - plus the repository schema test. + the scored static HTML report is an agent-asserted planning expectation when + planning this final report contract, not an automated gate. The automated + conformance check is `python3 scripts/validate_report.py` plus the repository + schema test. - Always title the reader-facing report **USD Performance Tuning Report**. - Always include a dedicated `Reasoning` section with one to two concise paragraphs explaining why the selected optimizations fit the evidence. @@ -408,6 +434,10 @@ present); Metric Evidence; Operations; and Validators. `layer_count`, `total_vertices`, `total_attributes`, material counts) as stage/composition evidence. Treat file size carefully: compare total referenced footprint, not root-layer size only. +- For any footprint claim, normalize against the repack baseline (see *Footprint + attribution* above): score `structural_delta_pct` (vs the re-crated baseline), + not the raw headline, and never present a crate repack or an unshared + disaggregation as the optimization win. - Generate HTML by invoking `references/report-templates/render_preview.py` with `--fixture` pointing to the report JSON and `--output` for the HTML path. Never write HTML directly — always use the renderer (see *HTML Generation* above). diff --git a/skills/omniverse-usd-performance-tuning/references/optimization-report/references/optimization-report-template.md b/skills/omniverse-usd-performance-tuning/references/optimization-report/references/optimization-report-template.md index afc432e5..9b9b97a2 100644 --- a/skills/omniverse-usd-performance-tuning/references/optimization-report/references/optimization-report-template.md +++ b/skills/omniverse-usd-performance-tuning/references/optimization-report/references/optimization-report-template.md @@ -1,6 +1,3 @@ - - - # Optimization Report Template - Per-Phase Data Collection Checklist > **Source:** Derived from `../scripts/optimization-report.schema.json` (canonical contract). This reference is the agent's "first read" - it tells you which fields you must populate by end-of-flow so each phase can collect against the final data contract. @@ -21,7 +18,7 @@ Required top-level fields: |---|---|---|---| | `asset_name` | string | Phase 0 | Set early; the basename of the input asset usually suffices. | | `input_path` | string | Phase 0 | Optional in schema, but capture it for traceability. | -| `output_path` | string | Phase 5 | Path to the optimized stage root from Phase 5d (or `null` for diagnosis-only / structural-only path). | +| `output_path` | string | Phase 5 | Path to the optimized stage root from Phase 5d (or `null` for a `no_op` or runtime-forced `structural_only` run). | | `timestamp` | string (ISO 8601) | Phase 6d | Set when the report writes. | | `verdict` | enum: `improved \| neutral \| regressed \| mixed` | Phase 6c | From `compare-profiles`. Stays in this enum in every mode; use `neutral` when no metrics changed. Express degraded/no-op runs via `workflow_mode`, not new verdict values. | | `workflow_mode` | enum: `full \| structural_only \| no_op` | Phase 6d | Optional (default `full`). `structural_only` when SO was unavailable and only USD-structural work ran; `no_op` when SA reported `already_optimized`. | @@ -32,6 +29,8 @@ Required top-level fields: | `reasoning` | string | Phase 6d | One to two paragraphs explaining why the agent chose this optimization approach for the asset, based on evidence and tradeoffs. | | `measurement_context` | object | Phases 0, 1a, 6a | Context for stage/composition measurements: runtime, cache policy, sample count, stage-open method. | | `runtime_profiling` | object | Phase 6d | Optional Omniperf/runtime-profiler handoff for RAM, VRAM, FPS, frame time, shader, renderer, and GPU metrics. | +| `footprint` | object | Phases 1a + 6 | Optional repack-normalized disk-footprint attribution. When any footprint claim is made, report `raw_input_bytes`, `repack_normalized_baseline_bytes`, `optimized_bytes` and attribute `repack_delta_pct` / `structural_delta_pct`; `scored_against: "repack_normalized"`. The storage score measures `structural_delta_pct`, not the raw headline. | +| `preservation` | object | Phases 1 + 6 | Preservation (silent-loss) gate. Required on any run that makes a structural/dedupe/instancing claim (omit only for a pure no_op with no preservation assertion). Emit `rendered_mesh_count` (must equal the asset's known pre-optimization rendered-mesh count — not authored prims), `distinct_geometry_bytes_preserved: true`, `bounds_preserved: true`, `dangling: 0`. Report scoring marks the run 0 if this block is missing or any gate changed: a "lossless" dedupe that drops rendered meshes, geometry bytes, bounds, or leaves dangling bindings is silent loss, caught here rather than by the disk number. | | `metric_groups[]` | array | Phase 6d | Stage headline areas such as composition load, structure, instancing, storage footprint, and validation. | | `artifacts` | object | Phase 6d | Paths to generated JSON, Markdown, and static HTML reports. | | `metrics[]` | array | Phases 1a + 6a | Each metric: `name`, `before`, `after`, `change_pct`, `verdict`. | @@ -53,6 +52,12 @@ Populate immediately after the runtime is chosen: ### Phase 1 - Open and characterize +- [ ] If a footprint/disk-size claim will be made, capture `raw_input_bytes` now + and compute `repack_normalized_baseline_bytes` by re-crating the input + losslessly (same target encoding / USD version, zero dedupe). The + `footprint.structural_delta_pct` reported in Phase 6 is measured against this + normalized baseline, not the raw input — never present the free crate + re-encode as the optimization. See `README.md § Footprint attribution`. - [ ] `metrics[]` - **baseline** entries with `before` populated, `after` left null until Phase 6. - Suggested baseline metrics: - `stage_open_seconds` (Phase 1a profile) @@ -66,8 +71,8 @@ in `runtime_profiling`, ideally via Omniperf dashboard/artifacts. ### Phase 2 - Composition / discovery / restructure decision -- [ ] `validators[]` - first entries (validator name + issue count from Phase 2c selected probes). One row per validator that ran. -- [ ] If user takes the "exit" branch at Phase 2e gate: skip to Phase 6d and write a diagnosis-only report (`output_path: null`, empty `operations[]`). +- [ ] `validators[]` - first entries (validator name + issue count from Phase 2c Tier 1 whole-stage probes). One row per validator that ran. +- [ ] The Phase 2e gate never exits the pipeline; it only chooses how to optimize. The only `output_path: null` / empty `operations[]` report comes from a `no_op` run (already-optimized) or the runtime-forced `structural_only` degraded path (Usd Optimize unavailable + install declined), not a user-chosen exit. ### Phase 3 - Stage-level instancing @@ -79,9 +84,10 @@ in `runtime_profiling`, ideally via Omniperf dashboard/artifacts. ### Phase 4 - Per-sub-asset mesh ops +- [ ] `validators[]` - per-target Tier 2/3 entries from the Phase 4 validate→re-verify loop (4c/4d). Name the target in each entry and record its findings (before) and re-verify result (after). - [ ] `operations[]` - one entry per op per target. The `result` field is concise per-target outcome (e.g. `meshCleanup on prototype/A: 124 prims processed, 12% triangle reduction`). -- [ ] Record the Phase 4 batch manifest path in `notes` or the Markdown summary. The manifest should include target weights, chosen concurrency per batch, resource observations, output/log paths, failures, and any adjustment or remainder-script decision. -- [ ] If adaptive batch mode generated a remainder script, record it under `notes` with the script path and remaining target count. +- [ ] Record the Phase 4 scheduler `status.json` path in `notes` or the Markdown summary. It should include target weights, chosen concurrency per batch, resource observations, output/log paths, failures, timeouts, and any adjustment or resume decision. +- [ ] If the scheduler-backed batch paused, record the `status.json` path to resume from under `notes` with the remaining (non-terminal) target count. ### Phase 5 - Reference replacement and stage cleanup @@ -91,7 +97,8 @@ in `runtime_profiling`, ideally via Omniperf dashboard/artifacts. ### Phase 6 - Verify and report - [ ] `metrics[]` - fill `after`, `change_pct`, and per-metric `verdict` from Phase 6a profile-after. -- [ ] `validators[]` - second pass entries from Phase 6b re-validation. Compare against Phase 2c entries to surface dropped/persistent issues in the Markdown summary. +- [ ] `preservation` - silent-loss gate (any structural/dedupe/instancing run). Record the post-optimization `rendered_mesh_count` and confirm it equals the asset's known pre-optimization count; set `distinct_geometry_bytes_preserved`, `bounds_preserved`, and `dangling` from the post-run measurement. Anything other than count-unchanged / `true` / `true` / `0` is silent loss and report scoring marks the run 0. Omit only for a pure `no_op`. +- [ ] `validators[]` - second pass entries from Phase 6b Tier 1 whole-stage re-validation. Compare against Phase 2c (Tier 1) and Phase 4 (per-target) entries to surface dropped/persistent issues in the Markdown summary. - [ ] `verdict` - top-level verdict from `compare-profiles` (Phase 6c). - [ ] `timestamp` - written by `optimization-report`. - [ ] `optimization_score`, `score_scope`, `score_label`, and `metric_groups[]` - computed from stage/composition metrics only. @@ -107,7 +114,7 @@ unclaimed, and keep the verdict no stronger than the remaining evidence allows. ## Special cases -### Structural-only path (SO unavailable) +### Structural-only path (Usd Optimize unavailable) When SO is unavailable and the user declines setup: @@ -120,7 +127,7 @@ When SO is unavailable and the user declines setup: ### Quick-mode-only caveat (standalone runtime, no Kit) When Phase 1a profile-stage and Phase 6a profile-after ran in quick mode -only (the standalone Scene Optimizer path has no Kit and no Tracy), +only (the standalone Usd Optimize path has no Kit and no Tracy), **explicitly call out** in the report what was measured vs unmeasured: - The `metrics[]` array carries USD-level signal only: stage open @@ -161,15 +168,25 @@ When the agent loops back from Phase 7: or delta probe; expanded validation scope requires explicit approval. - The final `verdict` reflects the cumulative comparison (first baseline vs latest after). -### Diagnosis-only +### No optimized stage written (no_op / runtime-forced structural_only) + +There is no user-chosen diagnosis-only mode — every optimization request runs the +full pipeline. A report legitimately has no optimized stage in two cases: + +- **`no_op`** — the pipeline ran but Phases 3-5 found no work (already-optimized + stage). +- **runtime-forced `structural_only`** — Usd Optimize was unavailable and the + user declined install/setup, so only structural assessment + pre-mutation + validation ran (an honest runtime block, not a chosen bypass). -If the user's intent was diagnosis-only (no mutation): +In both cases: - `output_path` is `null`. - `operations[]` is empty. - `validators[]` and baseline `metrics[]` are still populated. -- `verdict` should be `neutral` and the Markdown summary should clearly state "diagnosis-only - no optimized stage written." +- `verdict` stays within its enum (`neutral` when nothing changed); set + `workflow_mode` to `no_op` or `structural_only` accordingly. ## Schema reference -Full JSON Schema lives at `../scripts/optimization-report.schema.json`. The `optimization-report` skill is the producer; this template is the agent's pre-read so every phase collects the right data. +Full JSON Schema: `../scripts/optimization-report.schema.json`. (Why this template exists is covered in [§ Why this exists](#why-this-exists).) diff --git a/skills/omniverse-usd-performance-tuning/references/optimization-report/scripts/descent_convergence_common.py b/skills/omniverse-usd-performance-tuning/references/optimization-report/scripts/descent_convergence_common.py new file mode 100644 index 00000000..5c93d2b1 --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/optimization-report/scripts/descent_convergence_common.py @@ -0,0 +1,190 @@ +#!/usr/bin/env python3 +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""Shared descent-convergence gate logic (#186). + +The Phase-4 premature-merge / premature-decimate gate was implemented twice — +once in the report validator (``validate_report.py``) and once in the outcome +oracle scorer (``tools/oracle/score_run.py``). The two copies drifted: the +oracle copy triggered dedup on a bare ``authored_prim_delta_pct < 0`` (a +merge/removeSmallMeshes run drops authored prims with NO dedup, so that +false-failed), and both copies scanned the free-text ``result`` field with a +loose ``instance``/``prototype`` marker set that false-matched strings like +"126 instances preserved" and "point-instance aware". + +This module is the single source of truth for the gate's pure decision +functions and constants. It has NO file I/O and NO argparse — callers supply an +already-parsed ``report`` dict, a list of manifest dicts, and (for convergence) +a NORMALIZED frontier dict with these keys: + + descent_converged : bool + final_rescan_new_groups_above_floor : int | None + convergence_waived_by_user : bool + convergence_waiver_reason : str | None + +Each caller keeps its own frontier-source adapter (the validator reads manifest +``frontier`` blocks + the report ``structural_summary`` mirror; the oracle reads +the report mirror only) and maps its source fields onto those normalized keys. +""" +from __future__ import annotations + +from typing import Any + +#: Operation name/method substrings that mean dedup / instancing / restructure +#: happened THIS RUN — i.e. a de-duplication frontier descent was in play and its +#: convergence is meaningful. TIGHTENED (#186 finding 2): bare "instance" and +#: "prototype" are deliberately EXCLUDED. They false-matched benign strings such +#: as "126 instances preserved" and "point-instance aware" when the free-text +#: result/summary field was scanned, tripping the gate on runs that did no dedup. +#: These markers are unambiguous dedup/instancing/externalize op names. +DEDUP_OP_MARKERS = ( + "deduplicate", "instanceable", "internal_reference", "internal_share", + "externalize", +) + +#: Phase-4 GEOMETRY ops whose presence requires a CONVERGED dedup frontier first. +#: Matched as lowercase substrings against report ``operations[]`` name/method and +#: ``target_coverage.entries[].operations[]``. These are the lossy / +#: identity-affecting reductions that, run before the frontier converges, fuse or +#: coarsen geometry that further sharing would have collapsed (premature-merge / +#: premature-decimate inflation). Within-prototype mesh merge is detected via the +#: declared ``structural_summary.merge_applied`` / ``preservation`` flags, not by a +#: bare "merge" name match (which also hits the lossless probe). +PHASE4_GEOMETRY_OP_MARKERS = ( + "decimat", "fitprimitiv", "quantiz", "remesh", "subdivid", + "triangulat", "removesmall", "mergevertices", "dicemesh", "sparsemesh", +) + +#: Coverage-entry roles that mean "a restructure happened this run", so their +#: presence is a this-run dedup signal. +RESTRUCTURE_ROLES = frozenset( + {"assembly_root", "prototype", "shared_layer", "loadable_subasset"} +) + + +def _is_number(x: Any) -> bool: + """True for a real int/float, excluding bool (which is an int subclass).""" + return isinstance(x, (int, float)) and not isinstance(x, bool) + + +def iter_operation_strings(report: Any): + """Yield the lowercased name+method of each op in ``report['operations']`` and + each string in ``target_coverage.entries[].operations[]``. + + Deliberately JOINS the op ``name`` and ``method`` but does NOT include the + free-text ``result``/``summary`` field (#186 finding 2): the result text + carries prose like "126 instances preserved" / "point-instance aware" that a + substring marker match mistook for a dedup op. Only the structured + name/method identify what the op WAS. + """ + if not isinstance(report, dict): + return + for op in report.get("operations", []) or []: + if isinstance(op, dict): + parts = [op.get(key) for key in ("name", "method")] + joined = " ".join(p for p in parts if isinstance(p, str)) + if joined: + yield joined.lower() + coverage = report.get("target_coverage") + if isinstance(coverage, dict): + for entry in coverage.get("entries", []) or []: + if isinstance(entry, dict): + for value in entry.get("operations", []) or []: + if isinstance(value, str): + yield value.lower() + + +def did_phase4_geom(report: Any) -> bool: + """True when a lossy / identity-affecting Phase-4 geometry op ran. + + Signals: ``structural_summary.merge_applied`` is True, OR + ``preservation.allow_merge`` is True, OR ``preservation.rendered_mesh_merged_count`` + > 0, OR any op name/method contains a PHASE4_GEOMETRY_OP_MARKER. + """ + if not isinstance(report, dict): + return False + ss = report.get("structural_summary") or report.get("structural") or {} + if isinstance(ss, dict) and ss.get("merge_applied") is True: + return True + pres = report.get("preservation") + if isinstance(pres, dict): + if pres.get("allow_merge") is True: + return True + merged = pres.get("rendered_mesh_merged_count") + if _is_number(merged) and merged > 0: + return True + for text in iter_operation_strings(report): + if any(marker in text for marker in PHASE4_GEOMETRY_OP_MARKERS): + return True + return False + + +def did_dedup(report: Any, manifests: Any = ()) -> bool: + """True when the run performed hierarchy dedup / instancing / restructure THIS + RUN — so a frontier descent was in play and its convergence is meaningful. + + Keyed on THIS-RUN signals ONLY, never on absolute post-state. The triggers: + + (a) an apply-restructure manifest carrying ``phase4_targets`` or ``frontier``; + (b) ``structural_summary.reuse_measured`` is True (this run measured reuse); + (c) a ``metrics[]`` entry ``name == "instance_count"`` with BOTH ``before`` and + ``after`` present as real numbers and ``after > before`` (a real increase); + (d) a DEDUP_OP_MARKER in ``iter_operation_strings(report)``; + (e) a ``target_coverage.entries[]`` with ``role`` in RESTRUCTURE_ROLES. + + It MUST NOT trigger on a bare ``authored_prim_delta_pct < 0`` (a merge / + removeSmallMeshes-only run drops authored prims with no dedup — #186 finding 1), + nor on a bare absolute ``unique_prototype_count`` / ``instance_ratio`` / + ``instance_count`` post-state (an asset already instanced at source and + optimized for disk did no NEW dedup this run). + """ + for manifest in manifests or []: + if isinstance(manifest, dict) and ( + manifest.get("phase4_targets") or manifest.get("frontier") + ): + return True + if not isinstance(report, dict): + return False + ss = report.get("structural_summary") or report.get("structural") or {} + if isinstance(ss, dict) and ss.get("reuse_measured") is True: + return True + for metric in report.get("metrics", []) or []: + if isinstance(metric, dict) and metric.get("name") == "instance_count": + before = metric.get("before") + after = metric.get("after") + if _is_number(before) and _is_number(after) and after > before: + return True + for text in iter_operation_strings(report): + if any(marker in text for marker in DEDUP_OP_MARKERS): + return True + coverage = report.get("target_coverage") + if isinstance(coverage, dict): + for entry in coverage.get("entries", []) or []: + if isinstance(entry, dict) and entry.get("role") in RESTRUCTURE_ROLES: + return True + return False + + +def is_converged_or_waived(frontier: Any) -> bool: + """True when a NORMALIZED frontier dict records a converged descent OR a valid + user waiver. Fails CLOSED on ambiguity (#186 findings 3 & 4). + + Waiver branch — a waiver counts ONLY when ``convergence_waived_by_user`` is + truthy AND ``convergence_waiver_reason`` is a non-empty string. The schema + says a waiver "Requires ...waiver_reason. Silence is NOT a waiver", so a + reasonless waiver does NOT clear the gate. + + Converged branch — counts ONLY when ``descent_converged is True`` AND + ``final_rescan_new_groups_above_floor`` is an int (not bool) EQUAL to 0. The + schema says convergence "requires ... == 0"; a None/absent rescan field must + NOT count as converged (fail closed — absence is not evidence). + """ + if not isinstance(frontier, dict): + return False + if frontier.get("convergence_waived_by_user"): + reason = frontier.get("convergence_waiver_reason") + return isinstance(reason, str) and bool(reason.strip()) + if frontier.get("descent_converged") is True: + rescan = frontier.get("final_rescan_new_groups_above_floor") + return _is_number(rescan) and isinstance(rescan, int) and rescan == 0 + return False diff --git a/skills/omniverse-usd-performance-tuning/references/optimization-report/scripts/optimization-report.schema.json b/skills/omniverse-usd-performance-tuning/references/optimization-report/scripts/optimization-report.schema.json index 34f2c8e7..32623288 100644 --- a/skills/omniverse-usd-performance-tuning/references/optimization-report/scripts/optimization-report.schema.json +++ b/skills/omniverse-usd-performance-tuning/references/optimization-report/scripts/optimization-report.schema.json @@ -10,11 +10,9 @@ "timestamp", "verdict", "optimization_score", - "score_scope", "score_label", "reasoning", "measurement_context", - "artifacts", "metric_groups", "metrics", "operations", @@ -33,7 +31,7 @@ }, "output_path": { "type": ["string", "null"], - "description": "Path to the optimized output stage; null for diagnosis-only, no-op, or structural-only runs where no optimized stage was written." + "description": "Path to the optimized output stage; null for no_op (already-optimized) or runtime-forced structural_only runs where no optimized stage was written." }, "timestamp": { "type": "string", @@ -43,25 +41,30 @@ "verdict": { "type": "string", "enum": ["improved", "neutral", "regressed", "mixed"], - "description": "Overall optimization verdict from compare-profiles. Stays within this enum regardless of workflow_mode; use 'neutral' when no metrics changed. Degraded (Scene Optimizer unavailable) and no-op runs are expressed via workflow_mode, not by inventing new verdict values." + "description": "Overall optimization verdict from compare-profiles. Stays within this enum regardless of workflow_mode; use 'neutral' when no metrics changed. Degraded (Usd Optimize unavailable) and no-op runs are expressed via workflow_mode, not by inventing new verdict values." }, "workflow_mode": { "type": "string", "enum": ["full", "structural_only", "no_op"], - "description": "Execution mode for this run. 'full' = optimization/mutation ran (default when omitted); 'structural_only' = Scene Optimizer was unavailable so only USD-structural work ran and no mesh operations executed; 'no_op' = no optimization was needed (e.g., structure assessment reported already_optimized). The verdict stays in its own enum in every mode." + "description": "Execution mode for this run. 'full' = optimization/mutation ran (default when omitted); 'structural_only' = Usd Optimize was unavailable so only USD-structural work ran and no mesh operations executed; 'no_op' = no optimization was needed (e.g., structure assessment reported already_optimized). The verdict stays in its own enum in every mode." }, "notes": { "type": "string", "description": "Free-form caveats the verdict and score cannot capture on their own: degraded-path explanation, the runtime or access blocker that prevented a stronger verdict, or the next profile capture needed to graduate it." }, + "next_profile_capture": { + "type": "string", + "description": "Required by SKILL.md on the runtime-forced degraded path (workflow_mode: structural_only): which runtime profiling should be captured later (e.g. Kit/omniperf FPS, VRAM, frame-time on the optimized stage) to graduate the structural verdict into a runtime one. Optional in all other modes." + }, "runtime_context": { "type": "object", - "description": "Snapshot of the Kit / Scene Optimizer / Asset Validator versions in effect for this run. Copied verbatim from setup-preflight.json so later readers can reproduce or audit the report. Mirrors the runtime-context fields defined in skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md.", - "required": ["kit", "sceneOptimizer", "assetValidator"], + "description": "Snapshot of the Kit / Usd Optimize / usd-validation-nvidia versions in effect for this run. Copied verbatim from setup-preflight.json so later readers can reproduce or audit the report. Mirrors the runtime-context fields defined in skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md.", + "required": ["usdOptimize", "assetValidator"], "properties": { "kit": { "type": "object", "required": ["application", "version", "path"], + "description": "Kit application context. OPTIONAL: omitted on a standalone-only runtime (Kit is an opt-in render-profiling adjunct). When present, application/version/path are required.", "properties": { "application": { "type": "string", @@ -81,7 +84,7 @@ } } }, - "sceneOptimizer": { + "usdOptimize": { "type": "object", "required": ["extension", "version"], "properties": { @@ -109,8 +112,8 @@ }, "source": { "type": "string", - "enum": ["kit-extension", "pip", "standalone"], - "description": "Where Asset Validator was loaded from." + "enum": ["pip", "standalone"], + "description": "Where usd-validation-nvidia was loaded from." } } } @@ -125,7 +128,7 @@ "score_scope": { "type": "string", "enum": ["stage_optimization"], - "description": "Scope of optimization_score. This report scores stage/composition optimization effectiveness, not full runtime performance." + "description": "Optional. Scope of optimization_score: this report scores stage/composition optimization effectiveness, not full runtime performance. Single-value enum kept for explicitness; not rendered (the renderer uses score_scope_label) and not gated, so it is optional rather than required." }, "score_label": { "type": "string", @@ -147,6 +150,178 @@ "type": ["string", "number", "boolean", "null"] } }, + "footprint": { + "type": "object", + "description": "Repack-normalized disk-footprint attribution (report-contract correction). A USDC/crate repack is the free re-encode any Export achieves; it is NOT the optimization. Report all three sizes and attribute the split so a repack-inflated headline cannot masquerade as the structural win. The storage dimension of the Stage Optimization Score and any footprint claim are measured against repack_normalized_baseline_bytes, never the raw input. Example: a large input that re-crates losslessly to a much smaller baseline (a free re-encode) and only then shows a smaller dedupe-into-shared-prototypes win off that normalized baseline. Optional block; when present, validate_report.py checks the arithmetic and fails closed on a repack-only 'win'.", + "required": ["raw_input_bytes", "repack_normalized_baseline_bytes", "optimized_bytes", "structural_delta_pct", "scored_against"], + "additionalProperties": false, + "properties": { + "raw_input_bytes": { + "type": "number", + "minimum": 0, + "description": "Raw input stage size on disk as delivered (total referenced footprint, not root-layer size only)." + }, + "repack_normalized_baseline_bytes": { + "type": "number", + "minimum": 0, + "description": "Input losslessly re-crated to the same target encoding / USD version with zero dedupe. The honest baseline the structural win is measured against; isolates the free crate re-encode from the optimization." + }, + "optimized_bytes": { + "type": "number", + "minimum": 0, + "description": "Optimized output stage size on disk (same referenced-footprint basis as the inputs)." + }, + "repack_delta_pct": { + "type": "number", + "description": "raw_input -> repack_normalized_baseline percent change. The free re-encode delta (expected <= 0); explicitly NOT the optimization." + }, + "structural_delta_pct": { + "type": "number", + "description": "repack_normalized_baseline -> optimized percent change. The actual structural optimization win (dedupe into shared prototypes + instancing); the number the score and the run-scoring oracle gate against." + }, + "raw_delta_pct": { + "type": "number", + "description": "raw_input -> optimized percent change. The total disk saving the user observes; true and useful but must not be conflated with the structural win." + }, + "scored_against": { + "type": "string", + "enum": ["repack_normalized"], + "description": "Pins that the storage dimension and any footprint claim score against the repack-normalized baseline, not the raw input. The only valid value; present so the contract is explicit and machine-checkable." + }, + "disk_win_source": { + "type": "string", + "enum": ["none", "sharing", "sharing_only", "repack", "mesh_merge", "dead_data_removal", "unused_primvar_removal", "primvar_indexing", "layer_consolidation", "lossy_reduction", "decimation", "fit_primitive", "vertex_weld"], + "description": "What produced a claimed disk reduction. The run-scoring oracle (its _guard_sharing_only_disk_win check) fails closed when structural_delta_pct is a real win (< -1%) but the source is NOT a legitimate byte-reduction lever: 'sharing'/'sharing_only' (instancing/hierarchy dedup), 'mesh_merge', 'repack', 'none', or unset all FAIL — the crate already byte-deduplicates identical arrays within a layer, so sharing frees ~no bytes and a merge just concatenates geometry (bytes ~= sum). A genuine disk win must be data removal (dead_data_removal / unused_primvar_removal), primvar_indexing, cross-file layer_consolidation, a lossy op (lossy_reduction / decimation / fit_primitive), or a coincident-seam vertex_weld (welds out the duplicated boundary verts a per-face split introduced — real bytes, credited here and NEVER attributed to the merge that exposed them)." + }, + "notes": { "type": "string" } + } + }, + "structural_summary": { + "type": "object", + "description": "Scene-graph (axis-B) outcome the run-scoring oracle reads for the structural capture ratio and the measured-reuse gate. This is a RUNTIME / scene-graph claim (fewer composed prims, instancing, fewer draw calls from a within-prototype merge) and is flagged unverified-at-render until a runtime_profiling capture is attached; it is disk-neutral on its own (see footprint.disk_win_source for the disk axis).", + "additionalProperties": true, + "properties": { + "reuse_measured": { + "type": "boolean", + "description": "True only when the run MEASURED the reuse it collapsed (distinct vs total prototypes/units). The scorer scores no axis-B credit for an unmeasured consolidation claim when the oracle sets ceilings.structural.requires_measured_reuse." + }, + "authored_prim_delta_pct": { + "type": "number", + "description": "Authored-prim count percent change (negative = reduction). The primary axis-B metric; from instancing/dedup into shared prototypes. Instance-expanded scope." + }, + "unique_prototype_count": { "type": "integer", "minimum": 0, "description": "Number of distinct prototypes after restructure." }, + "instance_ratio": { "type": "number", "minimum": 0, "description": "Instances / total occurrences; higher is more reuse, scored toward the ceiling." }, + "prototype_rendered_mesh_delta_pct": { + "type": "number", + "description": "PROTOTYPE-scope rendered-mesh percent change (negative = reduction) from a within-prototype mesh merge — 'merge once, benefit N'. The scorer credits THIS (not the instance-expanded count) for the draw-call axis-B win, so it does not double-count with authored_prim_delta_pct / instanced reuse." + }, + "merge_applied": { + "type": "boolean", + "description": "Optional signal flag: true when a within-prototype mesh merge was performed in this run. Declarative only — the run-scoring oracle does NOT read it; it credits the merge (axis B) via prototype_rendered_mesh_delta_pct + merge_bounds_coherence and guards it via merge_identity_class + preservation.rendered_mesh_merged_count / rendered_triangle_count. Emit it for human/audit readability, not for scoring." + }, + "merge_identity_class": { + "type": "string", + "enum": ["weak", "none"], + "description": "Identity class of the units fused by the merge. A merge destroys per-part identity, so only 'weak' (anonymous, identity-not-wanted) or 'none' (identity-free fragments) units may be merged. A strong-identity (addressable component/subcomponent) unit must NOT be merged — the scorer's preservation gate fails any other value." + }, + "merge_bounds_coherence": { + "type": "number", + "minimum": 0, + "description": "Merged-prim AABB surface area / Sum(member AABB surface area). ~1 = the fused members were spatially adjacent (a legitimate draw-call merge). A value far above 1 means a merge of DISPERSED meshes that balloons the AABB and harms BVH/raytracing; the scorer grants NO draw-call credit when this exceeds MERGE_BOUNDS_COHERENCE_MAX (default 2.0), and the merge should not have been performed." + }, + "frontier_descent_converged": { + "type": "boolean", + "description": "Report-side mirror of the apply-restructure manifest's frontier.descent_converged. Set true only when the bounded recursive de-duplication descent CONVERGED — a fresh one-level-down reuse re-scan found nothing new above the floor. validate_report.py's descent-convergence gate requires this true (with frontier_final_rescan_new_groups_above_floor == 0) OR a manifest frontier that records the same OR frontier_convergence_waived, before any Phase-4 geometry op (decimation / within-prototype merge / primitive-fit / quantization / topology edit) is permitted on a dedup/instancing run. Carry it here for manifest-less runs." + }, + "frontier_final_rescan_new_groups_above_floor": { + "type": "integer", + "minimum": 0, + "description": "Report-side mirror of the manifest field: the count of new shareable groups (occurrence >= 2, above the MINP floor) the terminal one-level-down re-scan found. 0 == converged. > 0 together with frontier_descent_converged == true is a contradiction the gate rejects (the descent was declared complete while reuse remained one level down)." + }, + "frontier_convergence_waived": { + "type": "boolean", + "description": "Optional explicit user opt-out: true when the user chose to stop the descent before it converged and proceed to geometry ops anyway. Requires frontier_convergence_waiver_reason. Silence is NOT a waiver — the gate fails closed on an unconverged frontier with no recorded waiver." + }, + "frontier_convergence_waiver_reason": { + "type": "string", + "description": "Required when frontier_convergence_waived is true: the recorded reason the descent was stopped early (e.g. addressability cost, user time budget)." + }, + "notes": { "type": "string" } + } + }, + "safety_gate": { + "type": "object", + "description": "Correctness-precondition state (e.g. dangling material bindings repaired BEFORE structuring). The run-scoring oracle fails closed on a status that is not resolved/clear/none/passed/not_required.", + "additionalProperties": true, + "properties": { + "status": { "type": "string", "description": "resolved | clear | none | passed | not_required (cleared) vs. unresolved | blocked | failed (the scorer zeroes the run)." }, + "finding": { "type": "string" }, + "notes": { "type": "string" } + } + }, + "fidelity": { + "type": "object", + "description": "Lossy-tier fidelity evidence. The run-scoring oracle fails closed when max_deviation_within_band is false (a run that 'beats' a ceiling by over-decimating beyond the per-target band).", + "additionalProperties": true, + "properties": { + "max_deviation_within_band": { "type": "boolean" }, + "band": { "type": "string" }, + "notes": { "type": "string" } + } + }, + "preservation": { + "type": "object", + "description": "Axis-A silent-loss block — the proof that an optimization (especially a 'lossless' dedupe/instancing pass) did not silently drop geometry. This is the hard gate the run-scoring oracle reads to catch a pass that shrank the disk or collapsed authored prims while quietly losing rendered meshes, geometry bytes, bounds, or binding integrity. Field names match exactly what the scorer consumes so the schema, scorer, and validator agree. Emit this block on any run that makes a structural/dedupe/instancing claim; a run whose oracle asserts axis-A scores 0 when the block is missing. Optional only for runs with no axis-A assertion (e.g. a pure no_op).", + "required": ["rendered_mesh_count", "distinct_geometry_bytes_preserved", "bounds_preserved", "dangling"], + "additionalProperties": false, + "properties": { + "rendered_mesh_count": { + "type": "integer", + "minimum": 0, + "description": "Rendered-mesh count after optimization. Must equal the asset's known pre-optimization rendered-mesh count; the scorer fails the run (silent loss) on any change. Counts rendered meshes, not authored prims — an authored-prim collapse from dedupe/instancing is expected and is NOT a change here." + }, + "distinct_geometry_bytes_preserved": { + "type": "boolean", + "description": "True only when the total distinct geometry bytes (the unique mesh data, ignoring instanced repetition) are preserved across the optimization. The scorer treats anything other than true as silent loss." + }, + "bounds_preserved": { + "type": "boolean", + "description": "True only when the stage/world bounds are unchanged (within tolerance) after optimization. The scorer treats anything other than true as silent loss." + }, + "dangling": { + "type": "integer", + "minimum": 0, + "description": "Count of dangling relationships/bindings (e.g. material bindings pointing at removed prims) after optimization. Must be 0; the scorer fails the run when it exceeds the oracle's max_dangling (0 by default)." + }, + "allow_merge": { + "type": "boolean", + "description": "Optional declaration: set true on a run that performed a within-prototype mesh merge. A merge fuses many small meshes into one, so the rendered_mesh_count legitimately DROPS by rendered_mesh_merged_count. NOTE: the run-scoring oracle relaxes the strict rendered-mesh-count equality based on the matching ORACLE's preservation.allow_merge (the golden config), NOT this report-side field — so this member is a human/audit-facing declaration, not a scorer input. The merge accounting itself is enforced via rendered_mesh_merged_count (rendered_mesh_count + rendered_mesh_merged_count == known); an unaccounted drop is still silent loss and fails closed." + }, + "rendered_mesh_merged_count": { + "type": "integer", + "minimum": 0, + "description": "How many rendered meshes the merge fused away (the declared drop). The scorer requires rendered_mesh_count + rendered_mesh_merged_count == the asset's known pre-merge count; distinct_geometry_bytes_preserved must still be true (a merge concatenates, it must not DROP geometry)." + }, + "rendered_triangle_count": { + "type": "integer", + "minimum": 0, + "description": "Renderable triangle total after optimization — the authoritative silent-loss invariant for a mesh merge. A merge fuses prims and welds coincident points, so rendered_mesh_count and distinct point counts legitimately change, but the renderable triangle total must not (a re-pack preserves every face). When the matching oracle asserts preservation.rendered_triangle_count, the scorer fails the run if this differs beyond the oracle's triangle_tolerance_pct — catching an over-coarse weld that collapses geometry even when the merge mesh-count accounting (rendered_mesh_count + rendered_mesh_merged_count == known) still balances. Emit it on any merge run." + }, + "merge_locality_preserved": { + "type": "boolean", + "description": "Merge LOCALITY invariant: true only when every fused mesh stayed UNDER its named-component merge boundary — no geometry relocated to a shallower ancestor or the stage root. A single stage-wide merge buckets meshes by material across the whole stage and mergePoint=Parent resolves to their common ancestor (the root), dumping anonymous merged* blobs at the root and emptying the named kind-tagged components of their geometry. That is identity-destroying even when triangles and the mesh-count accounting balance, so on any allow_merge run the scorer fails closed unless this is true (and meshes_relocated_outside_boundary is 0). Compute it by checking each merged prim's parent against the expected boundary — kind-prim survival alone is NOT enough (the kind Xforms can survive while emptied). Scope one merge call per component to keep locality (mesh-merge-rewrite-spec.md §5)." + }, + "meshes_relocated_outside_boundary": { + "type": "integer", + "minimum": 0, + "description": "Evidence for merge_locality_preserved: count of fused prims that ended up outside their named-component boundary (e.g. at the stage root). 0 == local. Any positive value fails the preservation gate." + }, + "notes": { + "type": "string", + "description": "Optional free-form note, e.g. how the rendered-mesh count and distinct-bytes/bounds were measured." + } + } + }, "runtime_profiling": { "type": "object", "description": "Optional handoff section for runtime performance profiling. Use Omniperf or an equivalent runtime profiler for RAM, VRAM, FPS, frame time, renderer, shader, and GPU metrics instead of folding them into the Stage Optimization Score.", @@ -165,8 +340,7 @@ }, "artifacts": { "type": "object", - "description": "Report artifact paths generated from this JSON source of truth.", - "required": ["json", "markdown", "html"], + "description": "Optional provenance: report artifact paths generated from this JSON source of truth. Self-referential paths — not rendered by the report templates and not read by any gate, so the block and its members are optional (emit for traceability). additionalProperties stays false so a typo'd artifact key is still caught when the block is present.", "additionalProperties": false, "properties": { "json": { "type": "string" }, @@ -270,7 +444,7 @@ }, "target_coverage": { "type": "object", - "description": "Phase-4 mesh-optimization coverage ledger, structurally parallel to the validation report's coverage_ledger. entries[] must cover the UNION of every iteration's apply-restructure manifest phase4_targets[]; complete is true only when every entry reached a resolved disposition. validate_report.py reconciles this against the upstream manifest(s) so a target that was never enumerated (e.g. an assembly_root dropped from a later iteration's manifest) fails closed instead of silently passing. Reconciliation is NOT optional once a restructure happened: if any entry has a restructure role (assembly_root | prototype | shared_layer | loadable_subasset) the gate requires a manifest, supplied via --manifest or recorded in source_manifests[]. A diagnosis-only / optimize-as-is-monolith run (no restructure roles) is manifest-free; an empty Phase-4 run is valid with entries: [] and complete: true.", + "description": "Phase-4 mesh-optimization coverage ledger, structurally parallel to the validation report's coverage_ledger. entries[] must cover the UNION of every iteration's apply-restructure manifest phase4_targets[]; complete is true only when every entry reached a resolved disposition. validate_report.py reconciles this against the upstream manifest(s) so a target that was never enumerated (e.g. an assembly_root dropped from a later iteration's manifest) fails closed instead of silently passing. Reconciliation is NOT optional once a restructure happened: if any entry has a restructure role (assembly_root | prototype | shared_layer | loadable_subasset) the gate requires a manifest, supplied via --manifest or recorded in source_manifests[]. A no_op / optimize-as-is-monolith run (no restructure roles) is manifest-free; an empty Phase-4 run is valid with entries: [] and complete: true.", "required": ["complete", "entries"], "additionalProperties": false, "properties": { @@ -304,6 +478,11 @@ "minimum": 0, "description": "Default-predicate mesh count for this target (echoed from the manifest's authoritative count). disposition 'skipped_zero_meshes' is valid only when this is 0." }, + "optimized_mesh_count": { + "type": "integer", + "minimum": 0, + "description": "How many of this target's meshes the Phase-4 op chain actually touched/optimized. When disposition is 'optimized' and mesh_count > 0, an optimized_mesh_count of 0 is flagged as a no-op masquerading as optimized. Minimal effort signal: a single count, not a before/after op-audit trail." + }, "disposition": { "type": "string", "enum": ["optimized", "skipped_zero_meshes", "skipped_user_declined", "blocked"], diff --git a/skills/omniverse-usd-performance-tuning/references/optimization-report/scripts/test_validate_report_descent.py b/skills/omniverse-usd-performance-tuning/references/optimization-report/scripts/test_validate_report_descent.py new file mode 100644 index 00000000..ce09473f --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/optimization-report/scripts/test_validate_report_descent.py @@ -0,0 +1,204 @@ +#!/usr/bin/env python3 +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""Dependency-free tests for the descent-convergence gate (validate_descent_convergence). + +Run: python3 test_validate_report_descent.py (exit 0 = all pass, 1 = a failure) +No pytest / third-party deps, matching validate_report.py's standalone ethos. +""" +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import validate_report as V # noqa: E402 +import descent_convergence_common as dcc # noqa: E402 + +CASES = [] + + +def case(name, report, manifests, *, expect_error, marker=None): + CASES.append((name, report, manifests, expect_error, marker)) + + +# Building blocks +DEDUP_SS = {"unique_prototype_count": 48, "instance_ratio": 0.0016} +INSTANCE_METRIC = [{"name": "instance_count", "before": 0, "after": 126}] +DECIMATE_OP = [{"order": 4, "name": "decimateMeshes", "method": "0.1mm", "result": "faces -55%"}] +MERGE_SS = {"unique_prototype_count": 48, "merge_applied": True} +CONVERGED_SS = {"frontier_descent_converged": True, "frontier_final_rescan_new_groups_above_floor": 0} +CONVERGED_MANIFEST = {"phase4_targets": [{"path": "/p", "target_class": "prototype", "mesh_count": 5}], + "frontier": {"reuse_measured": True, "descent_converged": True, + "final_rescan_new_groups_above_floor": 0}} + +# 1. monolith decimate, NO dedup -> gate N/A -> PASS +case("monolith_decimate_no_dedup", + {"operations": DECIMATE_OP, "target_coverage": {"entries": [{"path": "/m", "role": "monolith"}]}}, + [], expect_error=False) + +# 2. dedup + decimate, NO convergence recorded -> FAIL (FF1) +case("dedup_decimate_unconverged", + {"structural_summary": DEDUP_SS, "metrics": INSTANCE_METRIC, "operations": DECIMATE_OP}, + [], expect_error=True, marker="descent-convergence gate") + +# 3. dedup + decimate, report mirror converged -> PASS +case("dedup_decimate_converged_report", + {"structural_summary": {**DEDUP_SS, **CONVERGED_SS}, "metrics": INSTANCE_METRIC, "operations": DECIMATE_OP}, + [], expect_error=False) + +# 4. dedup + merge, manifest frontier converged -> PASS +case("dedup_merge_converged_manifest", + {"structural_summary": MERGE_SS, "operations": [{"order": 8, "name": "merge", "method": "Parent Prim", "result": "-6k"}]}, + [CONVERGED_MANIFEST], expect_error=False) + +# 5. dedup + merge, manifest descent_converged true BUT rescan 5 -> FAIL (FF2 contradiction) +case("converged_but_residue_contradiction", + {"structural_summary": MERGE_SS}, + [{"frontier": {"descent_converged": True, "final_rescan_new_groups_above_floor": 5}}], + expect_error=True, marker="final_rescan_new_groups_above_floor is 5") + +# 6. dedup + decimate, waiver recorded -> PASS +case("dedup_decimate_waived", + {"structural_summary": {**DEDUP_SS, "frontier_convergence_waived": True, + "frontier_convergence_waiver_reason": "user time budget"}, + "metrics": INSTANCE_METRIC, "operations": DECIMATE_OP}, + [], expect_error=False) + +# 7. pure lossless dedup, NO phase4 geometry op -> gate does not fire -> PASS +case("dedup_only_no_geometry_op", + {"structural_summary": DEDUP_SS, "metrics": INSTANCE_METRIC, + "operations": [{"order": 2, "name": "internal_share(coarse)", "method": "x", "result": "-27%"}]}, + [], expect_error=False) + +# 8. THE RETROSPECTIVE LOOPHOLE: role=monolith + dedup metrics + merge, no convergence -> FAIL (FF1) +case("monolith_role_but_dedup_metrics_and_merge", + {"structural_summary": MERGE_SS, "metrics": INSTANCE_METRIC, + "preservation": {"allow_merge": True, "rendered_mesh_merged_count": 6803}, + "target_coverage": {"entries": [{"path": "/m", "role": "monolith"}]}}, + [], expect_error=True, marker="descent-convergence gate") + +# 9. ALREADY-INSTANCED DISK PIVOT: prototypes already > 0 at source + a geometry op, +# but NO new instancing this run (instance_count after == before), NO dedup +# op-marker, NO manifest, NO restructure role -> the dedup trigger must NOT fire +# on absolute post-state, so FF1 stays N/A -> PASS (no spurious failure). +case("already_instanced_no_new_dedup_disk_pivot", + {"structural_summary": {"unique_prototype_count": 64, "instance_ratio": 0.42}, + "metrics": [{"name": "instance_count", "before": 126, "after": 126}], + "operations": DECIMATE_OP, + "target_coverage": {"entries": [{"path": "/m", "role": "monolith"}]}}, + [], expect_error=False) + +# --- #186 finding-specific regressions ---------------------------------------- + +# F1 (finding 1): a merge/removeSmallMeshes-only run drops authored prims with NO +# dedup. authored_prim_delta_pct is deeply negative, but there is no reuse_measured, +# no dedup op-marker, no manifest, no restructure role, no instance increase -> +# did_dedup must be False -> the gate must NOT fire (the old oracle copy's bare +# authored_prim_delta_pct < 0 trigger false-failed exactly this run). +case("f1_merge_only_authored_prim_drop_is_not_dedup", + {"structural_summary": {"authored_prim_delta_pct": -18.0, "merge_applied": True}, + "operations": [{"order": 5, "name": "removeSmallMeshes", "method": "0.5mm"}, + {"order": 6, "name": "merge", "method": "Parent Prim", "result": "-6k prims"}], + "target_coverage": {"entries": [{"path": "/m", "role": "monolith"}]}}, + [], expect_error=False) + +# F2 (finding 2): the free-text result "126 instances preserved" and a +# "point-instance aware" method must NOT be read as a dedup op. Only name+method +# are scanned, and the tightened markers exclude bare "instance". No real dedup -> +# did_dedup False -> gate does NOT fire, even with a decimate op present. +case("f2_instances_preserved_prose_is_not_dedup", + {"operations": [ + {"order": 3, "name": "removeUnusedData", "method": "point-instance aware", + "result": "126 instances preserved"}, + {"order": 4, "name": "decimateMeshes", "method": "0.1mm", "result": "faces -55%"}], + "target_coverage": {"entries": [{"path": "/m", "role": "monolith"}]}}, + [], expect_error=False) + +# F3 (finding 3): a real dedup+merge run declaring descent_converged: true but with +# the rescan field OMITTED must fail closed — absent is NOT converged (schema: +# "0 == converged"). The dedup op-marker "deduplicate" + merge_applied make both +# did_dedup and did_phase4_geom True; the missing rescan means no state is +# converged-or-waived -> gate FIRES. +case("f3_absent_rescan_is_not_converged_fail_closed", + {"structural_summary": {"merge_applied": True, "frontier_descent_converged": True}, + "operations": [{"order": 2, "name": "deduplicateHierarchies", "method": "exact"}]}, + [], expect_error=True, marker="descent-convergence gate") + +# F4a (finding 4): dedup+merge with convergence_waived_by_user true but NO reason -> +# not a valid waiver (schema: "Silence is NOT a waiver") -> gate FIRES. +case("f4a_waiver_without_reason_does_not_count", + {"structural_summary": {"merge_applied": True, "frontier_convergence_waived": True}, + "operations": [{"order": 2, "name": "deduplicateHierarchies", "method": "exact"}]}, + [], expect_error=True, marker="descent-convergence gate") + +# F4b (finding 4): the same run WITH a non-empty reason -> valid waiver -> PASS. +case("f4b_waiver_with_reason_passes", + {"structural_summary": {"merge_applied": True, "frontier_convergence_waived": True, + "frontier_convergence_waiver_reason": "user time budget"}, + "operations": [{"order": 2, "name": "deduplicateHierarchies", "method": "exact"}]}, + [], expect_error=False) + + +def _run_pure_function_checks(): + """Direct assertions on the shared dcc pure functions (findings 1-4).""" + failures = 0 + + def check(label, cond): + nonlocal failures + status = "PASS" if cond else "FAIL" + if not cond: + failures += 1 + print(f"[{status}] dcc.{label}") + + # F1: bare authored_prim_delta drop is not dedup. + check("did_dedup F1 merge-only drop is False", + dcc.did_dedup({"structural_summary": {"authored_prim_delta_pct": -18.0}}) is False) + # F2: prose in result / method is not a dedup marker; name+method only. + check("did_dedup F2 'instances preserved' prose is False", + dcc.did_dedup({"operations": [ + {"name": "removeUnusedData", "method": "point-instance aware", + "result": "126 instances preserved"}]}) is False) + # Positive control: an unambiguous dedup op-marker IS dedup. + check("did_dedup deduplicate op-marker is True", + dcc.did_dedup({"operations": [{"name": "deduplicateHierarchies", "method": "exact"}]}) is True) + check("did_dedup reuse_measured is True", + dcc.did_dedup({"structural_summary": {"reuse_measured": True}}) is True) + # F3: absent rescan fails closed; explicit 0 converges. + check("is_converged_or_waived F3 absent rescan is False", + dcc.is_converged_or_waived({"descent_converged": True}) is False) + check("is_converged_or_waived converged with rescan 0 is True", + dcc.is_converged_or_waived( + {"descent_converged": True, "final_rescan_new_groups_above_floor": 0}) is True) + # F4: waiver requires a non-empty reason. + check("is_converged_or_waived F4 reasonless waiver is False", + dcc.is_converged_or_waived({"convergence_waived_by_user": True}) is False) + check("is_converged_or_waived F4 empty-string reason is False", + dcc.is_converged_or_waived( + {"convergence_waived_by_user": True, "convergence_waiver_reason": " "}) is False) + check("is_converged_or_waived waiver with reason is True", + dcc.is_converged_or_waived( + {"convergence_waived_by_user": True, "convergence_waiver_reason": "budget"}) is True) + return failures + + +def run(): + failures = 0 + for name, report, manifests, expect_error, marker in CASES: + errs = V.validate_descent_convergence(report, manifests) + got_error = bool(errs) + ok = got_error == expect_error + if ok and expect_error and marker: + ok = any(marker in e for e in errs) + status = "PASS" if ok else "FAIL" + if not ok: + failures += 1 + print(f"[{status}] {name}: expect_error={expect_error} got={got_error} " + + (f"errs={errs}" if not ok else "")) + pure_failures = _run_pure_function_checks() + total = len(CASES) + 9 # 9 direct dcc checks + passed = total - failures - pure_failures + print(f"\n{passed}/{total} passed") + return 1 if (failures or pure_failures) else 0 + + +if __name__ == "__main__": + raise SystemExit(run()) diff --git a/skills/omniverse-usd-performance-tuning/references/optimization-report/scripts/validate_report.py b/skills/omniverse-usd-performance-tuning/references/optimization-report/scripts/validate_report.py index ce7eb1f8..a00baa22 100644 --- a/skills/omniverse-usd-performance-tuning/references/optimization-report/scripts/validate_report.py +++ b/skills/omniverse-usd-performance-tuning/references/optimization-report/scripts/validate_report.py @@ -30,6 +30,38 @@ report), so a restructure report cannot pass merely because the operator forgot the flag. Monolith/diagnosis runs (no restructure roles) stay manifest-free. +Footprint gate (repack-normalization) +------------------------------------- +When the optional ``footprint`` block is present, the gate checks the +raw -> repack_normalized -> optimized arithmetic is consistent and fails closed +on a repack-as-optimization claim: a raw->optimized saving that is almost +entirely the free crate re-encode (structural shrink ~0 off the +repack-normalized baseline) cannot be presented as the optimization win. + +Preservation gate (axis-A silent-loss) +-------------------------------------- +When the optional ``preservation`` block is present, the gate checks its shape +matches what the run-scoring oracle consumes: +integer ``rendered_mesh_count`` / ``dangling`` and boolean +``distinct_geometry_bytes_preserved`` / ``bounds_preserved``. Whether those +values actually pass (count unchanged, bounds/bytes preserved, dangling 0) is +scored against the asset's oracle, not here. + +Descent-convergence gate (premature-merge / premature-decimate) +--------------------------------------------------------------- +A run that did hierarchy dedup / instancing must not run a Phase-4 geometry op +(decimation, within-prototype merge, primitive-fit, quantization, topology edit) +before the bounded recursive de-duplication descent has CONVERGED. The skill +documents this descent and its convergence as prose plus the manifest fields +``frontier.descent_converged`` / ``frontier.final_rescan_new_groups_above_floor``, +but nothing enforced it. This gate fails closed, keyed on the output +report/manifest (so a hand-authored rewrite is gated the same as a native +``deduplicateHierarchies`` run), unless convergence is recorded in the manifest +frontier block or the report ``structural_summary`` mirror keys +(``frontier_descent_converged`` + ``frontier_final_rescan_new_groups_above_floor`` +== 0), or an explicit ``frontier.convergence_waived_by_user`` is set. It also +rejects the ``descent_converged == true`` with residue-remaining contradiction. + Usage: python3 validate_report.py [--schema ] \\ [--manifest ...] @@ -39,9 +71,17 @@ import argparse import json +import sys from pathlib import Path from typing import Any +# The descent-convergence gate's pure decision functions + constants live in a +# sibling module (they ship together in this scripts dir). Adding our own +# directory to sys.path lets the plain ``import`` work when the validator is run +# as a standalone script rather than a package. +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import descent_convergence_common as dcc # noqa: E402 + DEFAULT_SCHEMA = Path(__file__).resolve().parent / "optimization-report.schema.json" #: A Phase-4 target is "resolved" only with one of these dispositions. ``blocked`` @@ -53,12 +93,19 @@ RESTRUCTURE_TARGET_CLASSES = frozenset( {"prototype", "shared_layer", "loadable_subasset", "assembly_root"} ) +#: Reuse/descent frontier dispositions that SHARE a unit (and therefore make a +#: scene-graph / consolidation claim that must be backed by MEASURED reuse). +SHARED_IDENTITY_DISPOSITIONS = frozenset({"externalize_shared", "internal_share"}) +#: Reuse/descent frontier reduction routes that DESTROY identity — allowed only on weak-identity +#: (anonymous / structural-fallback) units, never on a strong-identity part. +IDENTITY_DESTROYING_ROUTES = frozenset({"point_instance", "merge"}) +#: Identity signals that mark a unit as a real, addressable part (strong identity). +STRONG_IDENTITY_SIGNALS = frozenset({"kind", "naming", "semantic"}) #: Coverage-entry roles that mean "a restructure happened", so a manifest is #: mandatory and reconciliation is not optional. The ``monolith`` role (an -#: optimize-as-is N=1 target) and an empty ledger stay manifest-free. -RESTRUCTURE_ROLES = frozenset( - {"assembly_root", "prototype", "shared_layer", "loadable_subasset"} -) +#: optimize-as-is N=1 target) and an empty ledger stay manifest-free. Shared with +#: the descent-convergence gate (dcc.RESTRUCTURE_ROLES) so the two stay in lockstep. +RESTRUCTURE_ROLES = dcc.RESTRUCTURE_ROLES def _type_ok(instance: Any, type_name: str) -> bool: @@ -123,6 +170,58 @@ def validate_report(report: Any, schema: dict | None = None) -> list[str]: return errors +def _validate_frontier_entry(target: dict, label: str) -> list[str]: + """Enforce the reuse/descent frontier contract on a single phase4_targets[] entry (C3). + + These checks are conditional on the frontier fields being present, so a + minimal (path / target_class / mesh_count) manifest is unaffected. When the + frontier metadata IS authored the contract makes a bad descent FAIL, not + merely be discouraged in prose: + + * a shared (externalize_shared / internal_share) or identity-destroying + (point_instance / merge) entry must carry an ``identity_signal`` (the + queryable boundary basis); + * a shared entry whose frontier landed on anonymous meshes + (``identity_signal == "none"``) fails — the descent crossed from parts into + triangles; + * an identity-destroying ``reduction_route`` on a STRONG-identity unit + (kind / naming / semantic) fails — point_instance / merge are the matrix's + two weak-identity-only rows. + """ + errors: list[str] = [] + disposition = target.get("identity_disposition") + route = target.get("reduction_route") + signal = target.get("identity_signal") + + is_shared = disposition in SHARED_IDENTITY_DISPOSITIONS + is_destroying = route in IDENTITY_DESTROYING_ROUTES + + if (is_shared or is_destroying) and not signal: + errors.append( + f"{label}: identity_signal is required on a shared " + f"({disposition}) or identity-destroying ({route}) entry " + "(the boundary basis must be queryable)" + ) + + if is_shared and signal == "none": + errors.append( + f"{label}: identity_disposition {disposition!r} landed on anonymous " + "meshes (identity_signal 'none') — a shared frontier must land on a " + "named/kind/semantic unit or, at worst, the coarsest repeating subtree " + "(structural_fallback), never anonymous geometry" + ) + + if is_destroying and signal in STRONG_IDENTITY_SIGNALS: + errors.append( + f"{label}: identity-destroying reduction_route {route!r} on a " + f"strong-identity unit (identity_signal {signal!r}) — point_instance / " + "merge are reserved for weak-identity (anonymous / structural_fallback) " + "units; a named/kind/semantic part must stay addressable" + ) + + return errors + + def validate_manifest_structure(manifest: Any) -> list[str]: """Enforce the load-bearing apply-restructure manifest invariants. @@ -161,6 +260,66 @@ def validate_manifest_structure(manifest: Any) -> list[str]: f"{label}: mesh_count must be an integer >= 0 (authoritative " f"default-predicate count), got {mesh_count!r}" ) + errors.extend(_validate_frontier_entry(target, label)) + + # Measured-reuse-before-consolidation (C3): a scene-graph / consolidation win + # may only be reported from MEASURED reuse, never estimated. When any target + # claims a shared disposition (externalize_shared / internal_share), the + # manifest's top-level ``frontier`` block must record reuse_measured: true. + shared_entries = [ + t for t in (targets or []) + if isinstance(t, dict) and t.get("identity_disposition") in SHARED_IDENTITY_DISPOSITIONS + ] + if shared_entries: + frontier = manifest.get("frontier") + if not isinstance(frontier, dict) or frontier.get("reuse_measured") is not True: + errors.append( + "frontier: a shared disposition (externalize_shared/internal_share) is claimed " + "but frontier.reuse_measured is not true — a scene-graph / consolidation win " + "must be backed by MEASURED reuse (distinct vs total units), never estimated. " + "When measured reuse is low, pivot to the disk tier instead of forcing sharing." + ) + + # apply-restructure residual-mesh postcondition (mirrored here for the + # manifest, enforced live in apply-restructure where the USD stage is open). + # When extraction leaves > 0 mesh prims on the assembly root, apply-restructure + # records the authoritative residual count under ``assembly_root`` AND lists the + # same root in ``phase4_targets[]`` as ``target_class: assembly_root``. Fail loud + # if a restructure manifest is written with residual meshes but no such target + # entry: a retained-mesh assembly root must never be silently dropped from Phase 4. + residual = manifest.get("assembly_root") + if isinstance(residual, dict): + residual_count = residual.get("mesh_count") + residual_path = residual.get("path") + if ( + isinstance(residual_count, int) + and not isinstance(residual_count, bool) + and residual_count > 0 + ): + root_entry = next( + ( + t + for t in (targets or []) + if isinstance(t, dict) + and t.get("target_class") == "assembly_root" + and (residual_path is None or t.get("path") == residual_path) + ), + None, + ) + if root_entry is None: + errors.append( + f"assembly_root records residual mesh_count {residual_count} > 0 but no " + "phase4_targets[] entry with target_class 'assembly_root'" + + (f" and path {residual_path}" if residual_path else "") + + " is present (apply-restructure postcondition: a retained-mesh assembly " + "root must be a Phase-4 target, never silently dropped)" + ) + elif root_entry.get("mesh_count") != residual_count: + errors.append( + f"assembly_root residual mesh_count {residual_count} does not match its " + f"phase4_targets[] entry mesh_count {root_entry.get('mesh_count')!r} " + "(both must echo the same authoritative default-predicate count)" + ) return errors @@ -207,6 +366,141 @@ def _manifest_targets(manifests: list[Any]) -> dict[str, int | None]: return planned +#: Arithmetic-consistency tolerance (percentage points) for the footprint split. +_FOOTPRINT_TOLERANCE_PP = 0.6 +#: A structural change smaller than this magnitude (percent) is treated as "no +#: real structural shrink off the repack-normalized baseline" for the +#: repack-as-optimization fail-closed check. +_FOOTPRINT_STRUCTURAL_EPSILON_PCT = 1.0 + + +def _pct_change(before: float, after: float) -> float | None: + if before == 0: + return None + return (after - before) / before * 100.0 + + +def validate_footprint(report: Any) -> list[str]: + """Gate the optional repack-normalized footprint block. + + Returns violation messages (empty == passes or no footprint block). When a + ``footprint`` block is present it must (1) be arithmetically consistent + across raw -> repack_normalized -> optimized, and (2) fail closed if the + only reduction is the free crate re-encode while the structural win off the + repack-normalized baseline is ~0 (repack-as-optimization). A repack — or an + unshared disaggregation — presented as the optimization win is a fail-closed + reporting error per the plan. + """ + errors: list[str] = [] + footprint = report.get("footprint") if isinstance(report, dict) else None + if footprint is None: + return errors + if not isinstance(footprint, dict): + return ["footprint must be an object"] + + raw = footprint.get("raw_input_bytes") + normalized = footprint.get("repack_normalized_baseline_bytes") + optimized = footprint.get("optimized_bytes") + nums = { + "raw_input_bytes": raw, + "repack_normalized_baseline_bytes": normalized, + "optimized_bytes": optimized, + } + for name, value in nums.items(): + if not isinstance(value, (int, float)) or isinstance(value, bool) or value < 0: + errors.append(f"footprint.{name} must be a number >= 0, got {value!r}") + if errors: + return errors + + if footprint.get("scored_against") != "repack_normalized": + errors.append( + "footprint.scored_against must be 'repack_normalized' — the storage " + "dimension and any footprint claim score against the repack-normalized " + "baseline, not the raw input" + ) + + structural_delta = footprint.get("structural_delta_pct") + expected_structural = _pct_change(normalized, optimized) + if isinstance(structural_delta, (int, float)) and not isinstance(structural_delta, bool): + if expected_structural is not None and abs(structural_delta - expected_structural) > _FOOTPRINT_TOLERANCE_PP: + errors.append( + f"footprint.structural_delta_pct ({structural_delta}) does not match " + f"repack_normalized->optimized ({expected_structural:.2f}%) within " + f"{_FOOTPRINT_TOLERANCE_PP}pp" + ) + else: + errors.append("footprint.structural_delta_pct must be a number") + + repack_delta = footprint.get("repack_delta_pct") + if isinstance(repack_delta, (int, float)) and not isinstance(repack_delta, bool): + expected_repack = _pct_change(raw, normalized) + if expected_repack is not None and abs(repack_delta - expected_repack) > _FOOTPRINT_TOLERANCE_PP: + errors.append( + f"footprint.repack_delta_pct ({repack_delta}) does not match " + f"raw->repack_normalized ({expected_repack:.2f}%) within " + f"{_FOOTPRINT_TOLERANCE_PP}pp" + ) + + raw_delta = footprint.get("raw_delta_pct") + if isinstance(raw_delta, (int, float)) and not isinstance(raw_delta, bool): + expected_raw = _pct_change(raw, optimized) + if expected_raw is not None and abs(raw_delta - expected_raw) > _FOOTPRINT_TOLERANCE_PP: + errors.append( + f"footprint.raw_delta_pct ({raw_delta}) does not match " + f"raw->optimized ({expected_raw:.2f}%) within {_FOOTPRINT_TOLERANCE_PP}pp" + ) + + # Repack-as-optimization fail-closed: a raw->optimized saving that is almost + # entirely the free crate re-encode (structural shrink ~0 off the normalized + # baseline) must not be presented as the optimization win. + if ( + isinstance(structural_delta, (int, float)) + and not isinstance(structural_delta, bool) + and structural_delta > -_FOOTPRINT_STRUCTURAL_EPSILON_PCT + ): + observed_raw = raw_delta if isinstance(raw_delta, (int, float)) and not isinstance(raw_delta, bool) else _pct_change(raw, optimized) + if observed_raw is not None and observed_raw < -_FOOTPRINT_STRUCTURAL_EPSILON_PCT: + errors.append( + f"footprint: raw->optimized shows {observed_raw:.2f}% but the structural " + f"reduction off the repack-normalized baseline is only {structural_delta:.2f}% " + "— the saving is the free crate re-encode, not the optimization. Presenting a " + "repack (or an unshared disaggregation) as the optimization win is a " + "fail-closed reporting error." + ) + return errors + + +def validate_preservation(report: Any) -> list[str]: + """Gate the optional axis-A preservation (silent-loss) block. + + Returns violation messages (empty == passes or no preservation block). The + block is optional at the report level, but when present its shape must match + exactly what the run-scoring oracle consumes so the + schema, scorer, and validator agree: an integer ``rendered_mesh_count`` and + ``dangling`` (both >= 0), and boolean ``distinct_geometry_bytes_preserved`` + and ``bounds_preserved``. This is shape-only — whether the values pass the + gate (count unchanged, both bools true, dangling 0) is the scorer's job + against the asset's oracle, not a static check here. + """ + errors: list[str] = [] + pres = report.get("preservation") if isinstance(report, dict) else None + if pres is None: + return errors + if not isinstance(pres, dict): + return ["preservation must be an object"] + for name in ("rendered_mesh_count", "dangling"): + value = pres.get(name) + if isinstance(value, bool) or not isinstance(value, int) or value < 0: + errors.append( + f"preservation.{name} must be an integer >= 0, got {value!r}" + ) + for name in ("distinct_geometry_bytes_preserved", "bounds_preserved"): + value = pres.get(name) + if not isinstance(value, bool): + errors.append(f"preservation.{name} must be a boolean, got {value!r}") + return errors + + def reconcile_target_coverage(report: Any, manifests: list[Any] | None = None) -> list[str]: """Gate the report's Phase-4 target_coverage; reconcile against manifest(s). @@ -236,10 +530,45 @@ def reconcile_target_coverage(report: Any, manifests: list[Any] | None = None) - f"target_coverage entry {path}: skipped_zero_meshes requires " f"mesh_count == 0, got {mesh_count!r} (a non-zero target cannot be skipped)" ) + # No-op-masquerading-as-optimized: an entry that claims the mesh op chain + # ran must have touched at least one mesh when the target has meshes. + optimized_mesh_count = entry.get("optimized_mesh_count") + if ( + disposition == "optimized" + and isinstance(optimized_mesh_count, int) + and not isinstance(optimized_mesh_count, bool) + and optimized_mesh_count == 0 + and isinstance(mesh_count, int) + and not isinstance(mesh_count, bool) + and mesh_count > 0 + ): + errors.append( + f"target_coverage entry {path}: disposition 'optimized' but " + f"optimized_mesh_count is 0 while mesh_count is {mesh_count} > 0 " + "(no-op masquerading as optimized — record the meshes actually touched, " + "or use skipped_user_declined / skipped_zero_meshes)" + ) present_restructure_roles = sorted( {e.get("role") for e in entries} & RESTRUCTURE_ROLES ) + + # Once a restructure exists (a manifest is supplied/recorded OR a restructure + # role appears), 'monolith' is illegal: it is by definition the N=1, no-manifest, + # non-restructured optimize-as-is path. A monolith entry alongside manifest + # provenance or restructure roles is a contradiction, not a valid ledger row. + recorded_manifests = coverage.get("source_manifests") or [] + manifest_context = bool(manifests) or bool(recorded_manifests) + if manifest_context or present_restructure_roles: + for entry in entries: + if entry.get("role") == "monolith": + errors.append( + f"target_coverage entry {entry.get('path', '')}: role 'monolith' " + "is illegal once a restructure exists (a source manifest is present or a " + "restructure role appears in target_coverage). 'monolith' is only the N=1, " + "no-manifest, non-restructured optimize-as-is target." + ) + if present_restructure_roles and not manifests: errors.append( "target_coverage has restructure role(s) " @@ -292,6 +621,98 @@ def reconcile_target_coverage(report: Any, manifests: list[Any] | None = None) - return errors +def _collect_frontier_states(report: Any, manifests: list[Any]) -> list[tuple[str, dict]]: + """Gather ``(source_label, frontier_dict)`` from every manifest ``frontier`` block + and from the report's ``structural_summary`` mirror keys, so convergence can be + read from the manifest OR the report (a manifest-less run carries it in the report).""" + states: list[tuple[str, dict]] = [] + for i, manifest in enumerate(manifests or []): + if isinstance(manifest, dict) and isinstance(manifest.get("frontier"), dict): + states.append((f"manifest[{i}].frontier", manifest["frontier"])) + if isinstance(report, dict): + ss = report.get("structural_summary") + if isinstance(ss, dict): + mirror: dict[str, Any] = {} + if "frontier_descent_converged" in ss: + mirror["descent_converged"] = ss.get("frontier_descent_converged") + if "frontier_final_rescan_new_groups_above_floor" in ss: + mirror["final_rescan_new_groups_above_floor"] = ss.get( + "frontier_final_rescan_new_groups_above_floor" + ) + if ss.get("frontier_convergence_waived"): + mirror["convergence_waived_by_user"] = ss.get("frontier_convergence_waived") + mirror["convergence_waiver_reason"] = ss.get( + "frontier_convergence_waiver_reason" + ) + if mirror: + states.append(("structural_summary", mirror)) + return states + + +def validate_descent_convergence(report: Any, manifests: list[Any] | None = None) -> list[str]: + """Gate: a Phase-4 geometry op must not run on an UNCONVERGED dedup frontier. + + FF1 — if the run did hierarchy dedup / instancing AND ran a Phase-4 geometry op + (decimation, within-prototype merge, primitive-fit, quantization, topology edit), + the manifest ``frontier`` block OR the report ``structural_summary`` mirror must + record ``descent_converged == true`` with a dry terminal re-scan (or an explicit + recorded waiver with a reason). Otherwise the run may have stopped at a coarse + frontier and reduced geometry that further sharing would have collapsed + (premature-merge / premature-decimate inflation). + + The gate keys on THIS-RUN dedup signals: an unambiguous dedup/instancing op + marker, an apply-restructure manifest, an ``instance_count`` increase, a + restructure-role coverage entry, or a measured-reuse flag (see + ``dcc.did_dedup``). It is therefore only as good as those recorded signals: a + run that dedup'd but recorded NONE of them is not detectable here (there is no + absolute post-state that proves dedup happened this run without one of these + signals). It is mechanism-agnostic across the signals it CAN see — a + hand-authored rewrite that records a dedup op-marker / manifest / instance + increase is gated the same as a native ``deduplicateHierarchies`` run. + + FF2 — ``descent_converged == true`` together with + ``final_rescan_new_groups_above_floor > 0`` is the self-contradiction the + apply-restructure manifest schema names but never enforces; fail it. + """ + errors: list[str] = [] + manifests = manifests or [] + states = _collect_frontier_states(report, manifests) + + # FF2 — converged-but-residue contradiction (independent of Phase-4 ops) + for label, frontier in states: + rescan = frontier.get("final_rescan_new_groups_above_floor") + if ( + frontier.get("descent_converged") is True + and isinstance(rescan, int) + and not isinstance(rescan, bool) + and rescan > 0 + ): + errors.append( + f"{label}: descent_converged is true but " + f"final_rescan_new_groups_above_floor is {rescan} (> 0) — a converged " + "frontier must have a dry terminal re-scan; this contradiction means the " + "descent was declared complete while shareable reuse remained one level down" + ) + + # FF1 — geometry op ran on a dedup/instancing run with no recorded convergence + if dcc.did_dedup(report, manifests) and dcc.did_phase4_geom(report): + if not any(dcc.is_converged_or_waived(frontier) for _, frontier in states): + errors.append( + "descent-convergence gate: a Phase-4 geometry op (decimation / " + "within-prototype merge / primitive-fit / quantization / topology edit) " + "ran on a dedup/instancing run, but no converged de-duplication frontier " + "is recorded (no frontier.descent_converged == true with a dry terminal " + "re-scan, and no recorded waiver). Record convergence in the " + "apply-restructure manifest frontier block, or in report.structural_summary " + "(frontier_descent_converged + frontier_final_rescan_new_groups_above_floor " + "== 0), or set an explicit frontier.convergence_waived_by_user with a reason. " + "A low/coarse prototype count is the SIGNAL TO DESCEND, not to merge: " + "running geometry ops first fuses or coarsens geometry that further sharing " + "would have collapsed (premature-merge inflation)." + ) + return errors + + def main() -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("report", type=Path, help="Path to the report JSON to validate.") @@ -324,6 +745,9 @@ def main() -> int: manifests = [manifest for _, manifest in labeled] errors.extend(reconcile_target_coverage(report, manifests)) + errors.extend(validate_footprint(report)) + errors.extend(validate_preservation(report)) + errors.extend(validate_descent_convergence(report, manifests)) if errors: print(f"{args.report}: INVALID ({len(errors)} error(s))") diff --git a/skills/omniverse-usd-performance-tuning/references/output-workspace.md b/skills/omniverse-usd-performance-tuning/references/output-workspace.md index 425d920c..90d2a6d3 100644 --- a/skills/omniverse-usd-performance-tuning/references/output-workspace.md +++ b/skills/omniverse-usd-performance-tuning/references/output-workspace.md @@ -7,8 +7,6 @@ agent_next: freshness: 2026-05-20 version: "0.1.0" --- - - # Output Workspace Contract @@ -36,7 +34,7 @@ artifacts under the skill repo or the shell working directory. ``` `setup-preflight.json` is the canonical session-scoped runtime configuration. -The setup, validation, Scene Optimizer, compare, and report references all read +The setup, validation, Usd Optimize, compare, and report references all read this exact filename from this exact location. ## Runtime Gate @@ -53,8 +51,8 @@ probe. Kit application: {runtime_context.kit.application} {runtime_context.kit.version} path: {runtime_context.kit.path} build: {runtime_context.kit.build} -Scene Optimizer: {runtime_context.sceneOptimizer.extension} {runtime_context.sceneOptimizer.version} -Asset Validator: {runtime_context.assetValidator.package} {runtime_context.assetValidator.version} via {runtime_context.assetValidator.source} +Usd Optimize: {runtime_context.usdOptimize.extension} {runtime_context.usdOptimize.version} +usd-validation-nvidia: {runtime_context.assetValidator.package} {runtime_context.assetValidator.version} via {runtime_context.assetValidator.source} ─────────────────────────────────────────────────────────────────────────── ``` diff --git a/skills/omniverse-usd-performance-tuning/references/profile-stage/README.md b/skills/omniverse-usd-performance-tuning/references/profile-stage/README.md index fada6985..6d5e1cb5 100644 --- a/skills/omniverse-usd-performance-tuning/references/profile-stage/README.md +++ b/skills/omniverse-usd-performance-tuning/references/profile-stage/README.md @@ -1,19 +1,12 @@ # Profile Stage - - - ## When to Use Use when profiling a USD stage before/after optimization; do not use to interpret regressions alone. ## Instructions -1. Confirm the target asset, artifact, or user intent and check the prerequisites listed below. -2. Read only the referenced files needed for the current phase, failure mode, or output contract. -3. Follow the workflow, rules, and safety gates in this reference before invoking downstream references or shell commands. -4. Return the result using the Output Format section and name any blocked prerequisite or unresolved user decision. - +See `references/_shared/standard-instructions.md`. ## Pre-flight Checklist @@ -27,7 +20,7 @@ Before running profile measurements, re-read and confirm: - [ ] For full mode: multi-sample warm protocol (discard first, average rest). ## Output Format -Return a concise status or report that names the input, selected runtime or evidence source, actions planned or performed, artifacts written, blockers, and the next validation or user-decision step. When a schema or template is referenced below, conform to that contract. +See `references/_shared/standard-output-format.md`. Use this reference to capture measurable performance data. Run it **before** optimization to establish a baseline, and **after** to verify improvement. @@ -205,8 +198,10 @@ post-optimization warm open as a verdict. before comparing it to the baseline. Do not compare a first after-write open to a warmed baseline. - If warm samples are noisy (for example, max-min exceeds 15% of median) or the - before/after delta is within the measured spread, mark warm-load evidence as - inconclusive in `compare-profiles` rather than a regression. + before/after delta is within the measured spread, the warm-load evidence is + inconclusive: in `compare-profiles` classify that row's verdict as `neutral` + (the verdict enum has no `inconclusive` value) and record the inconclusive + timing context in the notes, rather than reporting a regression. ## Full Mode (Kit runtime, requires Isaac Sim + GPU) @@ -223,7 +218,7 @@ quick mode plus: ### Prerequisites - Isaac Sim or Kit SDK with RTX renderer. -- Kit `omni.kit.profiler.tracy` profiler extension (Tracy is a Kit profiler, not a Scene Optimizer component). +- Kit `omni.kit.profiler.tracy` profiler extension (Tracy is a Kit profiler, not a Usd Optimize component). - GPU with display (headless with virtual display works). ### Usage @@ -278,7 +273,6 @@ and `NVIDIA/omniperf/.agents/skills/nsys-analyze/SKILL.md`. } ``` - ## Full mode: startup vs runtime separation When capturing Tracy data, separate the zone report into two sections: @@ -320,7 +314,7 @@ This separation enables `compare-profiles` to correctly classify tradeoffs ## What quick mode can and cannot prove (standalone-path caveat) Quick mode is the only available mode when the Phase 0 runtime is -standalone Scene Optimizer (no Kit). The agent must be explicit in the +standalone Usd Optimize (no Kit). The agent must be explicit in the final `optimization-report` about which claims quick-mode metrics support and which they do not. @@ -366,4 +360,5 @@ unavailable)" and §"Quick-mode-only caveat" for the report wording. - If `pxr` imports fail, run setup to choose a Kit or standalone USD Python runtime. - If full mode cannot load Tracy, verify `omni.kit.profiler.tracy` is enabled in the selected Kit runtime. - If warm-open samples vary widely, rerun the protocol in fresh processes; if - variance persists, mark warm-load evidence inconclusive. + variance persists, treat warm-load evidence as inconclusive (verdict row + `neutral` + inconclusive context in notes). diff --git a/skills/omniverse-usd-performance-tuning/references/report-templates/README.md b/skills/omniverse-usd-performance-tuning/references/report-templates/README.md index 8ad08eed..c9629aa1 100644 --- a/skills/omniverse-usd-performance-tuning/references/report-templates/README.md +++ b/skills/omniverse-usd-performance-tuning/references/report-templates/README.md @@ -1,6 +1,3 @@ - - - # USD Performance Tuning Report Templates These templates are the design surface for `optimization-report`. diff --git a/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.design-fixture.json b/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.design-fixture.json index 449580f2..603e0b7e 100644 --- a/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.design-fixture.json +++ b/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.design-fixture.json @@ -16,6 +16,13 @@ "sample_count": 5, "score_scope": "stage/composition metrics only" }, + "preservation": { + "rendered_mesh_count": 2252, + "distinct_geometry_bytes_preserved": true, + "bounds_preserved": true, + "dangling": 0, + "notes": "Axis-A silent-loss gate: rendered-mesh count, distinct geometry bytes, world bounds, and binding integrity all preserved across the instanceable-reference conversion." + }, "runtime_profiling": { "status": "not_run", "recommended_tool": "Omniperf", @@ -151,7 +158,7 @@ { "order": 2, "name": "computeExtents", - "method": "Scene Optimizer safe-cleanup pipeline", + "method": "Usd Optimize safe-cleanup pipeline", "result": "Authored extents for renderer culling." } ], @@ -175,6 +182,7 @@ "path": "/tmp/factory/prototypes/rack_unit.usd", "role": "prototype", "mesh_count": 412, + "optimized_mesh_count": 412, "disposition": "optimized", "operations": ["meshCleanup", "fitPrimitives", "deduplicateGeometry", "decimateMeshes", "optimizeMaterials", "computeExtents"] }, @@ -182,6 +190,7 @@ "path": "/tmp/factory/factory.optimized.usdc", "role": "assembly_root", "mesh_count": 1840, + "optimized_mesh_count": 1792, "disposition": "optimized", "operations": ["meshCleanup", "fitPrimitives", "deduplicateGeometry", "decimateMeshes", "optimizeMaterials", "computeExtents"], "notes": "Assembly-root remainder (meshes left after extraction) processed through the per-target op chain, not left to stage-level cleanup." diff --git a/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.design-fixture.manifest.json b/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.design-fixture.manifest.json index 9bf0604f..42f59e4f 100644 --- a/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.design-fixture.manifest.json +++ b/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.design-fixture.manifest.json @@ -3,6 +3,15 @@ "input_stage": "/tmp/factory.usd", "output_dir": "/tmp/factory", "new_assembly_root": "/tmp/factory/factory.optimized.usdc", + "assembly_root": { + "path": "/tmp/factory/factory.optimized.usdc", + "mesh_count": 1840 + }, + "frontier": { + "reuse_measured": true, + "descent_converged": true, + "final_rescan_new_groups_above_floor": 0 + }, "phase4_targets": [ { "path": "/tmp/factory/prototypes/rack_unit.usd", diff --git a/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.html.template b/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.html.template index 5d2fb95e..a810ec7e 100644 --- a/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.html.template +++ b/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.html.template @@ -1,5 +1,3 @@ - - @@ -179,6 +177,11 @@ {% endfor %} + {% if notes %} +

Notes

+
{{ notes }}
+ {% endif %} +

Stage Impact Areas

{% for group in metric_groups %} @@ -246,6 +249,22 @@ + {% if footprint %} +

Storage Footprint (repack-normalized)

+
+ A USDC/crate repack is the free re-encode any export achieves, not the optimization. The structural win is measured against the repack-normalized baseline, never the raw input. +
+ + + + + + + + +
Raw input{{ footprint.raw_input_bytes }} bytes
Repack-normalized baseline{{ footprint.repack_normalized_baseline_bytes }} bytes ({{ footprint.repack_delta_pct }}% re-encode, free)
Optimized{{ footprint.optimized_bytes }} bytes
Structural win (vs normalized baseline){{ footprint.structural_delta_pct }}%
Total raw → optimized{{ footprint.raw_delta_pct }}%
+ {% endif %} +

Operations

diff --git a/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.md.template b/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.md.template index 133155d9..75fbab1a 100644 --- a/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.md.template +++ b/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.md.template @@ -1,6 +1,3 @@ - - - # USD Performance Tuning Report - {{ asset_name }} **Stage Optimization Score:** {{ optimization_score }}/10 ({{ score_label }}) @@ -14,6 +11,12 @@ {{ reasoning }} +{% if notes %} +## Notes + +{{ notes }} +{% endif %} + {% if runtime_context %} ## Runtime Context @@ -22,8 +25,8 @@ | Kit application | {{ runtime_context.kit.application }} {{ runtime_context.kit.version }} | | Kit path | {{ runtime_context.kit.path }} | | Kit build | {{ runtime_context.kit.build }} | -| Scene Optimizer | {{ runtime_context.sceneOptimizer.extension }} {{ runtime_context.sceneOptimizer.version }} | -| Asset Validator | {{ runtime_context.assetValidator.package }} {{ runtime_context.assetValidator.version }} (via {{ runtime_context.assetValidator.source }}) | +| Usd Optimize | {{ runtime_context.usdOptimize.extension }} {{ runtime_context.usdOptimize.version }} | +| usd-validation-nvidia | {{ runtime_context.assetValidator.package }} {{ runtime_context.assetValidator.version }} (via {{ runtime_context.assetValidator.source }}) | {% endif %} ## Stage Impact Areas @@ -56,6 +59,22 @@ | {{ metric.display_name }} | {{ metric.before }} {{ metric.unit }} | {{ metric.after }} {{ metric.unit }} | {{ metric.change_pct }}% | {{ metric.evidence_type }} | {{ metric.verdict }} | {% endfor %} +{% if footprint %} +## Storage Footprint (repack-normalized) + +A USDC/crate repack is the free re-encode any export achieves, not the +optimization. The structural win is measured against the repack-normalized +baseline, never the raw input. + +| Footprint | Value | +|---|---:| +| Raw input | {{ footprint.raw_input_bytes }} bytes | +| Repack-normalized baseline | {{ footprint.repack_normalized_baseline_bytes }} bytes ({{ footprint.repack_delta_pct }}% re-encode, free) | +| Optimized | {{ footprint.optimized_bytes }} bytes | +| Structural win (vs normalized baseline) | {{ footprint.structural_delta_pct }}% | +| Total raw → optimized | {{ footprint.raw_delta_pct }}% | +{% endif %} + ## Operations | # | Operation | Method | Result | diff --git a/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.structural-only-fixture.json b/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.structural-only-fixture.json index ba39d5f0..04269016 100644 --- a/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.structural-only-fixture.json +++ b/skills/omniverse-usd-performance-tuning/references/report-templates/optimization-report.structural-only-fixture.json @@ -5,14 +5,14 @@ "timestamp": "2026-05-28T00:00:00Z", "verdict": "neutral", "workflow_mode": "structural_only", - "notes": "Scene Optimizer was unavailable in the selected runtime and the user declined install, so the workflow ran in structural-only mode: structure assessment plus pre-mutation USD validation only. No mesh operations executed and no optimized stage was written, so the verdict is neutral. FPS, frame time, and VRAM are unmeasured; re-run Phase 1a/6a in full mode under Kit / USD Composer / Isaac Sim to graduate the verdict.", + "notes": "Usd Optimize was unavailable in the selected runtime and the user declined install, so the workflow ran in structural-only mode: structure assessment plus pre-mutation USD validation only. No mesh operations executed and no optimized stage was written, so the verdict is neutral. FPS, frame time, and VRAM are unmeasured; re-run Phase 1a/6a in full mode under Kit / USD Composer / Isaac Sim to graduate the verdict.", "optimization_score": 5.0, "score_scope": "stage_optimization", "score_label": "neutral", - "reasoning": "Scene Optimizer could not be loaded, so no mutation was attempted. Structure assessment characterized the stage and pre-mutation USD validation ran, but without SO there is no optimized output to compare against the baseline. The score reflects a neutral, no-change result rather than a measured optimization win.\n\nThe report documents the runtime blocker and the next capture needed so a later full-mode run can produce a real before/after verdict.", + "reasoning": "Usd Optimize could not be loaded, so no mutation was attempted. Structure assessment characterized the stage and pre-mutation USD validation ran, but without Usd Optimize there is no optimized output to compare against the baseline. The score reflects a neutral, no-change result rather than a measured optimization win.\n\nThe report documents the runtime blocker and the next capture needed so a later full-mode run can produce a real before/after verdict.", "measurement_context": { "profile_mode": "quick USD composition profile", - "runtime": "standalone USD Python (no Scene Optimizer)", + "runtime": "standalone USD Python (no Usd Optimize)", "score_scope": "stage/composition metrics only" }, "runtime_profiling": { @@ -43,7 +43,7 @@ "score": 5.0, "status": "measured", "weight": 50, - "summary": "Pre-mutation USD validation ran; SO performance rules skipped (SO unavailable)." + "summary": "Pre-mutation USD validation ran; SO performance rules skipped (Usd Optimize unavailable)." } ], "metrics": [ diff --git a/skills/omniverse-usd-performance-tuning/references/runtime-artifact-token-budget.md b/skills/omniverse-usd-performance-tuning/references/runtime-artifact-token-budget.md index 9c5a7840..d7a92525 100644 --- a/skills/omniverse-usd-performance-tuning/references/runtime-artifact-token-budget.md +++ b/skills/omniverse-usd-performance-tuning/references/runtime-artifact-token-budget.md @@ -1,9 +1,6 @@ - - - # Runtime Artifact Token Budget -Use this policy whenever a skill launches Kit, Asset Validator, Scene Optimizer, +Use this policy whenever a skill launches Kit, usd-validation-nvidia, Usd Optimize, Tracy, or any helper wrapper that can produce large stdout, stderr, logs, CSVs, or traces. @@ -15,8 +12,8 @@ logs or issue dumps into the agent context. High-risk artifacts include: - Kit launch stdout/stderr and extension startup logs. -- Asset Validator CSVs with one row per issue. -- Scene Optimizer `run.log`, verbose operation logs, and analysis payloads. +- usd-validation-nvidia CSVs with one row per issue. +- Usd Optimize `run.log`, verbose operation logs, and analysis payloads. - Tracy CSV exports, `.tracy` captures, and frame/zone dumps. - Any file that may contain thousands of rows, repeated prim paths, or stack traces. @@ -81,7 +78,7 @@ operation parameters). ### Scope Applies to: -- Scene Optimizer CLI / `run.py` invocations +- Usd Optimize CLI / `run.py` invocations - Kit / `kit --exec` script launches - Standalone `python -m` USD processing scripts - Any subprocess where `from pxr import ...` is in play diff --git a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/README.md b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/README.md index 57526138..f92ca789 100644 --- a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/README.md +++ b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/README.md @@ -1,19 +1,18 @@ # Setup USD Performance Tuning - - - ## When to Use -Use this reference when runtime availability is unknown or the user explicitly asks to set up, verify, switch, or install the Kit, Scene Optimizer, or Asset Validator path. +Minimum supported runtime: usd-optimize 1.0.x (GitHub release packages) with +the usd-validation-nvidia pip package. + +Use this reference when standalone runtime availability is unknown or the user explicitly asks to set up, verify, or install the standalone Usd Optimize / usd-validation-nvidia path (or to set up the opt-in Kit→omniperf profiling adjunct). ## Instructions 1. Check for an existing `setup-preflight.json` and verify whether it matches the current target and runtime intent. -2. Probe available Kit, Scene Optimizer, Asset Validator, and standalone USD Python paths without silently choosing between viable alternatives. -3. Ask the user before installing or switching runtimes when no verified path satisfies the request. -4. Write or refresh the preflight artifact with runtime versions, paths, and available Scene Optimizer operations. - +2. Probe the standalone Usd Optimize, usd-validation-nvidia, and USD Python paths (plus any opt-in Kit profiling root) without silently choosing between viable alternatives. +3. Ask the user before installing the standalone runtime when no verified path satisfies the request. +4. Write or refresh the preflight artifact with runtime versions, paths, and available Usd Optimize operations. ## Pre-flight Checklist @@ -25,7 +24,7 @@ Before executing setup/preflight, re-read and confirm: - [ ] Write `setup-preflight.json` conforming to `scripts/setup-preflight.schema.json`. ## Output Format -Return the selected runtime route, any user decision needed, and the path to `setup-preflight.json`. The preflight artifact records Kit, Scene Optimizer, Asset Validator, USD Python, and `operationsAvailable` evidence. +Return the selected runtime route, any user decision needed, and the path to `setup-preflight.json`. The preflight artifact records Kit, Usd Optimize, usd-validation-nvidia, USD Python, and `operationsAvailable` evidence. Use this reference before running validation, profiling, or optimization from this skill package in a fresh environment. The goal is to choose and verify one @@ -35,7 +34,7 @@ runtime path before invoking the workflow skills. This reference is the **named entry skill** in an agent's response only when no runtime path is verified at all — that is, when the setup probe reports every -candidate (Kit, standalone Scene Optimizer, standalone Asset Validator) as +candidate (Kit, standalone Usd Optimize, standalone usd-validation-nvidia) as unavailable, missing, or unverified. In that case there is no way to route performance work, so resolving the runtime is the agent's first responsibility. @@ -56,8 +55,16 @@ normal phase order regardless. ## Purpose -Identify and verify a single Kit or standalone runtime path for profiling, -validation, and Scene Optimizer execution before downstream references run. +Verify the **standalone** runtime — the sole runtime for Usd Optimize +execution and usd-validation-nvidia validation — before downstream references run. +Kit is not an alternate optimization/validation runtime; it is retained only as +an explicit opt-in render-profiling adjunct (Kit→omniperf), set up on request. + +Phase 0 **guarantees an importable `pxr` (USD Python)** as a precondition for the +pipeline: every standalone route lands `pxr` (Kit and SO standalone provide it +directly; a validator-only standalone venv installs `usd-core`). After Phase 0 +completes on any route, `import pxr` succeeds — downstream phases that author USD +(e.g. `apply-restructure`) can rely on it. ## Prerequisites @@ -68,7 +75,7 @@ validation, and Scene Optimizer execution before downstream references run. ## Examples - "Set up this repo before I run validation." -- "Check whether my Kit path can run Scene Optimizer and Asset Validator." +- "Check whether my Kit path can run Usd Optimize and usd-validation-nvidia." ## Runtime choices @@ -84,27 +91,30 @@ for rule discovery — just ensure both are importable. Selected runs go through scope-note **canonical concept** to a rule class by identity. > Standalone achieves the same validator coverage as Kit: install -> `omniverse-asset-validator` via pip into the same venv where the SO package -> is on PYTHONPATH, and the `@register_rule` decorators register SO validators +> `omniverse-asset-validator` via pip into the same venv where the Usd Optimize package +> is on PYTHONPATH, and the `@register_rule` decorators register Usd Optimize validators > at import time. -Fall back to Kit (USD Composer, Isaac Sim, or Kit SDK) when standalone packages -are not available or the user explicitly requests it. Kit runs OAV and SO in -one runtime and additionally supports render-time profiling. When taking the -Kit path, validation must use `omni.asset_validator.core` from that same Kit -runtime. Do not require `uv` or `omni_asset_validate` on `PATH` for the Kit -path. +Standalone is the only runtime for optimization and validation; there is no Kit +optimization fallback. Kit (USD Composer, Isaac Sim, or Kit SDK) is retained +**only as an opt-in render-time profiling adjunct** — the one way to capture the +FPS / Hydra / RTX / VRAM / draw-call metrics required before claiming +runtime wins. That profiling path is delegated to the external `NVIDIA/omniperf` +skills; set it up only when the user explicitly asks for render-time profiling. +Kit is never auto-selected as a silent fallback for SO/AV work. ## Requirement-to-skill map -- Existing Kit or USD Composer runtime: verify in this reference; do not install. -- Missing Kit runtime: invoke `install-kit`. -- Scene Optimizer inside Kit: invoke `install-so-via-kit` when missing. -- Standalone Scene Optimizer operations: invoke `install-so-standalone` when - the extracted `scene_optimizer_core_...release.zip` package is missing. -- Standalone Omni Asset Validator: invoke `install-asset-validator-standalone` - when missing. SO validators auto-register when both packages share the same +- Standalone Usd Optimize operations: invoke `install-usd-optimize-standalone` when + the extracted prebuilt Usd Optimize package is missing + (asset name + download: `references/upstreams/usd-optimize.md`). +- Standalone Omni usd-validation-nvidia: invoke `install-usd-validation-nvidia-standalone` + when missing. Usd Optimize validators auto-register when both packages share the same Python environment. +- Opt-in render profiling only: an existing/ user-supplied Kit or USD Composer + runtime is verified for the Kit→omniperf profiling adjunct (`install-kit` / + `install-usd-optimize-standalone` are profiling-setup helpers, not a default optimization + fallback). Do not install Kit just to run SO/AV work. ## Output workspace contract @@ -116,6 +126,9 @@ Everything this reference writes goes under the user's `output_path` (see it under any other filename or location** (no `probe_result.json`, no `_work/`, no temp dirs). Downstream skills check this exact path; a different name leaves the session-start gate broken. + Include `cuda_available` when probed; the Phase-4 batch scheduler treats `false` + as a hard signal not to run `gpu_bound` operations through slow CPU fallback, + and treats `null`/missing as unknown (fail closed to CPU-only). - `/scripts/probe_setup.py` — the generated Python probe driven through Step 3. - `/scripts/probe_setup.log` and @@ -135,7 +148,7 @@ to the working directory. The agent performs setup checks directly from the current shell. Do not rely on repo-local setup scripts or ask the user to run scripts. -Check for standalone Scene Optimizer and Asset Validator packages first — +Check for standalone Usd Optimize and usd-validation-nvidia packages first — they are the preferred runtime (lighter, no Kit overhead, deterministic). Follow `references/standalone-runtime.md` for discovery and verification. @@ -143,52 +156,56 @@ If standalone packages are found and importable, set `runtime_route: "standalone"` in `/setup-preflight.json` and continue to Step 1.6. -If standalone packages are not found, fall through to Step 1.5 (Kit discovery). +If standalone packages are not found, this is a runtime block: surface the +missing-SO/AV install path (`install-usd-optimize-standalone` / +`install-usd-validation-nvidia-standalone`). Do not fall back to Kit for optimization +or validation — Kit is not an SO/AV runtime here. -## Step 1.5 - Determine Kit candidates (fallback) +## Step 1.5 - Opt-in Kit profiling discovery -If standalone is unavailable, look for Kit installations. Follow +Only when the user explicitly asks for render-time profiling, look for a Kit +installation to drive the Kit→omniperf profiling adjunct. Follow `references/kit-discovery.md` for discovery order, path classification, auto-enumeration, and candidate records. -Always ask before broad filesystem scanning. If one Kit candidate exists, write -it to `runtime_context.kit` and continue. If multiple candidates exist, ask the -user to choose; never silently pick one in an interactive session. The newest -candidate is pre-selected. +Always ask before broad filesystem scanning. Prefer a user-supplied Kit / +USD Composer / Isaac Sim path; if exactly one candidate is discovered, write it +to `runtime_context.kit`. If multiple candidates exist, ask the user to choose; +never silently pick one. This path is for profiling only — it never becomes the +optimization/validation runtime. Record the chosen candidate and `runtime_context.kit.chosen_by` as described in `references/kit-discovery.md`. -## Step 1.6 - Probe the chosen Kit for SO and AV versions +## Step 1.6 - Probe the runtime for SO and AV versions -Once `runtime_context.kit` is set (or standalone is chosen), run the Python -probe from the chosen launcher and write the probe result to +Once the standalone runtime is confirmed (or an opt-in Kit profiling root is +set), run the Python probe and write the probe result to `/setup-preflight.json`. Follow `references/runtime-probe.md` for the launcher, import-mode, version-source, and `operationsAvailable` contract. The `runtime_context` object is the literal input to the header template in `references/runtime-context-header.md`. Downstream skills read from this object, -not from the raw probe `kit` / `sceneOptimizer` / `assetValidator` source +not from the raw probe `kit` / `usdOptimize` / `assetValidator` source fields. -Downstream skills (`so-run-operations`, `omniverse-usd-performance-tuning`, every -`so-interpret-validators` recommendation) cross-check `operationsAvailable` +Downstream skills (`usd-optimize-run-operations`, `omniverse-usd-performance-tuning`, every +`usd-optimize-interpret-validators` recommendation) cross-check `operationsAvailable` against the op key they intend to invoke and refuse to call any op the runtime does not register. ## Step 2 - Interpret status -- `ready-standalone`: use standalone Scene Optimizer for operations and Omni Asset Validator from Python. -- `ready-kit`: use Kit for Scene Optimizer and `omni.asset_validator.core` validation from the same Kit runtime. -- `needs-runtime-choice`: stop and ask the user for a decision. - -When status is `needs-runtime-choice`, ask exactly for one of these paths: +- `ready-standalone`: use standalone Usd Optimize for operations and Omni usd-validation-nvidia from Python. This is the optimization+validation runtime. +- `ready-profiling-kit`: an opt-in Kit→omniperf profiling root is available **in addition to** standalone; it is used only for render-time profiling, never for SO/AV work. +- `needs-runtime-choice`: standalone SO/AV is not importable — stop and ask the user to supply the standalone package path or a pip-installable environment. -- Provide the path to standalone SO / AV packages or a pip-installable environment. -- Provide the path to an existing Kit or USD Composer install. +When status is `needs-runtime-choice`, ask for the standalone SO / AV package +path or a pip-installable environment. (A Kit path does not resolve this; Kit is +not an SO/AV runtime.) -Do not continue to `so-run-validators`, `so-run-operations`, or deep validation -until this choice is resolved. +Do not continue to `usd-optimize-run-validators`, `usd-optimize-run-operations`, or deep validation +until standalone SO/AV is resolved. ## Non-interactive (batch / CI) mode @@ -199,17 +216,16 @@ agent must then proceed without blocking: - If `output_path`, a runtime preference, and any required candidate paths are all supplied, do not prompt. -- When the preference is `auto`, resolve the runtime by deterministic policy: - 1. Standalone Scene Optimizer + Asset Validator, if importable. - 2. A user-supplied Kit / USD Composer / Isaac Sim path. - 3. The newest auto-discovered Kit — only when a broad filesystem scan was - explicitly authorized for this run. -- Record `runtime_context.kit.chosen_by: auto_policy` (or - `standalone_preferred`) in `setup-preflight.json` so downstream skills and the - report can show the runtime was selected unattended rather than confirmed by a - human. -- If no runtime resolves under this policy, stop with `needs-runtime-choice` and - name the missing inputs — do not guess a runtime or scan without permission. +- When the preference is `auto`, resolve the optimization runtime + deterministically: standalone Usd Optimize + usd-validation-nvidia, if importable. + There is no Kit optimization fallback in the policy. A user-supplied Kit path + is recorded only as the opt-in profiling adjunct, never as the SO/AV runtime. +- Record `runtime_context.chosen_by: standalone_preferred` in + `setup-preflight.json` so downstream skills and the report can show the runtime + was selected unattended rather than confirmed by a human. +- If standalone does not resolve under this policy, stop with + `needs-runtime-choice` and name the missing standalone inputs — do not guess a + runtime, fall back to Kit, or scan without permission. ## Step 3 - Verify standalone path @@ -220,7 +236,7 @@ and handoff rules. ## Step 4 - Verify Kit path (fallback) -For a Kit root (Step 1.5), verify Scene Optimizer and Omni Asset Validator core +For a Kit root (Step 1.5), verify Usd Optimize and Omni usd-validation-nvidia core both load, and capture the runtime versions that Step 1.6 surfaces to the user. Use `references/runtime-probe.md` for the exact launcher, import, version, and log discipline. @@ -236,7 +252,7 @@ After setup: 1. `omniverse-usd-performance-tuning` for broad performance requests. 2. `usd-structure-assessment` before choosing optimizations. 3. `usd-validation-runner` for validation; its references own the specific `validate-*` command details. -4. `so-run-validators`, `so-interpret-validators`, and `so-run-operations` only after runtime setup is ready. +4. `usd-optimize-run-validators`, `usd-optimize-interpret-validators`, and `usd-optimize-run-operations` only after runtime setup is ready. Record the chosen runtime path in the response so later commands use the same Kit or standalone environment. @@ -252,7 +268,7 @@ downstream references consume it from that exact path. The header has two formats: - **Format A (full block)** — required at this reference's runtime-choice prompt, - at the `restructure-decision` Phase 2e prompt, at the `so-run-operations` + at the `restructure-decision` Phase 2e prompt, at the `usd-optimize-run-operations` destructive-op confirmation, and at the first user-facing message of any session that starts mid-workflow. - **Format B (compact one-liner)** — used for routine status messages and @@ -261,15 +277,15 @@ The header has two formats: When `runtime_context.kit` is set (single candidate or user has picked), print Format A once as the conclusion of this reference's interaction with the user, before the agent hands off to `omniverse-usd-performance-tuning`. The user must see exactly which Kit -application, Scene Optimizer, and Asset Validator version will be in effect +application, Usd Optimize, and usd-validation-nvidia version will be in effect for the rest of the session. ## Limitations - Does not install unless a dedicated install reference is invoked. - Does not choose optimization operations or validator scope. -- Standalone SO validators auto-register via `@register_rule` decorators when - both `omniverse-asset-validator` and the SO package are importable in the +- Standalone Usd Optimize validators auto-register via `@register_rule` decorators when + both `omniverse-asset-validator` and the Usd Optimize package are importable in the same Python 3.12 environment. Kit auto-registers them via its extension session. @@ -277,5 +293,5 @@ for the rest of the session. - If standalone packages are found but the probe fails (import error, version mismatch), fall through to Kit discovery. - If multiple valid Kit installs are found, ask the user to choose or record the newest unattended choice. -- If the Kit probe cannot import Scene Optimizer or Asset Validator, try another Kit path. +- If the Kit probe cannot import Usd Optimize or usd-validation-nvidia, try another Kit path. - If standalone paths are incomplete, invoke the relevant install reference instead of reusing a bundled validator environment. diff --git a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-kit/README.md b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-kit/README.md index f78b5508..914bedd5 100644 --- a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-kit/README.md +++ b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-kit/README.md @@ -1,72 +1,16 @@ -# Install Kit +# Install Kit (pointer) - - +Kit is not an optimization or validation runtime for this skill — it survives +only as the opt-in render-profiling adjunct (Kit -> omniperf). This package +does not maintain Kit install instructions; follow the external docs: -## When to Use +- Kit SDK / app installs: https://docs.omniverse.nvidia.com/kit/docs/ +- Render profiling skills (FPS / VRAM / frame time): NVIDIA/omniperf -Use when Python 3.12 Kit is needed for validators, profilers, or SO via Kit. +If a Kit profiling session is used, follow +`references/runtime-artifact-token-budget.md` before reading Kit logs or +Tracy output. -## Instructions - -1. Confirm the target asset, artifact, or user intent and check the prerequisites listed below. -2. Read only the referenced files needed for the current phase, failure mode, or output contract. -3. Follow the workflow, rules, and safety gates in this reference before invoking downstream references or shell commands. -4. Return the result using the Output Format section and name any blocked prerequisite or unresolved user decision. - -## Output Format - -Return a concise status or report that names the input, selected runtime or evidence source, actions planned or performed, artifacts written, blockers, and the next validation or user-decision step. When a schema or template is referenced below, conform to that contract. - -## Purpose - -Install Omniverse Kit as a Python package via pip so skills can import -`omni.kit_app` and start a headless Kit runtime. - -Do not use this reference for full Isaac Sim, Omniverse Launcher, or desktop app -installs. - -## Prerequisites - -- Python 3.12 -- Network access to `pypi.nvidia.com` - -## Limitations - -- This installs Kit only; it does not install or enable Scene Optimizer by - itself. -- Installing Kit does not authenticate access to remote `omniverse://` servers. -- The smoke test accepts the Kit EULA through `OMNI_KIT_ACCEPT_EULA=yes`. - -## Install - -```bash -python3.12 -m venv ~/venvs/kit -source ~/venvs/kit/bin/activate -pip install --upgrade pip -pip install omniverse-kit --extra-index-url https://pypi.nvidia.com -``` - -## Smoke test - -```bash -OMNI_KIT_ACCEPT_EULA=yes python -m omni.kit_app --no-window --/app/quitAfter=10.0 -``` - -Kit boots, prints its banner, and quits. That confirms the install. - -Redirect smoke-test stdout/stderr to a log file and surface only a bounded tail -if troubleshooting is needed. Follow -`skills/omniverse-usd-performance-tuning/references/runtime-artifact-token-budget.md` -for Kit launch logs. - -## Troubleshooting - -- If `import omni.kit_app` fails, confirm the intended virtual environment is - active and rerun the pip install command. -- If the smoke test stalls on EULA handling, rerun it with - `OMNI_KIT_ACCEPT_EULA=yes`. -- For remote `omniverse://` assets, use `omniverse-authentication` to preflight - remote access, handle browser-based SSO, and verify `omni.client` can - stat/open the target URL before running profilers, validators, or Scene - Optimizer operations. +The optimize+validate path needs no Kit: see +`install-usd-optimize-standalone` and +`install-usd-validation-nvidia-standalone`. diff --git a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-so-via-kit/README.md b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-so-via-kit/README.md deleted file mode 100644 index 464e6d07..00000000 --- a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-so-via-kit/README.md +++ /dev/null @@ -1,96 +0,0 @@ -# Install Scene Optimizer via Kit - - - - -## When to Use - -Use when Scene Optimizer should run as a Kit extension. Do not use for standalone SO setup. - -## Instructions - -1. Confirm the target asset, artifact, or user intent and check the prerequisites listed below. -2. Read only the referenced files needed for the current phase, failure mode, or output contract. -3. Follow the workflow, rules, and safety gates in this reference before invoking downstream references or shell commands. -4. Return the result using the Output Format section and name any blocked prerequisite or unresolved user decision. - -## Output Format - -Return a concise status or report that names the input, selected runtime or evidence source, actions planned or performed, artifacts written, blockers, and the next validation or user-decision step. When a schema or template is referenced below, conform to that contract. - -## Purpose - -Kit + SO Kit extension. SO is fetched from Kit's extension registry on -first `--enable`, cached after. - -Use this reference when Scene Optimizer should run inside Kit so validators, -profilers, or remote USD access can share the same Kit runtime. - -## Prerequisites - -- Python 3.12 environment that can import or install `omni.kit_app`. -- Network access to the Kit package index and extension registry. -- Permission to accept the Kit EULA for headless smoke tests. - -## Limitations - -- First `--enable` may spend minutes fetching the extension from the registry. -- The in-Kit API differs from the standalone Scene Optimizer API. -- Remote `omniverse://` assets still need a separate authentication preflight. - -## Step 1 — Install Kit - -Invoke the `install-kit` skill if `python -c "import omni.kit_app"` -fails. Skip otherwise. - -## Step 2 — Verify SO loads - -```bash -OMNI_KIT_ACCEPT_EULA=yes python -c " -from omni.kit_app import KitApp -import sys -app = KitApp() -app.startup(['--no-window', '--enable', 'omni.scene.optimizer.core']) -from omni.scene.optimizer.core import SceneOptimizerCore -print(len(SceneOptimizerCore.getInstance().getOperations())) -sys.exit(app.shutdown()) -" -``` - -Expect ≥ 40 (floor — varies by version). First run pulls SO from the -registry (~minutes); subsequent runs are cached under -`~/.local/share/ov/data/Kit/`. - -The in-Kit verification path uses the public `SceneOptimizerCore` registry. -Operation invocation is defined by `so-run-operations/references/invocation.md`; -do not infer mutation call shapes from this install probe. - -## Remote Omniverse assets - -For `omniverse://` URLs, run the `omniverse-authentication` skill before the -first stage open. Kit may open a browser window for SSO and cache credentials -locally. Also enable `omni.client` and `omni.usd_resolver` when opening remote -stages from Python: - -```python -app.startup([ - "--no-window", - "--enable", "omni.client", - "--enable", "omni.usd_resolver", - "--enable", "omni.scene.optimizer.core", -]) -``` - -If `pxr` or `omni.client` is not importable after startup, add the installed Kit -extension folders to `sys.path` before importing USD modules. - -## Troubleshooting - -- If `import omni.kit_app` fails, run `install-kit` in the selected Python 3.12 - environment and retry from that environment. -- If the first SO startup is slow, wait for the registry fetch to finish; later - runs should use the Kit cache under `~/.local/share/ov/data/Kit/`. -- If remote stage opens fail, run `omniverse-authentication` before retrying the - full stage open. -- If `pxr` or `omni.client` remains unavailable after startup, add the installed - Kit extension folders to `sys.path` before importing USD modules. diff --git a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-so-standalone/README.md b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-usd-optimize-standalone/README.md similarity index 62% rename from skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-so-standalone/README.md rename to skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-usd-optimize-standalone/README.md index 1f22efa0..39793da9 100644 --- a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-so-standalone/README.md +++ b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-usd-optimize-standalone/README.md @@ -1,32 +1,26 @@ -# Install Scene Optimizer Standalone - - - +# Install Usd Optimize Standalone ## When to Use -Use when SO core operations or packaged SO validator rules are needed outside Kit. +Use when SO core operations or packaged Usd Optimize validator rules are needed outside Kit. ## Instructions -1. Confirm the target asset, artifact, or user intent and check the prerequisites listed below. -2. Read only the referenced files needed for the current phase, failure mode, or output contract. -3. Follow the workflow, rules, and safety gates in this reference before invoking downstream references or shell commands. -4. Return the result using the Output Format section and name any blocked prerequisite or unresolved user decision. +See `references/_shared/standard-instructions.md`. ## Output Format -Return a concise status or report that names the input, selected runtime or evidence source, actions planned or performed, artifacts written, blockers, and the next validation or user-decision step. When a schema or template is referenced below, conform to that contract. +See `references/_shared/standard-output-format.md`. ## Purpose PyPI wheel isn't released yet; this reference consumes a prebuilt -`scene_optimizer_core_...release.zip` package. Do not clone the Scene +`usd_optimize_...release.zip` package from GitHub Releases. Do not clone the Scene Optimizer source repo, run `repo.sh`, or depend on repo helper wrappers for standalone runtime setup. The package is ~350-380 MB; download + extract takes ~1-2 min on a fast connection. EULA env var **not** needed (no Kit). -Use this reference for standalone Scene Optimizer core operations and the +Use this reference for standalone Usd Optimize core operations and the packaged `omni.scene.optimizer.validators` rules when a Kit runtime is unavailable or not desired. For validator execution, pair this package with a project-managed `omniverse-asset-validator` environment that can import the @@ -34,7 +28,7 @@ same SO package. Kit remains useful when automatic extension registration or render-time profiling is needed. This install reference does not define operation invocation. Keep operation -execution examples in `so-run-operations/references/invocation.md` so agents +execution examples in `usd-optimize-run-operations/references/invocation.md` so agents have one source of truth. ## Prerequisites @@ -61,16 +55,20 @@ If either is missing, install before continuing Use a user-provided package archive path, direct archive URL, or extracted package root when supplied. Do not clone the source repository. If an extracted package root is supplied and it has the sentinel paths listed -under Package Version, set `SO_HOME` and `SCENE_OPTIMIZER_PACKAGE_ROOT` to that +under Package Version, set `USD_OPTIMIZE_ROOT` and `USD_OPTIMIZE_ROOT` to that root and skip the download/extract steps. -Current public direct archive URLs: +Prebuilt packages are published as **GitHub release assets** on +[NVIDIA-Omniverse/usd-optimize](https://github.com/NVIDIA-Omniverse/usd-optimize/releases) +(Linux x86_64, Linux aarch64, Windows x86_64): -- Linux x86_64: `https://d4i3qtqj3r0z5.cloudfront.net/scene_optimizer_core_usd_25.11_py_3.12%40110.1.0%2Bmaster.401.324ccecb.gl.manylinux_2_35_x86_64.release.zip` -- Windows x86_64: `https://d4i3qtqj3r0z5.cloudfront.net/scene_optimizer_core_usd_25.11_py_3.12%40110.1.0%2Bmaster.401.324ccecb.gl.windows-x86_64.release.zip` +```bash +gh release download v1.0.4 -R NVIDIA-Omniverse/usd-optimize -p '*manylinux*x86_64*' +# or browse: https://github.com/NVIDIA-Omniverse/usd-optimize/releases +``` -For direct archive URLs, `@` -> `%40` and `+` -> `%2B`. Auto-pick by -`uname -s`/`-m`. +Auto-pick the asset by `uname -s`/`-m`. Without `gh`, use the asset's browser +URL from the releases page (no URL-encoding gymnastics needed). ## Step 3 — Pick install location @@ -87,30 +85,30 @@ Use this step only for a direct archive path or URL. ```bash export SO_PACKAGE= -export SO_HOME= -mkdir -p "$SO_HOME" +export USD_OPTIMIZE_ROOT= +mkdir -p "$USD_OPTIMIZE_ROOT" case "$SO_PACKAGE" in - http://*|https://*) curl -L "$SO_PACKAGE" -o "$SO_HOME/scene_optimizer_core.zip" ;; - *) cp "$SO_PACKAGE" "$SO_HOME/scene_optimizer_core.zip" ;; + http://*|https://*) curl -L "$SO_PACKAGE" -o "$USD_OPTIMIZE_ROOT/usd_optimize_package.zip" ;; + *) cp "$SO_PACKAGE" "$USD_OPTIMIZE_ROOT/usd_optimize_package.zip" ;; esac -cd "$SO_HOME" +cd "$USD_OPTIMIZE_ROOT" python3.12 - <<'PY' import zipfile -archive = "scene_optimizer_core.zip" +archive = "usd_optimize_package.zip" if not zipfile.is_zipfile(archive): raise SystemExit( f"{archive} is not a zip archive; set SO_PACKAGE to a direct .zip " "archive path or URL and retry" ) PY -unzip -q scene_optimizer_core.zip +unzip -q usd_optimize_package.zip -cat > "$SO_HOME/activate.sh" <<'EOF' -export SO_HOME="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -export SCENE_OPTIMIZER_PACKAGE_ROOT="$SO_HOME" -export PYTHONPATH="$SO_HOME/python:$SO_HOME/usdpy:$PYTHONPATH" -export LD_LIBRARY_PATH="$SO_HOME/lib:$SO_HOME/extraLibs:$LD_LIBRARY_PATH" +cat > "$USD_OPTIMIZE_ROOT/activate.sh" <<'EOF' +export USD_OPTIMIZE_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +export USD_OPTIMIZE_ROOT="$USD_OPTIMIZE_ROOT" +export PYTHONPATH="$USD_OPTIMIZE_ROOT/python:$USD_OPTIMIZE_ROOT/usdpy:$PYTHONPATH" +export LD_LIBRARY_PATH="$USD_OPTIMIZE_ROOT/lib:$USD_OPTIMIZE_ROOT/extraLibs:$LD_LIBRARY_PATH" # uv-managed Python 3.12 ships libpython3.12.so.1.0 outside the system # loader path. Prepend the chosen interpreter's lib dir so SO's C++ @@ -121,24 +119,24 @@ if [ -n "$_so_pylib" ] && [ -d "$_so_pylib" ]; then fi unset _so_pylib EOF -source "$SO_HOME/activate.sh" +source "$USD_OPTIMIZE_ROOT/activate.sh" ``` -Env vars are **session-scoped**. Re-source `$SO_HOME/activate.sh` in +Env vars are **session-scoped**. Re-source `$USD_OPTIMIZE_ROOT/activate.sh` in any new shell. > **uv-managed Python 3.12.** When `python3.12` was installed via > `uv python install 3.12`, `libpython3.12.so.1.0` lives under > `~/.local/share/uv/python/cpython-3.12.*/lib/` and is **not** on the -> default loader path. Without the snippet above, the first SO import fails +> default loader path. Without the snippet above, the first Usd Optimize import fails > with `ImportError: libpython3.12.so.1.0: cannot open shared object > file`. The `_so_pylib` block in `activate.sh` derives the right > directory from `sys.base_prefix` so it works for both uv-managed and > system Pythons. On Windows: write `activate.bat` instead, using -`set SCENE_OPTIMIZER_PACKAGE_ROOT=%SO_HOME%` and -`set PATH=%SO_HOME%\lib;%SO_HOME%\extraLibs;%PATH%` (no `LD_LIBRARY_PATH`). +`set USD_OPTIMIZE_ROOT=%USD_OPTIMIZE_ROOT%` and +`set PATH=%USD_OPTIMIZE_ROOT%\lib;%USD_OPTIMIZE_ROOT%\extraLibs;%PATH%` (no `LD_LIBRARY_PATH`). Windows resolves `python312.dll` through the launcher that started the process, so the uv-managed-Python caveat above does not apply. @@ -169,7 +167,7 @@ PY Expect >= 40 (the exact count varies by build). This verifies import and operation registry only. Operation invocation is defined by -`so-run-operations/references/invocation.md`; do not infer mutation call shapes +`usd-optimize-run-operations/references/invocation.md`; do not infer mutation call shapes from this install probe. ## Limitations @@ -180,29 +178,14 @@ full validator engine. The drop may include a bundled `validator-venv/`. Do not use it as the default runtime — it may lack `numpy` and is slower on large stages. Use a -project-managed venv with `install-asset-validator-standalone` instead. +project-managed venv with `install-usd-validation-nvidia-standalone` instead. ## SO Validator Auto-Registration -The standalone SO package includes `omni.scene.optimizer.validators` — 25 -Python validator rules (mesh density, unused UVs, primitive fit, etc.) that -use `@register_rule` decorators. When OAV and the SO package share the same -Python environment, importing the validators auto-registers them: - -```python -import omni.scene.optimizer.validators # triggers @register_rule decorators - -from omni.asset_validator import CategoryRuleRegistry -registry = CategoryRuleRegistry() -# Now includes "Usd:Performance" and "Omni:Geometry" categories -``` - -No `register_all()` call is needed for rule discovery. The rule registration -decorators handle registration at import time. Do not treat category names as -validation scope, and do not select rules by bare name — the canonical executor -resolves a scope note's concepts to rule classes by identity (a bare -`find_rule()` can't tell the Scene Optimizer and Asset Validator rules that -share a class name apart). +See [so-validator-auto-registration.md](../so-validator-auto-registration.md) for +the shared rule: the standalone SO package's `omni.scene.optimizer.validators` +auto-register into OAV at import time when both packages share a Python +environment, and category names confirm discovery only (not validation scope). To verify the install can run a scoped concept after `usd-validation-runner` has scoped the plan: @@ -229,13 +212,13 @@ The standalone import is `from omni.asset_validator import ValidationEngine` Current expected package family (Kit 110.1 parity): ``` -scene_optimizer_core_usd_25.11_py_3.12@110.1.0+master.401.324ccecb.gl..release.zip +usd_optimize_usd_25.11_py_3.12 (version 1.0.4, .release.zip) ``` Expected layout after unpack: ``` -$SO_HOME/ +$USD_OPTIMIZE_ROOT/ ├── .agents/ # Operation guides and SO skills packaged for agents ├── python/ # Python modules (omni.scene.optimizer.*) ├── usdpy/ # USD Python bindings (pxr.*) @@ -248,9 +231,10 @@ Sentinel check (all runtime dirs plus agent docs must exist for a valid install) ```bash for sub in .agents python lib extraLibs usdpy; do - [[ -d "$SO_HOME/$sub" ]] || echo "MISSING: $sub" + [[ -d "$USD_OPTIMIZE_ROOT/$sub" ]] || echo "MISSING: $sub" done -[[ -f "$SO_HOME/.agents/operations/INDEX.md" ]] || echo "MISSING: .agents/operations/INDEX.md" +# Per-operation docs: docs/operations.rst (1.1.x packages) or .agents/operations/INDEX.md (1.0.x). Valid if either exists. +[[ -f "$USD_OPTIMIZE_ROOT/docs/operations.rst" || -f "$USD_OPTIMIZE_ROOT/.agents/operations/INDEX.md" ]] || echo "MISSING: per-operation docs (docs/operations.rst or .agents/operations/INDEX.md)" ``` ## Environment for Docker/CI @@ -258,8 +242,8 @@ done Set `WU_SO_PACKAGE_DIR` to point tools at the local backend: ```bash -export WU_SO_PACKAGE_DIR="$SO_HOME" -export SCENE_OPTIMIZER_PACKAGE_ROOT="$SO_HOME" +export WU_SO_PACKAGE_DIR="$USD_OPTIMIZE_ROOT" +export USD_OPTIMIZE_ROOT="$USD_OPTIMIZE_ROOT" ``` If absent, downstream tools may fall back to NVCF cloud backend or fail. @@ -267,18 +251,18 @@ If absent, downstream tools may fall back to NVCF cloud backend or fail. ## Troubleshooting - If `omni.scene.optimizer.core` cannot be imported, confirm Python 3.12 is - running and `$SO_HOME/activate.sh` has been sourced in the current shell. + running and `$USD_OPTIMIZE_ROOT/activate.sh` has been sourced in the current shell. - `ImportError: libpython3.12.so.1.0: cannot open shared object file` → the active `python3.12` is uv-managed (or otherwise installed outside - the system loader path) and `$SO_HOME/activate.sh` was not re-sourced + the system loader path) and `$USD_OPTIMIZE_ROOT/activate.sh` was not re-sourced after a fresh shell or after the `uv` install. The activate script prepends `$(python3.12 -c 'import sys, os; print(os.path.join(sys.base_prefix, "lib"))')` to `LD_LIBRARY_PATH`; re-source it. If the import still fails, run `python3.12 -c 'import sys; print(sys.base_prefix)'` manually and confirm a `lib/libpython3.12.so.1.0` exists under that prefix. -- If library loading fails on Linux, verify `$SO_HOME/lib` and - `$SO_HOME/extraLibs` are present in `LD_LIBRARY_PATH`. +- If library loading fails on Linux, verify `$USD_OPTIMIZE_ROOT/lib` and + `$USD_OPTIMIZE_ROOT/extraLibs` are present in `LD_LIBRARY_PATH`. - If the install looks incomplete, run the sentinel check above and redownload when any required directory is missing. - If downstream tools use a cloud backend or fail to find the package, set - `WU_SO_PACKAGE_DIR="$SO_HOME"` in the same environment. + `WU_SO_PACKAGE_DIR="$USD_OPTIMIZE_ROOT"` in the same environment. diff --git a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-asset-validator-standalone/README.md b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-usd-validation-nvidia-standalone/README.md similarity index 50% rename from skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-asset-validator-standalone/README.md rename to skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-usd-validation-nvidia-standalone/README.md index 45e3d8a4..b351609b 100644 --- a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-asset-validator-standalone/README.md +++ b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/install-usd-validation-nvidia-standalone/README.md @@ -1,12 +1,9 @@ -# Install Asset Validator Standalone - - - +# Install usd-validation-nvidia Standalone ## When to Use -Use when standalone Omni Asset Validator is needed outside Kit. This installs -into the **same Python 3.12 environment** that Scene Optimizer uses. The SO +Use when standalone Omni usd-validation-nvidia is needed outside Kit. This installs +into the **same Python 3.12 environment** that Usd Optimize uses. The SO validator rules auto-register via `@register_rule` decorators when both packages share a Python environment — no manual enabling required. @@ -14,31 +11,34 @@ packages share a Python environment — no manual enabling required. 1. Confirm Python 3.12 is available and the target environment is identified. 2. Install `omniverse-asset-validator` and `numpy` into the environment. -3. Verify the import and CLI work. +3. Ensure `pxr` (USD Python) is importable; if it is not already provided by SO's + `usdpy/`, install `usd-core` so a validator-only standalone venv still gets `pxr`. +4. Verify the imports and CLI work. ## Output Format -Return a concise status naming the environment path, Python executable, -`omni_asset_validate` version, and `numpy` version. +See [§ Output](#output) below for the value list to report. ## Purpose -Install the base Omni Asset Validator runtime into a standalone Python 3.12 -environment. When Scene Optimizer is also on `PYTHONPATH` in this environment, +Install the base Omni usd-validation-nvidia runtime into a standalone Python 3.12 +environment. When Usd Optimize is also on `PYTHONPATH` in this environment, `import omni.scene.optimizer.validators` triggers `@register_rule` decorators that register 25 SO performance validator rules into OAV automatically. ## Prerequisites - Python 3.12 is available. -- Network access to a package index that provides `omniverse-asset-validator`. -- The SO standalone package is already extracted (via `install-so-standalone`) +- Network access to a package index that provides `usd-validation-nvidia` + (the renamed usd-validation-nvidia package; the old `omniverse-asset-validator` + name is frozen at 1.18.0 on PyPI — new fixes ship only to the new name). +- The SO standalone package is already extracted (via `install-usd-optimize-standalone`) or will be set up afterward — order does not matter as long as both are importable in the same environment at runtime. ## Install -Use the **same venv** that Scene Optimizer will use. If `install-so-standalone` +Use the **same venv** that Usd Optimize will use. If `install-usd-optimize-standalone` already created a venv, reuse it. Otherwise create one: Linux: @@ -47,7 +47,10 @@ Linux: python3.12 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip -python -m pip install omniverse-asset-validator numpy +python -m pip install usd-validation-nvidia numpy +# Guarantee pxr (USD Python): if SO's usdpy/ is not already on PYTHONPATH, +# install usd-core. This makes `import pxr` succeed in a validator-only venv. +python -c "import pxr" 2>/dev/null || python -m pip install usd-core ``` Windows PowerShell: @@ -56,25 +59,36 @@ Windows PowerShell: py -3.12 -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade pip -python -m pip install omniverse-asset-validator numpy +python -m pip install usd-validation-nvidia numpy +# Guarantee pxr (USD Python): install usd-core only if SO does not already provide it. +python -c "import pxr" 2>$null; if ($LASTEXITCODE -ne 0) { python -m pip install usd-core } ``` > **Note:** `omniverse-asset-validator` does not declare `pxr` as a pip > dependency. The SO standalone package provides `pxr` via its `usdpy/` -> directory on `PYTHONPATH`. If SO is not yet configured, `pip install -> usd-core` is an alternative source for `pxr`. +> directory on `PYTHONPATH`; when SO is present, do not double-install. The rule +> is **ensure `pxr` is importable** — if it is not (e.g. a validator-only +> standalone venv with no SO yet), `pip install usd-core` provides it. After this +> step `import pxr` must succeed. ## Verify ```bash python -c "import omni.asset_validator; print('OAV', omni.asset_validator.__version__)" python -c "import numpy; print('numpy', numpy.__version__)" +python -c "import pxr; print('pxr OK')" omni_asset_validate --version ``` ## SO Validator Auto-Registration -Once both OAV and the SO package are importable in the same environment: +See [so-validator-auto-registration.md](../so-validator-auto-registration.md) for +the shared rule (auto-registration at import time when OAV and the Usd Optimize +package share a Python environment; category names confirm discovery only, not +validation scope). + +Once both OAV and the Usd Optimize package are importable in the same +environment, this command lists the registered categories and rule count: ```bash python -c " @@ -82,17 +96,13 @@ import omni.scene.optimizer.validators from omni.asset_validator import CategoryRuleRegistry registry = CategoryRuleRegistry() perf = [c for c in registry.categories if 'Performance' in c] -print(f'SO validator categories registered: {perf}') +print(f'Usd Optimize validator categories registered: {perf}') print(f'Total rules: {len(list(registry.rules))}') " ``` Expected: `Usd:Performance` and `Omni:Geometry` categories appear with ~25 -additional rules. No `register_all()` call is needed for rule discovery: the -validator registration decorators handle registration at import time. Category -names confirm discovery only; `usd-validation-runner` selects validators by -canonical concept and resolves them to rule classes by identity (via -`scripts/usd_validation_executor.py`) before calling `enable_rule()`. +additional rules. ## Output diff --git a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/kit-discovery.md b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/kit-discovery.md index 54a70c77..0ecfc229 100644 --- a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/kit-discovery.md +++ b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/kit-discovery.md @@ -1,6 +1,3 @@ - - - # Kit Discovery Use this reference for setup Step 1 and Step 1.5. The setup skill body owns @@ -41,7 +38,7 @@ A venv Kit runtime qualifies when it has `pyvenv.cfg` plus `Scripts/python.exe` or `bin/python`. Do not pre-check `exts/`, `extscache/`, or extension folders. The Python probe -in `runtime-probe.md` is the authoritative Scene Optimizer and Asset Validator +in `runtime-probe.md` is the authoritative Usd Optimize and usd-validation-nvidia availability test. ## Auto-Enumeration diff --git a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md index 58392d69..a8714352 100644 --- a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md +++ b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md @@ -1,17 +1,14 @@ - - - # Runtime context header > **Audience:** every agent that prompts the user inside the USD Performance Tuning workflow. -> **Rule:** print one of the two formats below **before** asking the user anything that depends on the active Kit / Scene Optimizer / Asset Validator runtime — runtime choice at Phase 0, restructure decision at Phase 2e, destructive-op approval in `so-run-operations`, verdict in `compare-profiles`, and the runtime block in `optimization-report`. The user must always be able to see which Kit application and which package versions are about to act on their asset. +> **Rule:** print one of the two formats below **before** asking the user anything that depends on the active Kit / Usd Optimize / usd-validation-nvidia runtime — runtime choice at Phase 0, restructure decision at Phase 2e, destructive-op approval in `usd-optimize-run-operations`, verdict in `compare-profiles`, and the runtime block in `optimization-report`. The user must always be able to see which Kit application and which package versions are about to act on their asset. ## Why this exists Three concrete pains have repeatedly surfaced when the runtime isn't visible: - A user authorizes a destructive operation without knowing which Kit version is about to mutate their stage — when something goes sideways later, reproduction is guesswork. -- The agent recommends an SO operation that the user's installed runtime doesn't ship. The user only finds out when the op silently no-ops mid-chain. +- The agent recommends an Usd Optimize operation that the user's installed runtime doesn't ship. The user only finds out when the op silently no-ops mid-chain. - Two team members run the same workflow against the same asset and get different validator counts because they're on different Kit / AV versions, and neither tracked which. Always-showing the runtime context puts that information where the decision happens. @@ -62,9 +59,9 @@ asks the user for one before continuing. Do not pick a default. DTP session MUST run the session-start gate exactly once. The entry skill is whichever workflow skill the agent invokes first for the user's request — typically `omniverse-usd-performance-tuning`, but can be -`so-run-operations`, `so-run-validators`, or `usd-validation-runner` +`usd-optimize-run-operations`, `usd-optimize-run-validators`, or `usd-validation-runner` when the user invokes one of those directly. Downstream skills -(`apply-restructure`, `so-interpret-validators`, `compare-profiles`, +(`apply-restructure`, `usd-optimize-interpret-validators`, `compare-profiles`, `optimization-report`, etc.) inherit the gate's result via the preflight JSON and do not re-run it. @@ -89,26 +86,25 @@ The gate's steps: ``` ─── Runtime context ─────────────────────────────────────────────────────── - Kit application: {runtime_context.kit.application} {runtime_context.kit.version} - path: {runtime_context.kit.path} - build: {runtime_context.kit.build} - Scene Optimizer: {runtime_context.sceneOptimizer.extension} {runtime_context.sceneOptimizer.version} - Asset Validator: {runtime_context.assetValidator.package} {runtime_context.assetValidator.version} via {runtime_context.assetValidator.source} + Runtime: standalone (Usd Optimize + usd-validation-nvidia) + Usd Optimize: {runtime_context.usdOptimize.package} {runtime_context.usdOptimize.version} + usd-validation-nvidia: {runtime_context.assetValidator.package} {runtime_context.assetValidator.version} via {runtime_context.assetValidator.source} + Kit profiling: {runtime_context.kit.application} {runtime_context.kit.version} (opt-in render-profiling adjunct, or "none") ─────────────────────────────────────────────────────────────────────────── - This runtime will be used for the work that follows. Continue, or change it? + Standalone is the runtime for all optimization + validation work. Continue? - > 1. Continue with this runtime - 2. Change Kit installation (re-runs setup-usd-performance-tuning Step 1) - 3. Switch to standalone (pip-installed libraries, no Kit) - 4. Re-run the runtime probe (refresh versions, re-detect) + > 1. Continue + 2. Re-run the runtime probe (refresh versions, re-detect) + 3. Enable / set the opt-in Kit→omniperf render-profiling adjunct ``` 4. **Route the answer.** - Option 1 → proceed to the actual work; subsequent messages in the same session may use Format B and skip the prompt. - - Option 2 / 3 / 4 → invoke `setup-usd-performance-tuning` and - overwrite the preflight before continuing. + - Option 2 / 3 → invoke `setup-usd-performance-tuning` and overwrite the + preflight before continuing. Kit is only a profiling adjunct; it is never + selected as an alternate optimization runtime. The gate fires **once per session**. Subsequent skill invocations within the same conversation reuse the preflight (and the user's "continue" @@ -128,17 +124,18 @@ run the gate instead. ## Source of truth -Both formats below read from the **`runtime_context`** object in `/setup-preflight.json` (canonical filename + location; see *Where artifacts live* above). `runtime_context` is the canonical block the probe writes and downstream skills consume; the header never reads the raw probe `kit` / `sceneOptimizer` / `assetValidator` source fields directly. The fields the header consumes are: +Both formats below read from the **`runtime_context`** object in `/setup-preflight.json` (canonical filename + location; see *Where artifacts live* above). `runtime_context` is the canonical block the probe writes and downstream skills consume; the header never reads the raw probe `kit` / `usdOptimize` / `assetValidator` source fields directly. The fields the header consumes are: - `runtime_context.kit.application` — friendly name (e.g. `USD Composer`, `Isaac Sim`, `Kit SDK`) - `runtime_context.kit.version` — release version (e.g. `110.1.0`) - `runtime_context.kit.path` — absolute install path - `runtime_context.kit.build` — full build identifier when present (e.g. `110.1.0+main.10181.f4b28ef2.gl.windows-x86_64.release`) -- `runtime_context.sceneOptimizer.extension` — extension name (e.g. `omni.scene.optimizer.core`) -- `runtime_context.sceneOptimizer.version` — extension version +- `runtime_context.usdOptimize.extension` — extension name (e.g. `omni.scene.optimizer.core`) +- `runtime_context.usdOptimize.version` — extension version - `runtime_context.assetValidator.package` — package or extension name - `runtime_context.assetValidator.version` — version -- `runtime_context.assetValidator.source` — `kit-extension`, `pip`, or `standalone` (informs the user whether AV runs through Kit or as a standalone Python install) +- `runtime_context.assetValidator.source` — `pip` or `standalone` (the validator runs as the usd-validation-nvidia Python package; the Kit validator extension is not a supported path) +- `runtime_context.cuda_available` — optional independent CUDA availability signal consumed by the Phase-4 batch scheduler; `false` blocks `gpu_bound` operations from silently falling back to slow CPU execution, `null` means unknown (the scheduler fails closed). If `/setup-preflight.json` is unavailable when an agent reaches a prompt that requires the header, it must invoke `setup-usd-performance-tuning` first. The header must never be skipped or partially filled. @@ -148,7 +145,7 @@ Use at every decision point where the user is authorizing something that mutates - `setup-usd-performance-tuning` runtime-choice prompt - `restructure-decision` Phase 2e prompt -- `so-run-operations` destructive-op confirmation +- `usd-optimize-run-operations` destructive-op confirmation - The first user-facing message in any session that starts mid-workflow ``` @@ -156,8 +153,8 @@ Use at every decision point where the user is authorizing something that mutates Kit application: {runtime_context.kit.application} {runtime_context.kit.version} path: {runtime_context.kit.path} build: {runtime_context.kit.build} -Scene Optimizer: {runtime_context.sceneOptimizer.extension} {runtime_context.sceneOptimizer.version} -Asset Validator: {runtime_context.assetValidator.package} {runtime_context.assetValidator.version} via {runtime_context.assetValidator.source} +Usd Optimize: {runtime_context.usdOptimize.extension} {runtime_context.usdOptimize.version} +usd-validation-nvidia: {runtime_context.assetValidator.package} {runtime_context.assetValidator.version} via {runtime_context.assetValidator.source} ─────────────────────────────────────────────────────────────────────────── ``` @@ -170,21 +167,28 @@ Use for routine status messages, ack messages, and follow-up prompts in the same This file is the **single source of truth** for the Format B string. Any skill that prints it (`omniverse-usd-performance-tuning` initial ack, `compare-profiles` verdict header) must reproduce it character-for-character: ``` -[Kit: {runtime_context.kit.application} {runtime_context.kit.version} | SO: {runtime_context.sceneOptimizer.version} | AV: {runtime_context.assetValidator.version}] +[Kit: {runtime_context.kit.application} {runtime_context.kit.version} | SO: {runtime_context.usdOptimize.version} | AV: {runtime_context.assetValidator.version}] +``` + +On a standalone-only runtime there is no `runtime_context.kit`; drop the Kit +segment entirely: + +```text +[SO: {runtime_context.usdOptimize.version} | AV: {runtime_context.assetValidator.version}] ``` Required at: - `omniverse-usd-performance-tuning` initial acknowledgement - `compare-profiles` verdict header -- Per-prototype progress lines in `so-run-operations` batch mode (Phase 4b) +- Per-prototype progress lines in `usd-optimize-run-operations` batch mode (Phase 4b) ## When to refresh the block The runtime can change mid-session if the user installs a new Kit or switches Python environments. The agent must re-print Format A whenever: - `setup-usd-performance-tuning` is re-invoked -- An install reference (`install-kit`, `install-so-via-kit`, `install-so-standalone`, `install-asset-validator-standalone`) reports a successful install +- An install reference (`install-kit`, `install-usd-optimize-standalone`, `install-usd-optimize-standalone`, `install-usd-validation-nvidia-standalone`) reports a successful install - The agent explicitly requests a runtime switch from the user Otherwise the cached preflight is fresh enough for the duration of the workflow. @@ -198,8 +202,8 @@ Otherwise the cached preflight is fresh enough for the duration of the workflow. Kit application: USD Composer 110.1.0 path: D:\build\chk\usd_composer-fat\110.1.0+main.10181.f4b28ef2.gl.windows-x86_64.release\kit build: 110.1.0+main.10181.f4b28ef2.gl.windows-x86_64.release -Scene Optimizer: omni.scene.optimizer.core 110.0.4 -Asset Validator: omniverse-asset-validator 1.x.y via kit-extension +Usd Optimize: omni.scene.optimizer.core 110.0.4 +usd-validation-nvidia: usd-validation-nvidia 1.x.y via pip ─────────────────────────────────────────────────────────────────────────── I will run usd-structure-assessment on /path/to/asset.usd. OK? @@ -210,8 +214,8 @@ I will run usd-structure-assessment on /path/to/asset.usd. OK? ``` ─── Runtime context ─────────────────────────────────────────────────────── Kit application: (not yet chosen — see Kit candidates below) -Scene Optimizer: (version determined by Kit choice) -Asset Validator: (version determined by Kit choice) +Usd Optimize: (version determined by Kit choice) +usd-validation-nvidia: (version determined by Kit choice) ─────────────────────────────────────────────────────────────────────────── Multiple Kit installations were found. The newest one is pre-selected. @@ -236,7 +240,7 @@ profile-stage: starting BASELINE capture in quick mode... - Do not print Format A more than once in the same session unless the runtime actually changed; users will start skimming it. Use Format B for everything after the first prompt. - Do not print just the version without the path. The path is what lets the user reproduce the run on another machine or check whether they're pointed at a build they don't expect. - Do not paraphrase the version. Print exactly what `/setup-preflight.json` records. Paraphrasing creates ambiguity when someone later asks "which build?" -- Do not skip the block in `so-run-operations` destructive-op confirmation. The user authorizing a destructive op must see the runtime explicitly at the moment of authorization, not earlier in the session. +- Do not skip the block in `usd-optimize-run-operations` destructive-op confirmation. The user authorizing a destructive op must see the runtime explicitly at the moment of authorization, not earlier in the session. ## Cross-references diff --git a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-probe.md b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-probe.md index f064f87e..929b2cae 100644 --- a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-probe.md +++ b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-probe.md @@ -1,10 +1,7 @@ - - - # Runtime Probe Contract Use this reference for setup Step 1.6 and Step 3. The probe is the only -authoritative check for Kit, Scene Optimizer, Asset Validator, and operation +authoritative check for Kit, Usd Optimize, usd-validation-nvidia, and operation availability. ## Probe Outputs @@ -28,7 +25,7 @@ If INFO-level plugin logs are needed for troubleshooting, set Required blocks: - `kit`: chosen application, version, build, path, launcher. -- `sceneOptimizer`: extension/package name, version, operation count, +- `usdOptimize`: extension/package name, version, operation count, `operationsAvailable`, and source. - `assetValidator`: package/extension name, version, and source. - `runtime_context`: mirror of the user-facing values consumed by @@ -37,7 +34,7 @@ Required blocks: `operationsAvailable` must come from the live runtime and must be sorted. Do not hand-copy operation keys from a snapshot. -Note: `probe-snapshot.schema.json` (flat fixture, snake_case `operations_available`) is a curation reference for version comparison — it is a different artifact from `setup-preflight.json` (nested runtime config, camelCase `sceneOptimizer.operationsAvailable`) which is the agent's runtime output consumed by downstream phases. +Note: `probe-snapshot.schema.json` (flat fixture, snake_case `operations_available`) is a curation reference for version comparison — it is a different artifact from `setup-preflight.json` (nested runtime config, camelCase `usdOptimize.operationsAvailable`) which is the agent's runtime output consumed by downstream phases. ## Launchers @@ -50,42 +47,41 @@ Use the launcher selected during Kit discovery: Set `OMNI_KIT_ACCEPT_EULA=yes`. Start Kit with `--no-window`, `--enable omni.scene.optimizer.core`, and -`--enable omni.asset_validator.core`. +(validator runs from the pip package, not a Kit extension). ## Import Modes -Do not mix Kit-mode and standalone-mode Asset Validator imports. +The validator always imports standalone (`omni.asset_validator` from the usd-validation-nvidia pip package); the Kit validator extension is not a supported path. -| Mode | SO import | AV import | AV version | +| Mode | Usd Optimize import | AV import | AV version | |---|---|---|---| | Standalone | `omni.scene.optimizer.core` | `omni.asset_validator` | `importlib.metadata.version("omniverse-asset-validator")` | -| Kit | `omni.scene.optimizer.core` | `omni.asset_validator.core` | Kit extension manager | -Scene Optimizer uses the same import in both modes. Asset Validator is the +Usd Optimize uses the same import in both modes. usd-validation-nvidia is the asymmetric case. ## Version Sources Prefer these sources in order: -- **Scene Optimizer (standalone):** use this fallback chain — stop at the first +- **Usd Optimize (standalone):** use this fallback chain — stop at the first that returns a non-empty, non-`0.0.0` value: 1. `omni.scene.optimizer.core.__version__` (may not exist on prebuilts). 2. `omni.scene.optimizer.impl.core.SOPluginVersion()` → `"{major}.{minor}.{rev}"`. If all three are `0`, treat as unstamped. - 3. `$SCENE_OPTIMIZER_PACKAGE_ROOT/CHANGELOG.md` — read the first `## ` + 3. `$USD_OPTIMIZE_ROOT/CHANGELOG.md` — read the first `## ` heading (e.g. `## 110.0.5 — 2026-06-01`). Report as `"0.0.0+changelog:"` to signal the binding is unstamped but the package is identifiable. 4. If all fail, report `"unknown"` with an `errors` entry. -- **Asset Validator (standalone):** `importlib.metadata.version("omniverse-asset-validator")`. +- **usd-validation-nvidia (standalone):** `importlib.metadata.version("omniverse-asset-validator")`. - **Kit application:** `omni.kit.app.get_app().get_app_version()`. -- **Scene Optimizer (Kit):** extension manager package version for +- **Usd Optimize (Kit):** extension manager package version for `omni.scene.optimizer.core`. -- **Asset Validator (Kit):** extension manager package version for +- **usd-validation-nvidia (Kit):** extension manager package version for `omni.asset_validator.core`. -For supported SO operation keys, use this fallback chain: +For supported Usd Optimize operation keys, use this fallback chain: ```python # Preferred: @@ -100,7 +96,7 @@ omni.scene.optimizer.core.bindings._omni_scene_optimizer_core \ ## Success Criteria -Expect at least 40 Scene Optimizer operations and a successful +Expect at least 40 Usd Optimize operations and a successful `omni.asset_validator.core` import for Kit-mode validation. If either probe fails, ask for another path or fall back to Kit. diff --git a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/so-validator-auto-registration.md b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/so-validator-auto-registration.md new file mode 100644 index 00000000..9762eacc --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/so-validator-auto-registration.md @@ -0,0 +1,31 @@ +# SO Validator Auto-Registration + +Shared reference for how the Usd Optimize (SO) performance validator rules +register into the Omni Asset Validator (OAV). Cited by both +`install-usd-optimize-standalone/README.md` and +`install-usd-validation-nvidia-standalone/README.md`. + +The standalone SO package includes `omni.scene.optimizer.validators` — 25 Python +validator rules (mesh density, unused UVs, primitive fit, etc.) declared with +`@register_rule` decorators. When OAV and the Usd Optimize package share the same +Python environment, importing the validators auto-registers them; no +`register_all()` call is needed for rule discovery — the decorators handle +registration at import time. + +```python +import omni.scene.optimizer.validators # triggers @register_rule decorators + +from omni.asset_validator import CategoryRuleRegistry +registry = CategoryRuleRegistry() +# Now includes the "Usd:Performance" and "Omni:Geometry" categories +``` + +Expected: the `Usd:Performance` and `Omni:Geometry` categories appear with ~25 +additional rules. + +**Category names confirm discovery only — they are not validation scope.** Do not +select rules by bare name: `usd-validation-runner` selects validators by canonical +concept and resolves them to rule classes by identity (via +`scripts/usd_validation_executor.py`) before calling `enable_rule()`. A bare +`find_rule()` cannot tell the Usd Optimize and usd-validation-nvidia rules that +share a class name apart. diff --git a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/standalone-runtime.md b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/standalone-runtime.md index 7a22f96d..2f1b3842 100644 --- a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/standalone-runtime.md +++ b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/standalone-runtime.md @@ -1,6 +1,3 @@ - - - # Standalone Runtime Setup Use this reference when the user chooses standalone libraries instead of Kit or @@ -8,61 +5,68 @@ when no Kit candidate is available. ## Statuses -- `ready-standalone`: standalone Scene Optimizer and Asset Validator paths are +- `ready-standalone`: standalone Usd Optimize and usd-validation-nvidia paths are selected and verified. - `needs-runtime-choice`: setup cannot continue without the user choosing Kit, standalone, or installation. -- `blocked_missing_scene_optimizer`: the user requested Scene Optimizer but no +- `blocked_missing_usd_optimize`: the user requested Usd Optimize but no supported SO runtime can be selected or installed. -## Scene Optimizer Prompt +## Usd Optimize Prompt -When standalone Scene Optimizer is missing, ask before invoking -`install-so-standalone`. The prompt must include: +When standalone Usd Optimize is missing, ask before invoking +`install-usd-optimize-standalone`. The prompt must include: - Python 3.12 hard requirement. - Approximate download size (~350-380 MB for the prebuilt standalone package). - Intended install location. -- Requirement for a published `scene_optimizer_core_...release.zip` package +- Requirement for a published prebuilt Usd Optimize release package + (asset name + download: `references/upstreams/usd-optimize.md`) archive path, direct archive URL, or extracted package root when no package root is already available. -- SO validators auto-register into OAV via `@register_rule` decorators when +- Usd Optimize validators auto-register into OAV via `@register_rule` decorators when both packages share the same Python environment — no manual enabling needed. - Limitation that render-time profiling needs Kit. Offer: -1. Proceed with standalone Scene Optimizer install. +1. Proceed with standalone Usd Optimize install. 2. Install Kit instead. 3. Stop and produce diagnosis-only output from available evidence. If the user proceeds and Python 3.12 is missing, install or select Python 3.12 -first, then invoke `install-so-standalone`. +first, then invoke `install-usd-optimize-standalone`. ## Expected Standalone Layout -Scene Optimizer standalone uses: +Usd Optimize standalone uses: ```text -/.agents/operations/INDEX.md -/python -/usdpy -/lib -/extraLibs +/docs/operations.rst # per-op docs, 1.1.x packages +/.agents/operations/INDEX.md # per-op docs, 1.0.x packages +/python +/usdpy +/lib +/extraLibs ``` -Invoke `install-so-standalone` when `SCENE_OPTIMIZER_PACKAGE_ROOT`, `SO_HOME`, +The per-operation doc sentinel is version-tolerant: a root is valid when either +`docs/operations.rst` (1.1.x packages) or `.agents/operations/INDEX.md` (1.0.x +packages) exists. The runtime dirs (`python`, `usdpy`, `lib`, `extraLibs`) must +be present regardless. + +Invoke `install-usd-optimize-standalone` when `USD_OPTIMIZE_ROOT`, `USD_OPTIMIZE_ROOT`, or `WU_SO_PACKAGE_DIR` is missing or does not point at an extracted package with -the sentinel paths above. Do not clone the Scene Optimizer source repository to +the sentinel paths above. Do not clone the Usd Optimize source repository to satisfy standalone setup. -For standalone Omni Asset Validator, invoke `install-asset-validator-standalone` +For standalone Omni usd-validation-nvidia, invoke `install-usd-validation-nvidia-standalone` when `omni_asset_validate` is missing. Install into the same venv that Scene -Optimizer uses — SO validators auto-register via `@register_rule` when both +Optimizer uses — Usd Optimize validators auto-register via `@register_rule` when both packages are importable. -Do not use the Scene Optimizer package's bundled `validator-venv` as the -default Asset Validator runtime — it may lack `numpy` and is slower on large +Do not use the Usd Optimize package's bundled `validator-venv` as the +default usd-validation-nvidia runtime — it may lack `numpy` and is slower on large stages. ## Handoff @@ -71,5 +75,5 @@ After standalone setup, return to: - `omniverse-usd-performance-tuning` for broad performance requests. - `usd-validation-runner` for validation. -- `so-run-operations` only after Scene Optimizer operation availability is +- `usd-optimize-run-operations` only after Usd Optimize operation availability is verified and recorded in `/setup-preflight.json`. diff --git a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/scripts/probe-snapshot.schema.json b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/scripts/probe-snapshot.schema.json index 67a5e314..5f059b1d 100644 --- a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/scripts/probe-snapshot.schema.json +++ b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/scripts/probe-snapshot.schema.json @@ -17,13 +17,13 @@ "so_build_date": { "type": "string", "format": "date-time", - "description": "ISO 8601 UTC date the SO extension was built or released. Used as the comparison key when filtering ops by since_version. Filled in manually after capture because the extension does not expose buildTime." + "description": "ISO 8601 UTC date the Usd Optimize extension was built or released. Used as the comparison key when filtering ops by since_version. Filled in manually after capture because the extension does not expose buildTime." }, "operations_available": { "type": "array", "items": { "type": "string" }, "uniqueItems": true, - "description": "Operation keys the SO runtime registers, as returned by the selected operation registry probe. Sorted alphabetically." + "description": "Operation keys the Usd Optimize runtime registers, as returned by the selected operation registry probe. Sorted alphabetically." }, "probed_at": { "type": "string", diff --git a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/scripts/setup-preflight.schema.json b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/scripts/setup-preflight.schema.json index 2770872c..db5bef24 100644 --- a/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/scripts/setup-preflight.schema.json +++ b/skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/scripts/setup-preflight.schema.json @@ -2,12 +2,12 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "setup-preflight.schema.json", "title": "Setup Preflight Configuration", - "description": "Runtime contract for setup-preflight.json. Strict on sceneOptimizer and assetValidator — downstream agents cross-check operationsAvailable against planned operations. A wrong field name means the operation check fails silently.", + "description": "Runtime contract for setup-preflight.json. Strict on usdOptimize and assetValidator — downstream agents cross-check operationsAvailable against planned operations. A wrong field name means the operation check fails silently.", "type": "object", "required": [ "schemaVersion", "runtime_route", - "sceneOptimizer", + "usdOptimize", "assetValidator", "runtime_context", "probed_at" @@ -19,11 +19,12 @@ }, "runtime_route": { "type": "string", - "enum": ["kit", "standalone"] + "enum": ["kit", "standalone"], + "description": "The optimization+validation runtime. This is 'standalone' for all optimization and validation work; Kit is no longer an optimization runtime. The 'kit' value is retained only for legacy/back-compat records — a Kit install used for the opt-in render-profiling adjunct is recorded under the top-level 'kit' object, not by setting runtime_route to 'kit'." }, "kit": { "type": "object", - "description": "Present when runtime_route is 'kit'. Kit application metadata.", + "description": "Optional opt-in Kit→omniperf render-profiling root (user-supplied or discovered). Retained for the profiling adjunct only; it is never the SO/AV optimization runtime. Kit application metadata.", "additionalProperties": true, "properties": { "application": { "type": "string" }, @@ -32,9 +33,13 @@ "build": { "type": "string" } } }, - "sceneOptimizer": { + "cuda_available": { + "type": ["boolean", "null"], + "description": "Independent CUDA availability signal consumed by the Phase-4 batch scheduler (usd-optimize-run-operations/scripts/run_batch.py). Read from this preflight / runtime_context, NEVER from Usd Optimize's own hasNvidiaGpu(). false means gpu_bound operations must not silently fall back to slow CPU execution; null/missing means unknown and the scheduler fails closed (treats the host as CPU-only)." + }, + "usdOptimize": { "type": "object", - "description": "Scene Optimizer runtime identity. Strict: operationsAvailable is the cross-check contract consumed by EXECUTION.md and so-run-operations.", + "description": "Usd Optimize runtime identity. Strict: operationsAvailable is the cross-check contract consumed by EXECUTION.md and usd-optimize-run-operations.", "required": ["extension", "version", "operationsAvailable", "source"], "additionalProperties": false, "properties": { @@ -52,13 +57,13 @@ }, "source": { "type": "string", - "enum": ["kit-extension", "standalone-package"] + "enum": ["standalone-package"] } } }, "assetValidator": { "type": "object", - "description": "Asset Validator runtime identity. Strict: source enum determines validation command patterns.", + "description": "usd-validation-nvidia runtime identity. Strict: source enum determines validation command patterns.", "required": ["package", "version", "source"], "additionalProperties": false, "properties": { @@ -70,18 +75,19 @@ }, "source": { "type": "string", - "enum": ["kit-extension", "pip", "standalone"] + "enum": ["pip", "standalone"] } } }, "runtime_context": { "type": "object", - "description": "Canonical runtime context block that downstream skills (optimization-report, the runtime-context-header) consume. The probe writes the chosen runtime here and the header prints from it; the source kit/sceneOptimizer/assetValidator fields above are the raw probe data. Inner shape matches the optimization-report schema's runtime_context definition exactly so the block can be copied verbatim into the report.", - "required": ["kit", "sceneOptimizer", "assetValidator"], + "description": "Canonical runtime context block that downstream skills (optimization-report, the runtime-context-header) consume. The probe writes the chosen runtime here and the header prints from it; the source kit/usdOptimize/assetValidator fields above are the raw probe data. Inner shape matches the optimization-report schema's runtime_context definition exactly so the block can be copied verbatim into the report.", + "required": ["usdOptimize", "assetValidator"], "properties": { "kit": { "type": "object", "required": ["application", "version", "path"], + "description": "Kit application context. OPTIONAL: omitted on a standalone-only runtime (Kit is an opt-in render-profiling adjunct). When present, application/version/path are required.", "properties": { "application": { "type": "string", @@ -101,7 +107,7 @@ } } }, - "sceneOptimizer": { + "usdOptimize": { "type": "object", "required": ["extension", "version"], "properties": { @@ -129,10 +135,14 @@ }, "source": { "type": "string", - "enum": ["kit-extension", "pip", "standalone"], - "description": "Where Asset Validator was loaded from." + "enum": ["pip", "standalone"], + "description": "Where usd-validation-nvidia was loaded from." } } + }, + "cuda_available": { + "type": ["boolean", "null"], + "description": "Optional copy of the top-level CUDA availability signal for downstream consumers that read only runtime_context (the scheduler's --preflight path reads it here)." } } }, diff --git a/skills/omniverse-usd-performance-tuning/references/skill-map.md b/skills/omniverse-usd-performance-tuning/references/skill-map.md index 18c8e1d0..44467130 100644 --- a/skills/omniverse-usd-performance-tuning/references/skill-map.md +++ b/skills/omniverse-usd-performance-tuning/references/skill-map.md @@ -8,11 +8,11 @@ agent_next: freshness: 2026-05-20 version: "0.1.0" --- - - # USD Performance Tuning Skill Map +> **"SO" / "Scene Optimizer" = Usd Optimize** (the `omni.scene.optimizer.core` extension). The Kit-bundled extension uses the 110.x version line (e.g. 110.0.4); the standalone package uses the 1.0.x line (e.g. 1.0.4). Both refer to the same Usd Optimize; the extension id and the 110.x versions are retained intentionally as the real runtime identifiers. + > Compact navigation aid for the agent-facing catalog. Detailed phase > choreography lives with the owning entry skill: > `skills/omniverse-usd-performance-tuning/references/workflow.md`. @@ -23,20 +23,26 @@ Use this map to enter the single public workflow skill and load only the next necessary nested reference. Do not pre-read every reference. - Start every public USD performance request in - `omniverse-usd-performance-tuning`. -- Route validation-only requests to `usd-validation-runner`. + `omniverse-usd-performance-tuning`. There is one entry: the full + optimize+validate pipeline. Validation, structuring, and individual ops are + phases of that pipeline, not standalone entries — there is no validation-only, + structure-only, or direct-op bypass. - Route runtime ambiguity to `setup-usd-performance-tuning` unless a runtime path is already verified. - Route `omniverse://` targets to `omniverse-authentication` before probing. -- Route approved Scene Optimizer operation execution to `so-run-operations`. -- Resolve Scene Optimizer mechanics through upstream - [usd-optimize](https://github.com/NVIDIA-omniverse/usd-optimize/) or the - prebuilt `scene_optimizer_core_...release.zip` package using - `$SCENE_OPTIMIZER_PACKAGE_ROOT`, then `$SO_HOME`. If no package root exists, +- Route an explicit render-profiling request (FPS / Hydra / RTX / VRAM / + draw-call) to the opt-in Kit→omniperf profiling path (`profile-stage` full + mode / `compare-profiles`). This is a profiling adjunct, never an alternate + optimization runtime. +- Resolve Usd Optimize mechanics through upstream + [usd-optimize](https://github.com/NVIDIA-Omniverse/usd-optimize/) or the + prebuilt Usd Optimize release package (asset resolution: + `references/upstreams/usd-optimize.md`) using + `$USD_OPTIMIZE_ROOT`. If no package root exists, use the package path, URL, or extracted root supplied by the user. Current public direct archive URLs are listed in `references/upstreams/usd-optimize.md`. Do not clone the source repo just to - read SO operation docs. + read Usd Optimize operation docs. - Read [the workflow reference](workflow.md) when the request needs the full Phase 0-7 optimization flow. @@ -63,15 +69,16 @@ only when their phase is reached: |---|---| | `profile-stage` | Loaded by the workflow for baseline and after metrics. | | `usd-hierarchy-dedupe-candidates` | Loaded when copied hierarchy or high mesh count suggests structure reuse. | +| `usd-mesh-fragmentation-candidates` | Loaded when a converter face-explosion (flat fan of anonymous same-material meshes under a named unit) suggests a within-prototype merge. | | `restructure-decision` | Loaded for the Phase 2e user-confirm gate. | | `apply-restructure` | Loaded for Phase 2f hierarchy rewrite and Phase 5 reference remap. | | `instancing-readiness` | Loaded when the workflow finds candidate instances. | | `usd-edit-target-planner` | Loaded when edits need a safe authoring target. | -| `so-run-validators` | Loaded by validation routing for Scene Optimizer validator execution. | -| `so-interpret-validators` | Loaded to turn validator findings into operation recommendations. | +| `usd-optimize-run-validators` | Loaded by validation routing for Usd Optimize validator execution. | +| `usd-optimize-interpret-validators` | Loaded to turn validator findings into operation recommendations. | | `compare-profiles` | Loaded at Phase 6 to classify improvement, neutral, regression, or mixed outcomes. | -| `install-kit`, `install-so-via-kit`, `install-so-standalone`, `install-asset-validator-standalone` | Loaded only by setup dispatch. | -| `so-create-proxy` | Specialty user-request reference, not part of the main optimization flow. | +| `install-kit`, `install-usd-optimize-standalone`, `install-usd-validation-nvidia-standalone` | Loaded only by setup dispatch. | +| `usd-optimize-create-proxy` | Specialty user-request reference, not part of the main optimization flow. | Validation command references are owned by `skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/` rather than top-level @@ -84,6 +91,11 @@ skills. - `usd-hierarchy-dedupe-candidates` stays a separate downstream diagnostic reference. It is loaded only when assessment finds copied hierarchy, high mesh count, or likely reusable prototypes that need candidate grouping. +- `usd-mesh-fragmentation-candidates` is its merge-side counterpart: the + hierarchy finder finds *repeated subtrees* to **instance**; the fragmentation + suggester finds *fragmented same-material fans* to **merge**. A fan that is also + a repeated subtree is instanced at the component, then merged inside the + prototype — the two compose, they do not compete. - `restructure-decision` stays a thin user-confirmation gate between assessment evidence and `apply-restructure`. Do not fold it into assessment unless the runtime scenarios still pass and the gate remains explicit. @@ -101,13 +113,12 @@ flowchart TD P1["Phase 1 Baseline + structure"] P2["Phase 2 Composition + decision"] P3["Phase 3 Instancing"] - P4["Phase 4 Per-asset SO ops"] + P4["Phase 4 Per-asset Usd Optimize ops"] P5["Phase 5 Ref remap + cleanup"] P6["Phase 6 Verify + report"] P7["Phase 7 Default scoped iteration"] P0 --> P1 --> P2 - P2 -->|"already optimized or exit"| P6 - P2 -->|"continue"| P3 --> P4 --> P5 --> P6 + P2 --> P3 --> P4 --> P5 --> P6 P6 --> P7 ``` @@ -118,14 +129,14 @@ flowchart TD `skills/omniverse-usd-performance-tuning/references/runtime-artifact-token-budget.md` - Validation routing: `skills/omniverse-usd-performance-tuning/references/usd-validation-runner/README.md` - Validation command references: `skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/` -- Scene Optimizer operation mechanics: - [`usd-optimize`](https://github.com/NVIDIA-omniverse/usd-optimize/) or the - prebuilt Scene Optimizer package (local handoff: +- Usd Optimize operation mechanics: + [`usd-optimize`](https://github.com/NVIDIA-Omniverse/usd-optimize/) or the + prebuilt Usd Optimize package (local handoff: `references/upstreams/usd-optimize.md`) -- Local operation routing metadata: `references/operations/manifest.json`, - `references/operations/README.md`, and `references/operations/_curation.json` -- Local SO workflow policy: - `skills/omniverse-usd-performance-tuning/references/so-run-operations/` +- Local operation routing metadata: `references/operations/operations.json` + (routing fields + nested `curation` block) and `references/operations/README.md` +- Local Usd Optimize workflow policy: + `skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/` - Structure-assessment subtopics: `skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/` - Output/edit-target policy: `skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/` - Final report contract: `skills/omniverse-usd-performance-tuning/references/optimization-report/references/optimization-report-template.md` and @@ -133,6 +144,26 @@ flowchart TD ## Reference-reading Policy -Some workflow references are copied documentation snapshots. If a reference -has a `Canonical URL`, prefer the live URL when network access is available; -the local copy is a snapshot. +See [workflow.md § Reference-reading policy](workflow.md#reference-reading-policy) +for the rule: if a reference's header block carries a `Canonical URL`, prefer the +live URL when network access is available (the local copy is a snapshot). + +## Status Vocabulary + +Every status token in this skill tree, with its owner. Do not invent new +tokens; spell enum values exactly as the schema does (underscores, not +hyphens). + +| Token | Kind | Owner | +|---|---|---| +| `ready_to_plan` | plan-time decision | SKILL.md (Plan-time vs execution-time approval) | +| `approval_required` | apply-gate decision | SKILL.md + `usd-optimize-run-operations/references/operation-safety.md` | +| `blocked_missing_usd_optimize`, `blocked_missing_usd_optimize_operation` | Phase 0 blocked codes | `workflow.md` Phase 0 | +| `workflow_mode: full \| structural_only \| no_op` | report enum | `optimization-report/scripts/optimization-report.schema.json` | +| `verdict: improved \| neutral \| regressed \| mixed` | report enum | same schema (compare-profiles produces it) | +| `apply_authority: auto \| auto-within-tolerance \| intent-gated` | per-op class | `references/operations/operations.json` + operation-safety.md | +| `disposition: optimized \| skipped_zero_meshes \| skipped_user_declined \| blocked` | target coverage | optimization-report schema (`target_coverage.entries[]`) | + +Phase 4.5 (layer cleanup after destructive in-place ops, `workflow.md`) is an +interstitial step inside Phase 4→5, not a top-level phase; it is intentionally +absent from the phase diagram above. diff --git a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/batch-mode.md b/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/batch-mode.md deleted file mode 100644 index add3edf0..00000000 --- a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/batch-mode.md +++ /dev/null @@ -1,113 +0,0 @@ - - - -# Agent-Orchestrated Batch Mode - -This is Phase 4b of the canonical workflow. It is an agent orchestration -pattern, not a wrapper flag. Optional helper wrappers accept one asset path; -the agent invokes the single-asset runner per target. - -Do not serialize independent optimization targets by default. Run them in -adaptive batches sized by target weight and available system resources, then -adjust concurrency after each completed batch. - -## Targets - -Targets come from: - -- `apply-restructure` mode=`restructure`: prototype USDs, shared layers, and - newly loadable sub-assets recorded in - `/apply-restructure-manifest.json` `phase4_targets[]`, plus any - `target_class: "assembly_root"` entry for mesh data retained in the assembly. - Do not filter the manifest to prototype files only. -- Composed stages with no restructure: referenced sub-assets from - `usd-structure-assessment` Phase 1.2 `assets.manifest`. -- Monolithic-as-is: the original stage (`N=1`). - -## Adaptive Concurrency - -Use target count only after estimating target weight. A fixed target-count cap -is too conservative for small mechanical parts and too aggressive for large -floor-scale facility sections. - -Before the first batch, build a lightweight batch manifest: - -- Independent target list, grouped by dependency class. -- Per-target weight signals: file size, mesh count, vertex/face count, - material/texture count, prototype/instance count, and expected op-chain cost. -- Resource budget: CPU cores, available RAM, available VRAM when Kit/rendering - is involved, free disk, and expected log/artifact volume. -- Initial concurrency choice and reason. - -Initial concurrency guidance: - -| Target class | Starting point | -|---|---| -| Monolithic target | `1` | -| Heavy facility/floor-scale target, multi-GB target, or high mesh/texture count | `1`, then increase only after a healthy pilot | -| Medium sub-assets | `2-4` depending on memory and disk headroom | -| Small mechanical parts or small fixture libraries | Start above `5` when resources allow; use CPU, memory, disk, and log headroom rather than the old fixed cap | -| Unknown weight | Start conservatively at `2`, or `1` if opening one target already consumes significant memory | - -After each batch, inspect duration, failed targets, peak RAM/VRAM if available, -disk growth, log size, and output count. Increase concurrency when the pilot is -healthy and targets are small. Decrease concurrency or switch to serial when a -batch hits memory pressure, GPU pressure, disk/log pressure, runtime crashes, -or long-tail target variance. - -If the remaining work is likely to exceed the user's time/resource budget, pause -and ask whether to continue, generate a remainder script, or stop. Do not pause -solely because target count exceeds five; pause because the observed budget or -risk says continuing automatically is unsafe. - -## Prototype-First Ordering - -When targets include prototypes and non-prototype assets, run prototypes first, -wait for completion, then run non-prototype assets. Parallelize within each -dependency group according to the adaptive concurrency policy. Prototype changes -propagate to instances, so running instance-site work first wastes time. Treat -an `assembly_root` target with retained meshes as a non-prototype mesh target: -run the evidence-selected per-target mesh op chain on it before final -assembled-root cleanup. - -## Output Naming - -Hash the absolute input path in every per-target output, summary, and log -filename. Basename-only naming is unsafe because many industrial scenes contain -repeated names such as `Body.usd` or `Default_V5.usd`. - -Recommended pattern: - -```text -..optimized.usdc -..summary.json -..log -``` - -After every batch, verify that the number of produced optimized files matches -the number of targets in that batch. If not, report a collision or failed write -instead of declaring success. - -## Remainder Prompt - -When the adaptive budget says the remaining work should not continue -automatically, show: - -- Already optimized targets. -- Deferred targets. -- Observed runtime/resource pressure from completed batches. -- Remainder script path, if generated. -- Options: run the remainder script now, stop here, or explicitly optimize all - remaining targets anyway. - -Default behavior is to stop until the user chooses; the resource budget is the -guardrail. - -## Failure Handling - -Aggregate per-target summaries into one batch summary. Surface failed targets -with log and summary paths. Do not auto-retry failed targets. - -The final batch manifest should record every batch's target list, concurrency, -duration, output paths, summary/log paths, failures, resource observations, and -the reason for any concurrency adjustment. diff --git a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/invocation.md b/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/invocation.md deleted file mode 100644 index 771401e3..00000000 --- a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/invocation.md +++ /dev/null @@ -1,188 +0,0 @@ - - - -# Invocation Reference - -How to execute Scene Optimizer operations once the runtime is selected and the -operation plan is approved. Read `/setup-preflight.json` to -determine which runtime and API surface to use. - -This is the local source of truth for Scene Optimizer operation invocation. -Other workflow docs should link here instead of repeating Python API snippets. - -The two runtimes below are peers — neither is preferred. The user's Phase 0 -choice determines which section applies. - -## Kit Runtime - -When `setup-preflight.json` indicates Kit as the selected runtime, bootstrap -Kit first, then use the same supported Python shapes as standalone. - -```python -import os -import sys - -os.environ.setdefault("OMNI_KIT_ACCEPT_EULA", "yes") - -from omni.kit_app import KitApp - -app = KitApp() -app.startup([ - "--no-window", - "--enable", "omni.scene.optimizer.core", - "--enable", "omni.asset_validator.core", - # For omniverse:// assets, also enable: - # "--enable", "omni.client", - # "--enable", "omni.usd_resolver", -]) - -from omni.scene.optimizer.core import ExecutionContext, SceneOptimizerCore -from pxr import Usd - -# Open stage -stage = Usd.Stage.Open(input_path) - -# Attach the stage to an ExecutionContext before direct API calls. -context = ExecutionContext() -context.set_stage(stage) -core = SceneOptimizerCore.getInstance() - -# Verify operations are available -ops = core.getOperations() - -# Execute a single operation -success, error, output = core.executeOperation( - "meshCleanup", - context, - {"mergeVertices": True}, -) -if not success: - raise RuntimeError(error) - -# Or execute a pipeline -pipeline = [ - {"operation": "meshCleanup", "mergeVertices": True}, - {"operation": "optimizeMaterials"}, - {"operation": "pruneLeaves"}, -] -for success, error, output in core.executeConfig(context, pipeline): - if not success: - raise RuntimeError(error) - -# Export optimized output (never overwrite source) -stage.Export(output_path) - -sys.exit(app.shutdown()) -``` - -**Key points:** - -- Cross-check every operation key against `operationsAvailable` in - `setup-preflight.json` before execution. If missing, report - `blocked_missing_so_operation`. -- Probe the selected runtime before writing the script. -- Set `OMNI_KIT_ACCEPT_EULA=yes` in the environment before KitApp import. -- For analysis-only operations, set `context.analysisMode = 1`. -- Operation keys come from the per-operation page's Parameters table and - starting-config JSON. Invalid keys may warn or silently no-op. -- First run may spend minutes fetching extensions from the registry; subsequent - runs use the Kit cache under `~/.local/share/ov/data/Kit/`. - -## Standalone Runtime - -When `setup-preflight.json` indicates standalone, invocation mechanics are -owned by the SO package itself. Resolve the upstream guide: - -1. `$SCENE_OPTIMIZER_PACKAGE_ROOT/.agents/operations/INVOCATION.md` -2. `$SO_HOME/.agents/operations/INVOCATION.md` - -If no package root is available, download and extract the published -`scene_optimizer_core_...release.zip` (direct archive URLs in -`references/upstreams/usd-optimize.md`), or use the package path/URL supplied -by the user. - -**Local responsibilities still apply:** - -- Cross-check every operation key against `operationsAvailable` in - `setup-preflight.json` before execution. If missing, report - `blocked_missing_so_operation`. -- Apply destructive-operation approval gates via `operation-safety.md`. -- Write optimized stages and runtime artifacts under the local output - workspace chosen by setup. - -## Verified Python API Shapes - -Verified against -`scene_optimizer_core_usd_25.11_py_3.12@110.1.0+master.401.324ccecb.gl.manylinux_2_35_x86_64.release`. - -Preferred public JSON API: - -```python -import json -from omni.scene.optimizer.core.scripts import standalone -from pxr import Usd - -stage = Usd.Stage.Open(input_path) -ok = standalone.execute_commands_from_json(stage, json.dumps([ - {"operation": "meshCleanup", "mergeVertices": True}, -])) -if not ok: - raise RuntimeError("Scene Optimizer operation chain failed") -stage.Export(output_path) -``` - -Direct API with per-operation results: - -```python -from omni.scene.optimizer.core import ExecutionContext, SceneOptimizerCore -from pxr import Usd - -stage = Usd.Stage.Open(input_path) -context = ExecutionContext() -context.set_stage(stage) -results = SceneOptimizerCore.getInstance().executeConfig(context, [ - {"operation": "meshCleanup", "mergeVertices": True}, -]) -for success, error, output in results: - if not success: - raise RuntimeError(error) -stage.Export(output_path) -``` - -## Invalid Call Shape - -Do not pass a plain `pxr.Usd.Stage` directly as the second argument to -`SceneOptimizerCore.executeOperation` or `executeConfig`. The binding expects an -`ExecutionContext`; the stage must be attached with `context.set_stage(stage)`. -The bad shape below reproduces the failure seen in Horde testing: - -```python -SceneOptimizerCore.getInstance().executeOperation("printStats", stage, {}) -# AttributeError: 'Stage' object has no attribute '_impl' -``` - -If `_impl` appears in an operation log, stop the operation pass, mark the -attempt as an invalid SO invocation, and rerun through the supported shapes -above. Do not export or report a successful optimized stage from that failed -pass. - -## Save Policy - -- Export optimized output to a NEW `.usdc` path under `/`. - Never overwrite the source stage. -- Use `stage.Export(path)` for clean output. Use `Sdf.Layer.Export()` only - for individual layer cleanup (Phase 4.5). -- Use in-place `Save()` only for newly created layers or explicitly - user-approved source edits. -- Do not flatten unless the user asks for a flattened deliverable. - -## Per-Operation Parameters - -Per-operation parameter tables, defaults, and implementation caveats are owned -by upstream `usd-optimize`. The same package paths listed in the standalone -section above contain the full operation reference. If GitHub raw fetch is -available, the web URL below is acceptable for docs-only reads: - -- [https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/operations/INVOCATION.md](https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/operations/INVOCATION.md) - -Do not clone the source repo just to read docs. diff --git a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/operation-safety.md b/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/operation-safety.md deleted file mode 100644 index 14b07347..00000000 --- a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/operation-safety.md +++ /dev/null @@ -1,158 +0,0 @@ - - - -# Operation Safety - -Use this reference before running any Scene Optimizer chain that may delete, -collapse, regenerate, or otherwise irreversibly change authored content. -Scene Optimizer operation mechanics are owned by upstream -[usd-optimize](https://github.com/NVIDIA-omniverse/usd-optimize/) and the -prebuilt Scene Optimizer package. Resolve guidance from an extracted package -root via `$SCENE_OPTIMIZER_PACKAGE_ROOT`, then `$SO_HOME`. If no package -root exists, download/extract the published `scene_optimizer_core_...release.zip` -package (direct archive URLs are in `references/upstreams/usd-optimize.md`) or -use the package path, URL, or extracted root supplied by the user. Do not clone the -source repo just to read SO guidance. This file owns only the digitaltwin -approval gate and confirmation focus. - -## Confirmation Prompt - -Always prepend the full runtime context block from -`skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md` -Format A. A destructive-op approval must name the Kit application, Scene -Optimizer version, and Asset Validator version that will mutate the stage. - -## Parameter Prerequisites Gate - -Before composing the confirmation prompt for any destructive or bounded-loss -operation, read its YAML frontmatter `parameter_prerequisites` block (in -`references/operations/.md`). - -For each entry: - -- **`field:` entries with `required: true`** — verify the named field exists in - the SA report (`asset_physical_context` section) or `setup-preflight.json`. If - missing, **BLOCK** with reason: `"asset preflight incomplete: missing {field}"`. - Do not proceed to the confirmation prompt. -- **`field:` entries with `required: false`** — if present, use the value to - enrich suggested defaults or context derivation. If absent, proceed normally; - do not block. -- **`elicit_from_user:` entries** — include the `canonical_question` with its - `defaults` as options in the single upfront confirmation prompt. Use the - `conversion` formula to map the user's answer to the SO parameter. If a - `context_derivation` is present and the referenced field is available, use - it to suggest a default. -- **`skip_option`** — always offer the skip option. If the user selects it, - remove that operation from the chain. -- **`default_option`** — if present, this is the pre-selected answer when the - user doesn't express a preference. It does NOT remove the operation (unlike - `skip_option`). - -All `elicit_from_user` questions for a given operation MUST be batched into a -single prompt (the "single upfront prompt" pattern). Do not ask them as -separate mid-run gates. - -### Anti-pattern: rate-framing - -**Do not frame tolerance questions as "reduce by X%" or "how much to keep?"** -unless the user has explicitly provided a target reduction rate (memory budget, -LOD level target, explicit percentage). - -The canonical framing is fidelity-budget: "what detail to preserve?" This maps -to `maxMeanError` which preserves silhouette quality proportional to the -specified tolerance. - -Rate-mode (`reductionFactor` as primary stop) bypasses the silhouette-preserving -default and produces decisions the user cannot evaluate without first seeing -rendered output. It is acceptable ONLY when: - -1. The user explicitly says "reduce to N triangles" or "keep X%", or -2. The workflow is LOD generation with known level targets. - -### Anti-pattern: improvised option sets - -Do not present options that don't trace to a `parameter_prerequisites` block -or a user-supplied constraint. If the agent is about to ask "10% or 25%?", the -contract says: "no — tolerance questions go through the `elicit_from_user` -template; rate questions require explicit user-supplied targets." - -See also: `references/so-run-operations/references/units-and-tolerances.md` for -the shared unit conversion formula and parameter glossary. - -List the destructive operations in the proposed chain, explain what each one -does, then ask for confirmation before invoking the runner. - -## Destructive Or Bounded-Loss Operations - -| Op | Risk | Confirmation focus | -|---|---|---| -| `findOccludedMeshes` → `removePrims` | Deletes internal geometry. | Two-stage: (1) approve T3 analysis cost on SA containment pairs, (2) approve deletion of discovered occluded prims. Exclude transparent enclosures. Runs FIRST in op chain. | -| `deduplicateHierarchies` | Replaces subtrees with instanceable references to shared prototypes. | Confirm dedupe-candidate groups (from hierarchy-dedupe-candidates report). Lossless but structural — changes composition topology. | -| `decimateMeshes` | Drops vertices. | mm tolerance (maxMeanError); applied uniformly to all meshes. See upstream `.agents/operations/decimateMeshes.md`. | -| `fitPrimitives` | Replaces mesh geometry with analytic primitives. | Analysis first and data-preservation intent; see upstream `.agents/operations/fitPrimitives.md`. | -| `removeSmallGeometry` | Removes small meshes. | Threshold, visibility, user intent; see upstream `.agents/operations/removeSmallGeometry.md`. | -| `meshCleanup` with `makeManifold: true` | Repairs topology. | Topology repair vs. simpler cleanup; see upstream `.agents/operations/meshCleanup.md`. | -| `optimizeMaterials` with `convertToColor: true` | Replaces material networks with colors. | Only run on explicit flat-color requests; see upstream `.agents/operations/optimizeMaterials.md`. | -| `removePrims` / `deletePrims` / `removeUntypedPrims` / `deleteHiddenPrims` | Deletes prims. | Affected prim list, variant/runtime visibility, reversible alternatives; see the matching operation reference. | -| `boxClip` | Removes or retains geometry by AABB. | Extent and keep-vs-clip mode; see `references/operations/boxClip.md`. | -| `diceMeshes`, `manifoldMeshes`, `remeshMeshes`, `shrinkwrap` | Regenerates or slices topology. | Grid/voxel settings, topology loss, preview scope. | -| `merge` | Collapses multiple meshes into one or more meshes. | Loss of source hierarchy/path identity and instancing risk. | -| `pythonScript` | Executes user-supplied code. | Require a user-supplied or reviewed script. | -| `removeAttributes` | Removes or blocks attributes. | Exact attribute list and downstream consumers. | -| `sparseMeshes` | Analysis that often drives split/dice follow-ups. | Confirm acting on the analysis result. | - -## Conservative Fallback - -If the user is uncertain, run only `safe-cleanup` first: - -- `computeExtents` -- `pruneLeaves` -- `deduplicateGeometry` -- `optimizeMaterials` -- `optimizeTimeSamples` - -Run destructive or bounded-loss operations as a later pass after the user has -reviewed the safe-cleanup result. - -## Pipeline Notes - -For named pipelines, only `mesh-count-reduction` and `data-quality-baseline` -contain destructive ops today. `safe-cleanup`, `memory-reduction`, and -`load-time-reduction` are lossless. For hierarchy-level dedupe, use -`usd-hierarchy-dedupe-candidates` plus `apply-restructure`; do not substitute -mesh merge for a USD-authored hierarchy rewrite. - -### Anti-pattern: silent deferral of destructive ops - -**Do NOT skip, defer, or omit a destructive op from the plan without the user -explicitly selecting its `skip_option`.** - -If validator findings support a destructive op, present it in the plan with its -`parameter_prerequisites` canonical question and let the user decide. The -workflow contract says: *"Approval for each destructive operation is requested -alongside plan approval."* - -Acceptable: "decimateMeshes is recommended — what's the smallest detail to -preserve? [0.1 / 0.5 / 1.0 / 2.0 / 5.0 mm / skip decimation]" - -Not acceptable: "I'll run lossless ops now and defer lossy ops for later." -That removes user agency. The user may want decimation NOW. - ---- - -## Red Flag: SO Operation Returns Success With Zero Work on Known-Heavy Target - -| Signal | Meaning | -|--------|---------| -| `elapsed_ms: 0` or < 1ms on a target with known high vertex/mesh count | Operation could not find meshes to process | -| `success: true` but vertex_count delta = 0 on a target SA flagged for optimization | Structural blockage, not "nothing to do" | -| Multiple operations show zero work on same target | Almost certainly a traversal issue (Over-spec ancestors, population mask, wrong root prim) | - -**Action:** Do NOT report "operation found nothing to optimize" when SA or manifest -metadata indicates the target should have significant geometry. Instead: - -1. Check specifiers on ancestor prims (Over vs Def) — see `restructure-mode.md` - §"Authoring Requirements" for the diagnostic snippet. -2. Check that the target's `defaultPrim` is set correctly. -3. Check that the stage is not masked or filtered in a way that excludes content. -4. Report the structural issue to the user rather than rationalizing the no-op. diff --git a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md b/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md deleted file mode 100644 index 2cd4aff6..00000000 --- a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md +++ /dev/null @@ -1,42 +0,0 @@ - - - -# Pipeline Recipes - Upstream Handoff - -This local reference preserves the digitaltwin workflow milestone. Scene -Optimizer mechanics for this step are owned by upstream `usd-optimize`. - -- Public repository: [https://github.com/NVIDIA-omniverse/usd-optimize/](https://github.com/NVIDIA-omniverse/usd-optimize/) -- Package path: `.agents/operations/PIPELINES.md` -- Upstream web URL: [https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/operations/PIPELINES.md](https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/operations/PIPELINES.md) - -Resolve the upstream guide without cloning the source repo: - -1. `$SCENE_OPTIMIZER_PACKAGE_ROOT/.agents/operations/PIPELINES.md` -2. `$SO_HOME/.agents/operations/PIPELINES.md` - -If no package root is available, download and extract the published -`scene_optimizer_core_...release.zip` package for the target platform (direct -archive URLs are in `references/upstreams/usd-optimize.md`), or use the package -path/URL supplied by the user. If the user supplies an extracted -package root directly, resolve this same package path under that root. If -GitHub raw fetch is available, the web URL above is acceptable for docs-only -reads. Do not clone the source repo just to read upstream SO guidance. - -## Local Responsibilities - -- Keep workflow phase order, prototype-first ordering, and broad optimization milestone ordering in `workflow.md`. -- Use `config-from-evidence.md` for local evidence-to-request routing and `operation-safety.md` for approvals. -- Use `batch-mode.md` for digitaltwin's agent-orchestrated multi-target policy: adaptive concurrency, dependency-aware target groups, and remainder-script prompts. - -Named pipeline parameters and per-operation defaults belong upstream. If a -digitaltwin workflow needs to cite a chain, cite the upstream path and record -only the local evidence, target set, approval state, and report fields here. - -## Local Routing Keys - -The local workflow may route evidence to these operation keys before handing -mechanics to upstream: `computeExtents`, `decimateMeshes`, -`deduplicateGeometry`, `fitPrimitives`, `generateNormals`, `meshCleanup`, -`optimizeMaterials`, `optimizeTimeSamples`, `pruneLeaves`, `pythonScript`, -`removeSmallGeometry`, and `removeUnusedUVs`. diff --git a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/units-and-tolerances.md b/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/units-and-tolerances.md deleted file mode 100644 index 0865bcc6..00000000 --- a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/units-and-tolerances.md +++ /dev/null @@ -1,94 +0,0 @@ - - - -# Units and Tolerances - -Shared reference for any operation that converts user-specified mm tolerances -to Scene Optimizer stage-unit parameters. Referenced by `operation-safety.md` -and consumed by any `parameter_prerequisites` block with a `conversion` field. - -## Source of Truth - -The `asset_physical_context` section of the SA report provides: - -| Field | Meaning | -|-------|---------| -| `metersPerUnit` | Stage scale factor (1.0 = meters, 0.01 = cm, 0.001 = mm) | -| `upAxis` | Stage orientation (X, Y, or Z) | -| `scale_hint` | Human label: "meters", "centimeters", "millimeters", "other" | - -## Conversion Formula - -``` -tolerance_stage_units = mm_tolerance / (metersPerUnit × 1000) -``` - -### Worked Examples - -| User says | metersPerUnit | Stage units | Result | -|-----------|---------------|-------------|--------| -| "0.5 mm" | 0.01 (cm) | centimeters | 0.5 / (0.01 × 1000) = **0.05** | -| "1.0 mm" | 1.0 (m) | meters | 1.0 / (1.0 × 1000) = **0.001** | -| "2.0 mm" | 0.001 (mm) | millimeters | 2.0 / (0.001 × 1000) = **2.0** | -| "0.1 mm" | 0.01 (cm) | centimeters | 0.1 / (0.01 × 1000) = **0.01** | - -## Elicitation Template - -When asking the user for a physical tolerance, follow this structure: -1. **State the asset's physical scale:** - > "This stage uses {scale_hint} (metersPerUnit = {metersPerUnit})." - -2. **Ask the canonical question** from the operation's `parameter_prerequisites`: - > "{canonical_question}" - -3. **Offer defaults** from the prerequisites block: - > Present the `defaults` array from the operation's `parameter_prerequisites`. - > The user picks one or provides their own value. - -4. **Offer the skip option.** - -## Parameter Glossary - -| SO Parameter | Unit | Range | Meaning | -|-------------|------|-------|---------| -| `maxMeanError` | stage units | 0.0 = disabled | QEM error budget per vertex. Primary quality knob. | -| `reductionFactor` | integer 0–100 | 100 = keep all | Percentage of triangles to **KEEP**, not remove. Secondary stop condition. | -| `maxTriangles` | integer | 0 = disabled | Absolute triangle cap per mesh. | -| `pinBoundaries` | boolean | — | Preserve mesh boundary edges. Always `true` for sub-mesh decimation. | - -**Critical:** `reductionFactor` is "keep percent", NOT "reduce percent". -`reductionFactor: 90` means keep 90% of triangles (remove 10%). - -## Anti-Patterns - -1. **Do NOT ask "reduce by 10%?"** — that's rate-framing. - The canonical question is fidelity-budget: "what detail to preserve?" - See `operation-safety.md § Anti-pattern: rate-framing`. - -2. **Do NOT use integer `0` for disabled float conditions** — use `0.0`. - JSON `"maxMeanError": 0` is ambiguous; `"maxMeanError": 0.0` is explicit. - -3. **Do NOT omit `pinBoundaries: true`** when decimating sub-meshes or - meshes that share boundary edges with neighbors. - -4. **Do NOT invent percentage options** without the user first providing a - rate-based constraint. If the user hasn't said "I want N triangles" or - "keep X%", the tolerance question is the correct entry point. - -5. **Do NOT skip the conversion step.** A user saying "1mm tolerance" on a - centimeter stage means `maxMeanError: 0.1`, not `maxMeanError: 1.0`. - -## Operations That Use This Reference - -Any operation with tolerance knobs benefits from this formula: - -- `decimateMeshes` — `maxMeanError` (primary) -- `deduplicateGeometry` — `tolerance` (coincidence threshold) -- `findCoincidingGeometry` — `tolerance` -- `mergeVertices` — `tolerance` -- `removeSmallGeometry` — `threshold` (min extent in stage units) -- `findSmallGeometry` — `threshold` - -Each operation's `parameter_prerequisites` frontmatter specifies which fields -it needs and what conversion applies. This file owns the shared formula; -individual ops own their specific parameter semantics. diff --git a/skills/omniverse-usd-performance-tuning/references/upstreams/README.md b/skills/omniverse-usd-performance-tuning/references/upstreams/README.md index 6b1244ab..e4421421 100644 --- a/skills/omniverse-usd-performance-tuning/references/upstreams/README.md +++ b/skills/omniverse-usd-performance-tuning/references/upstreams/README.md @@ -1,8 +1,5 @@ # Upstream Source-of-Truth References - - - Pointers to the upstream repositories and prebuilt packages this skill delegates to instead of reimplementing. Operation mechanics, parameters, defaults, and package resolution live upstream; this skill owns only the digital twin workflow @@ -15,9 +12,10 @@ copy of the upstream docs. ## Contents -- [`usd-optimize.md`](usd-optimize.md) — Scene Optimizer operation mechanics and +- [`usd-optimize.md`](usd-optimize.md) — Usd Optimize operation mechanics and prebuilt-package resolution (upstream - [usd-optimize](https://github.com/NVIDIA-omniverse/usd-optimize/)). Resolve - per-operation guides through `$SCENE_OPTIMIZER_PACKAGE_ROOT` / `$SO_HOME` or - the upstream `.agents/operations/.md` path rather than duplicating them - in this repo. + [usd-optimize](https://github.com/NVIDIA-Omniverse/usd-optimize/)). Resolve + per-operation guides through `$USD_OPTIMIZE_ROOT` with the version-tolerant + lookup stated in `usd-optimize.md` (`docs/operations/.rst` on 1.1.x + packages, `.agents/operations/.md` on 1.0.x) rather than duplicating + them in this repo. diff --git a/skills/omniverse-usd-performance-tuning/references/upstreams/usd-optimize.md b/skills/omniverse-usd-performance-tuning/references/upstreams/usd-optimize.md index 15452e62..368db5fb 100644 --- a/skills/omniverse-usd-performance-tuning/references/upstreams/usd-optimize.md +++ b/skills/omniverse-usd-performance-tuning/references/upstreams/usd-optimize.md @@ -1,18 +1,24 @@ - - +# usd-optimize / Usd Optimize Package Handoff -# usd-optimize / Scene Optimizer Package Handoff - -Scene Optimizer operation mechanics are owned by upstream `usd-optimize` and -ship with the prebuilt Scene Optimizer package. This package owns digital twin +Usd Optimize operation mechanics are owned by upstream `usd-optimize` and +ship with the prebuilt Usd Optimize package. This package owns digital twin workflow routing, runtime setup context, validation scope, output workspace policy, batch orchestration, and reporting. -- Public repository: [https://github.com/NVIDIA-omniverse/usd-optimize/](https://github.com/NVIDIA-omniverse/usd-optimize/) -- Prebuilt package pattern: `scene_optimizer_core_usd__py_@..release.zip` -- Linux direct archive: `https://d4i3qtqj3r0z5.cloudfront.net/scene_optimizer_core_usd_25.11_py_3.12%40110.1.0%2Bmaster.401.324ccecb.gl.manylinux_2_35_x86_64.release.zip` -- Windows direct archive: `https://d4i3qtqj3r0z5.cloudfront.net/scene_optimizer_core_usd_25.11_py_3.12%40110.1.0%2Bmaster.401.324ccecb.gl.windows-x86_64.release.zip` -- Package operation guides: `.agents/operations/.md` +- Public repository: [https://github.com/NVIDIA-Omniverse/usd-optimize/](https://github.com/NVIDIA-Omniverse/usd-optimize/) +- Prebuilt packages: **GitHub Releases** on the repository above + (`https://github.com/NVIDIA-Omniverse/usd-optimize/releases`). Each release + carries Linux x86_64, Linux aarch64, and Windows x86_64 zips (~330-360 MB). +- Package pattern: `usd_optimize_usd__py_@..release.zip`. + usd-optimize 1.0.4 is the minimum supported runtime for this skill; 1.1.x is + also supported. The two layouts differ only in where per-operation docs live: + 1.1.x packages ship them at `docs/operations/.rst`, 1.0.x packages at + `.agents/operations/.md`. Operation inventory, arguments, and defaults are + the same across both. +- Download example: + `gh release download v1.0.4 -R NVIDIA-Omniverse/usd-optimize -p '*manylinux*x86_64*'` + (or pick the asset from the releases page in a browser). +- Package operation guides: `docs/operations/.rst` (1.1.x) or `.agents/operations/.md` (1.0.x) - Package operation runner skill: `.agents/skills/run-operations/SKILL.md` - Package validator runner skill: `.agents/skills/run-validators/SKILL.md` - Package validator interpretation skill: `.agents/skills/interpret-validators/SKILL.md` @@ -21,34 +27,45 @@ policy, batch orchestration, and reporting. ## Operation Guide Resolution -For any operation key listed in `references/operations/manifest.json`, derive +For any operation key listed in `references/operations/operations.json`, derive the upstream mechanics path instead of storing per-operation package details in -this repo: - -- Package path template: `.agents/operations/.md` -- Upstream web URL template: `https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/operations/.md` -- Package operation index: `.agents/operations/INDEX.md` - -Resolve local upstream guidance without cloning the source repo: +this repo. Resolve it with a version-tolerant lookup under the selected package +root (`$USD_OPTIMIZE_ROOT`), without cloning the source repo. This is the single +place this rule is stated; other skill files point here. -1. `$SCENE_OPTIMIZER_PACKAGE_ROOT` -2. `$SO_HOME` +- Package path template (prefer): `$USD_OPTIMIZE_ROOT/docs/operations/.rst` + (1.1.x packages). +- Fallback: `$USD_OPTIMIZE_ROOT/.agents/operations/.md` (1.0.x + packages, which predate the auto-generated docs tree). +- Sidecars follow the same rule. Operation index: `docs/operations.rst` (1.1.x) + or `.agents/operations/INDEX.md` (1.0.x). Pipeline/preset guidance: + `docs/choosing-operations.rst` plus `config_presets/*.json` (1.1.x) or + `.agents/operations/PIPELINES.md` (1.0.x). Invocation: `docs/cli.rst` (1.1.x) + or `.agents/operations/INVOCATION.md` (1.0.x). +- Upstream web URL template (1.1.x `main`): + `https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/docs/operations/.rst`. + To document the 1.0.x layout, pin the tag: + `https://github.com/NVIDIA-Omniverse/usd-optimize/blob/1.0.4/.agents/operations/.md`. -Each root above must contain `.agents/operations/INDEX.md` and the runtime -sentinels `python/`, `usdpy/`, `lib/`, and `extraLibs/` when it is also used -for standalone execution. The package may include `.claude` and `.codex` +Each root above must contain the per-operation doc set — `docs/operations/` with +`docs/operations.rst` (1.1.x) or `.agents/operations/INDEX.md` (1.0.x) — plus the +runtime sentinels `python/`, `usdpy/`, `lib/`, and `extraLibs/` when it is also +used for standalone execution. The package may include `.claude` and `.codex` compatibility aliases, but handoffs should use `.agents` paths. If no package root exists, download and extract the published -`scene_optimizer_core_...release.zip` package for the target platform, or use -the package archive path, direct archive URL, or extracted package root -supplied by the user. If web or raw GitHub fetch is available, the public +`usd_optimize_...release.zip` package for the target platform from GitHub +Releases, or use the package archive path, release-asset URL, or extracted +package root supplied by the user. Package-internal paths (`.agents/...`, +`python/`, `usdpy/`, `lib/`, `extraLibs/`) were last verified against the +110.x packages; re-verify against the extracted 1.0.x package on first use. If web or raw GitHub fetch is available, the public repository URL can be used for docs-only reads. Do not clone the source repo just to read operation parameters, defaults, or implementation gotchas. -Local operation files under `references/operations/.md` keep only -routing frontmatter. Use `references/operations/manifest.json` and -`references/operations/_curation.json` for digitaltwin routing, risk, -confirmation, and recommendation posture. Before invoking any operation, consume +Use `references/operations/operations.json` — the single catalog carrying both +routing metadata and the nested `curation` block (generated `status` + +authored `wired_into`; `rationale` only on overrides) — for digitaltwin +routing, risk, confirmation, and recommendation +posture. Before invoking any operation, consume `/setup-preflight.json` and confirm the op appears in -`sceneOptimizer.operationsAvailable`. +`usdOptimize.operationsAvailable`. diff --git a/skills/omniverse-usd-performance-tuning/references/so-run-operations/README.md b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/README.md similarity index 70% rename from skills/omniverse-usd-performance-tuning/references/so-run-operations/README.md rename to skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/README.md index 07a94aac..57588d91 100644 --- a/skills/omniverse-usd-performance-tuning/references/so-run-operations/README.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/README.md @@ -1,22 +1,18 @@ - - - -# so-run-operations - Local Execution Policy and Upstream Handoff +# usd-optimize-run-operations - Local Execution Policy and Upstream Handoff This local reference preserves the digitaltwin workflow milestone. Scene Optimizer mechanics for this step are owned by upstream `usd-optimize`. -- Public repository: [https://github.com/NVIDIA-omniverse/usd-optimize/](https://github.com/NVIDIA-omniverse/usd-optimize/) +- Public repository: [https://github.com/NVIDIA-Omniverse/usd-optimize/](https://github.com/NVIDIA-Omniverse/usd-optimize/) - Package path: `.agents/skills/run-operations/SKILL.md` -- Upstream web URL: [https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/skills/run-operations/SKILL.md](https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/skills/run-operations/SKILL.md) +- Upstream web URL: [https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/.agents/skills/run-operations/SKILL.md](https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/.agents/skills/run-operations/SKILL.md) Resolve the upstream guide without cloning the source repo: -1. `$SCENE_OPTIMIZER_PACKAGE_ROOT/.agents/skills/run-operations/SKILL.md` -2. `$SO_HOME/.agents/skills/run-operations/SKILL.md` +1. `$USD_OPTIMIZE_ROOT/.agents/skills/run-operations/SKILL.md` +2. `$USD_OPTIMIZE_ROOT/.agents/skills/run-operations/SKILL.md` -If no package root is available, download and extract the published -`scene_optimizer_core_...release.zip` package for the target platform (direct +If no package root is available, download and extract the prebuilt Usd Optimize release package (current asset name + download: `references/upstreams/usd-optimize.md`) (direct archive URLs are in `references/upstreams/usd-optimize.md`), or use the package path/URL supplied by the user. If the user supplies an extracted package root directly, resolve this same package path under that root. If @@ -26,15 +22,14 @@ reads. Do not clone the source repo just to read upstream SO guidance. ## Local Responsibilities - Run the session runtime gate from `setup-usd-performance-tuning/references/runtime-context-header.md` and consume `/setup-preflight.json`. -- Cross-check every planned op key against `sceneOptimizer.operationsAvailable`; block with `blocked_missing_scene_optimizer` or `blocked_missing_so_operation` when required. +- Cross-check every planned op key against `usdOptimize.operationsAvailable`; block with `blocked_missing_usd_optimize` or `blocked_missing_usd_optimize_operation` when required. - Apply local output workspace policy and `runtime-artifact-token-budget.md`; keep logs on disk and read bounded summaries only. - Apply destructive-operation approval gates via `references/operation-safety.md` before mutation. - Keep digitaltwin evidence-to-config routing in `references/config-from-evidence.md`. - Treat `references/invocation.md` as the only local source of truth for Python/API invocation shapes. -- For Phase 4b multi-target optimization, use `references/batch-mode.md` for target enumeration, adaptive concurrency, prototype-first ordering, hash-based output names, resource observations, and remainder-script prompts. -- Preserve logical milestone name `so-run-operations` and hand results to profile/compare/report phases. - +- For Phase 4b multi-target optimization, use `references/batch-mode.md` for target enumeration, adaptive concurrency, prototype-first ordering, hash-based output names, resource observations, status artifacts, and resume prompts. +- Preserve logical milestone name `usd-optimize-run-operations` and hand results to profile/compare/report phases. ## Pre-flight Checklist @@ -43,7 +38,7 @@ Before executing the op chain, re-read and confirm: - [ ] `references/operation-safety.md` — parameter prerequisites gate, confirmation prompt format, destructive-op approval policy. - [ ] Every op key cross-checked against `setup-preflight.json` - `sceneOptimizer.operationsAvailable`. + `usdOptimize.operationsAvailable`. - [ ] Per-op `parameter_prerequisites` frontmatter read for each destructive op. - [ ] `references/units-and-tolerances.md` — conversion formula for any tolerance-based op. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/batch-mode.md b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/batch-mode.md new file mode 100644 index 00000000..44e732dd --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/batch-mode.md @@ -0,0 +1,166 @@ +# Scheduler-Backed Batch Mode + +This is Phase 4b of the canonical workflow. The deterministic mechanics are +scheduler-backed (`usd-optimize-run-operations/scripts/run_batch.py`); the agent still decides +concurrency, tags, and op chains. Optional helper wrappers accept one asset +path; the agent writes a batch plan and the scheduler runs the targets. + +Do not serialize independent optimization targets by default. Run them in +adaptive batches sized by target weight and available system resources, then +adjust concurrency after each completed batch. + +## Runner (resource-aware scheduler) + +The deterministic mechanics of this pattern are owned by +`usd-optimize-run-operations/scripts/run_batch.py`. The split is: the **agent decides** (stays +prose) `max_workers` from the resource budget, the `archetype` tags, which op +chains, and the intent-gated opt-ins; the **runner owns** (deterministic tool) +spawning standalone single-asset workers, dependency ordering (prototype-first), +per-target/per-op timeouts, the GPU-cliff guard, status emission, and `--resume`. + +- **The plan and status artifacts are both contracts.** The runner reads the + batch plan (schema: `usd-optimize-run-operations/scripts/batch-plan.schema.json`) and writes + `status.json` (schema: `usd-optimize-run-operations/scripts/status.schema.json`); CLI bars and any + future dashboard are *views* over the status. The plan makes the descent → + apply-restructure manifest → scheduler handoff a real contract — **one target = + one own-layer file = one job** — and the manifest `phase4_targets[]` frontier + metadata (`role`/`target_class`, `level`, `archetype`) flows into per-target + jobs. Invoke with `--plan ` `--max-workers N` and optionally + `--preflight ` (CUDA signal) or + `--cuda available|unavailable`. +- **`state: done` is NOT coverage `disposition: optimized`.** Worker completion + proves the op ran, not that it changed anything. The runner records per-target + before/after deltas (from each worker's `summary_path`) and derives + `disposition` (`optimized` only on a real delta; `no_op` when unchanged; + `unknown` when no summary). The Phase-4e `target_coverage.entries[]` / + `coverage_ledger` are built from `disposition`, never from bare `done`. +- **Per-target/per-rule timeout:** every worker runs under + `subprocess.run(timeout=...)`; a hung worker is killed (`state: timeout`, a + distinct outcome from a worker that ran to a non-zero exit `state: failed`) + without stalling the rest of the batch. Each target also records + `duration_seconds` and `exit_code`. Scoped validator probes invoked through + `usd_validation_executor.py` carry the same timeout contract. +- **GPU-cliff guard:** `gpu_bound` targets are skipped + (`state: skipped_gpu_unavailable`) on a CPU-only/WSL host. CUDA is read from + the setup-preflight `runtime_context`, **not** from SO's own `hasNvidiaGpu()`, + and the signal fails closed (absent ⇒ treated as CPU-only) so a GPU op never + silently enters a long CPU fallback. +- **`--resume` replaces the remainder script:** resuming off `status.json` + re-runs only targets whose state is not terminal (`done` / + `skipped_gpu_unavailable`). +- Workers are standalone single-asset processes (optimization/validation never + uses Kit; standalone is the sole optimization runtime). The opt-in Kit→omniperf profiling path is capped to 1-2 + runs and sits outside this worker fan-out. + +## Edit-target invariant (why per-target parallelizes) + +The full rule — own-layer edit target, never optimize a referenced library +through the composed assembly, `Class → Def` de-classing, standalone-resolvable +libraries — lives in +[restructure-mode.md § Edit-Target Invariant](../../usd-structure-assessment/references/apply-restructure/references/restructure-mode.md#edit-target-invariant-never-optimize-through-a-reference). + +What matters here: because each target is its own root layer, **one target = one +own-layer file = one job**, and that is precisely *why* per-target work +parallelizes. The scheduler fans these independent jobs out. + +## Targets + +Targets come from: + +- `apply-restructure` mode=`restructure`: prototype USDs, shared layers, and + newly loadable sub-assets recorded in + `/apply-restructure-manifest.json` `phase4_targets[]`, plus any + `target_class: "assembly_root"` entry for mesh data retained in the assembly. + Do not filter the manifest to prototype files only. +- Composed stages with no restructure: referenced sub-assets from + `usd-structure-assessment` Phase 1.2 `assets.manifest`. +- Monolithic-as-is: the original stage (`N=1`). + +## Adaptive Concurrency + +Use target count only after estimating target weight. A fixed target-count cap +is too conservative for small mechanical parts and too aggressive for large +floor-scale facility sections. + +Before the first batch, build a lightweight batch manifest: + +- Independent target list, grouped by dependency class. +- Per-target weight signals: file size, mesh count, vertex/face count, + material/texture count, prototype/instance count, and expected op-chain cost. +- Resource budget: CPU cores, available RAM, available VRAM when Kit/rendering + is involved, free disk, and expected log/artifact volume. +- Initial concurrency choice and reason. + +Initial concurrency guidance: + +| Target class | Starting point | +|---|---| +| Monolithic target | `1` | +| Heavy facility/floor-scale target, multi-GB target, or high mesh/texture count | `1`, then increase only after a healthy pilot | +| Medium sub-assets | `2-4` depending on memory and disk headroom | +| Small mechanical parts or small fixture libraries | Start above `5` when resources allow; use CPU, memory, disk, and log headroom rather than the old fixed cap | +| Unknown weight | Start conservatively at `2`, or `1` if opening one target already consumes significant memory | + +After each batch, inspect duration, failed targets, peak RAM/VRAM if available, +disk growth, log size, and output count. Increase concurrency when the pilot is +healthy and targets are small. Decrease concurrency or switch to serial when a +batch hits memory pressure, GPU pressure, disk/log pressure, runtime crashes, +or long-tail target variance. + +If the remaining work is likely to exceed the user's time/resource budget, pause +and ask whether to continue, resume later from `status.json`, or stop. Do not +pause solely because target count exceeds five; pause because the observed budget +or risk says continuing automatically is unsafe. + +## Prototype-First Ordering + +When targets include prototypes and non-prototype assets, run prototypes first, +wait for completion, then run non-prototype assets. Parallelize within each +dependency group according to the adaptive concurrency policy. Prototype changes +propagate to instances, so running instance-site work first wastes time. Treat +an `assembly_root` target with retained meshes as a non-prototype mesh target: +run the evidence-selected per-target mesh op chain on it before final +assembled-root cleanup. + +## Output Naming + +Hash the absolute input path in every per-target output, summary, and log +filename. Basename-only naming is unsafe because many industrial scenes contain +repeated names such as `Body.usd` or `Default_V5.usd`. + +Recommended pattern: + +```text +..optimized.usdc +..summary.json +..log +``` + +After every batch, verify that the number of produced optimized files matches +the number of targets in that batch. If not, report a collision or failed write +instead of declaring success. + +## Resume Prompt + +When the adaptive budget says the remaining work should not continue +automatically, show: + +- Already optimized targets (terminal in `status.json`). +- Deferred targets (still `queued`). +- Observed runtime/resource pressure from completed batches. +- The `status.json` path to resume from. +- Options: resume the remaining targets now (`run_batch.py --resume`), stop here, + or explicitly optimize all remaining targets anyway. + +Default behavior is to stop until the user chooses; the resource budget is the +guardrail. `--resume` re-runs only the non-terminal targets, so there is no +improvised remainder script to generate. + +## Failure Handling + +Aggregate per-target summaries into one batch summary. Surface failed targets +with log and summary paths. Do not auto-retry failed targets. + +The final batch manifest should record every batch's target list, concurrency, +duration, output paths, summary/log paths, failures, resource observations, and +the reason for any concurrency adjustment. diff --git a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/config-from-evidence.md b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/config-from-evidence.md similarity index 61% rename from skills/omniverse-usd-performance-tuning/references/so-run-operations/references/config-from-evidence.md rename to skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/config-from-evidence.md index 3147f26d..884c3c89 100644 --- a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/config-from-evidence.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/config-from-evidence.md @@ -1,6 +1,3 @@ - - - # Config From Evidence Use this reference when the user has validator findings, structure assessment, @@ -8,11 +5,11 @@ profile metrics, renderer metrics, or runtime symptoms and asks for an operation chain. Validator findings are one evidence source; they are not the only way to compose a responsible recipe. -Scene Optimizer operation mechanics are owned by upstream -[usd-optimize](https://github.com/NVIDIA-omniverse/usd-optimize/) and the -prebuilt Scene Optimizer package. Resolve guidance from an extracted package -root via `$SCENE_OPTIMIZER_PACKAGE_ROOT`, then `$SO_HOME`. If no package -root exists, download/extract the published `scene_optimizer_core_...release.zip` +Usd Optimize operation mechanics are owned by upstream +[usd-optimize](https://github.com/NVIDIA-Omniverse/usd-optimize/) and the +prebuilt Usd Optimize package. Resolve guidance from an extracted package +root via `$USD_OPTIMIZE_ROOT`. If no package +root exists, download/extract the published the prebuilt Usd Optimize release package (current asset name + download: `references/upstreams/usd-optimize.md`) package (direct archive URLs are in `references/upstreams/usd-optimize.md`) or use the package path, URL, or extracted root supplied by the user. Do not clone the source repo just to read SO guidance. @@ -20,9 +17,11 @@ the source repo just to read SO guidance. ## Checklist 1. **Internal geometry removal (runs FIRST when evidence exists).** - - Evidence: SA `flagged_assets` with `reason: containment` AND - `enclosure_opaque: true`. These are opaque-enclosed asset pairs - (equipment, machines, vehicles, cabinets, housings). + - Evidence: SA `validation_scope.cross_component_pairs` that aren't + explicitly transparent (`enclosure_opaque` true or unset). These are + (likely) opaque-enclosed boundary pairs (equipment, machines, vehicles, + cabinets, housings), nominated from `asset_boundary_suggestions.boundaries[]` + via `candidate_source` hash OR semantics — bbox overlap is confirmation-only. - Chain: `findOccludedMeshes` (analysis on scoped pairs) → `removePrims` (delete confirmed-occluded paths). - Ordering: this pair runs BEFORE all other ops — no point cleaning, @@ -30,11 +29,12 @@ the source repo just to read SO guidance. - Exclusion: skip pairs where enclosure has transparent material (opacity < 1.0, glass shader, transmission). Those internals are visible through the enclosure. - - Two-stage approval: (1) confirm analysis cost (T3), (2) confirm - deletion of discovered internals. + - Approval: the scoped probe runs in Phase 4 without approval (bounded T3 + detection); only the deletion of discovered internals is intent-gated + (Phase 7 iteration-2 opt-in). - If no containment pairs exist or all are transparent, skip this step. 2. **Read the remaining evidence.** - - `so-interpret-validators` report. The Operation column lists the operation + - `usd-optimize-interpret-validators` report. The Operation column lists the operation key for each firing rule. - `usd-structure-assessment` summary counts, flagged assets, references, payloads, prototype/instance counts, material counts, and mesh-size @@ -45,9 +45,11 @@ the source repo just to read SO guidance. cardinality measured by `rtxMeshCount`, GPU memory, triangle count, draw calls, open/load time, disk size, or validation blockers. 4. **Choose an existing recipe or synthesize one.** Use - upstream `usd-optimize/.agents/operations/PIPELINES.md` for operation roles - and dependency ordering. Keep only local evidence, target set, approval - state, and report fields here. + upstream `usd-optimize/docs/choosing-operations.rst` (with + `config_presets/*.json`; on 1.0.x packages `.agents/operations/PIPELINES.md`) + for operation roles and dependency ordering — see the resolution rule in + `references/upstreams/usd-optimize.md`. Keep only local evidence, target set, + approval state, and report fields here. 5. **Apply validator-tier discipline when validator findings are present.** Include Tier 1 rules with defaults, include Tier 2 only with an iteration note, and never auto-include Tier 3 rules without manual review. @@ -58,9 +60,11 @@ the source repo just to read SO guidance. `removeSmallGeometry`, merge/resource-cardinality fixes, or structure changes first. Add decimation only after the user confirms the reduction goal. -8. **Build the JSON config.** Read each operation's upstream - `usd-optimize/.agents/operations/.md` guide for parameter names, - defaults, and risky fields before emitting the final chain. +8. **Build the JSON config.** Read each operation's upstream per-op guide + (`usd-optimize/docs/operations/.rst` on 1.1.x packages, or + `.agents/operations/.md` on 1.0.x; resolution in + `references/upstreams/usd-optimize.md`) for parameter names, defaults, and + risky fields before emitting the final chain. 9. **Prepare the user-facing rationale.** Name the evidence each step addresses, why the order matters, which steps are destructive or bounded-loss, and which before/after metrics will prove the recipe worked. @@ -80,5 +84,7 @@ Before running, show: For execution-context flags, operation argument syntax, named pipelines, and analysis-mode mechanics, use upstream `usd-optimize/.agents/skills/run-operations/SKILL.md` and -`usd-optimize/.agents/operations/INVOCATION.md`. For read-only "what would this -do?" analysis, prefer `so-run-validators` and upstream validator docs. +`usd-optimize/docs/cli.rst` (on 1.0.x packages `.agents/operations/INVOCATION.md`; +resolution in `references/upstreams/usd-optimize.md`). For read-only "what would +this do?" analysis, prefer `usd-optimize-run-validators` and upstream validator +docs. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/invocation.md b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/invocation.md new file mode 100644 index 00000000..02bed72d --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/invocation.md @@ -0,0 +1,100 @@ +# Invocation Reference + +How to execute Usd Optimize operations once the runtime is selected and the +operation plan is approved. Read `/setup-preflight.json` to +determine which runtime and API surface to use. + +This is the local source of truth for Usd Optimize operation invocation. +Other workflow docs should link here instead of repeating Python API snippets. + +**Standalone is the sole runtime that executes operations.** Kit is not an +operation-execution runtime; it is retained only as an opt-in render-profiling +adjunct (Kit→omniperf, see `workflow.md` Phase 1a/6a) and never runs Scene +Optimizer operations. Do not bootstrap `KitApp` to execute ops. + +## Standalone Runtime + +When `setup-preflight.json` indicates standalone, invocation mechanics are +owned by the Usd Optimize package itself. Resolve the upstream guide with the +version-tolerant lookup stated in `references/upstreams/usd-optimize.md`: + +1. `$USD_OPTIMIZE_ROOT/docs/cli.rst` (1.1.x packages) +2. `$USD_OPTIMIZE_ROOT/.agents/operations/INVOCATION.md` (1.0.x fallback) + +If no package root is available, download and extract the published +the prebuilt Usd Optimize release package (asset name + download in +`references/upstreams/usd-optimize.md`), or use the package path/URL supplied +by the user. + +**Local responsibilities still apply:** + +- Cross-check every operation key against `operationsAvailable` in + `setup-preflight.json` before execution. If missing, report + `blocked_missing_usd_optimize_operation`. +- Apply destructive-operation approval gates via `operation-safety.md`. +- Write optimized stages and runtime artifacts under the local output + workspace chosen by setup. + +## Verified Python API Shapes + +Verified against the `usd_optimize_...@1.0.4` GitHub release asset +(2026-06-11; current asset resolution: `references/upstreams/usd-optimize.md`). +Import from `usd_optimize.core`; the `omni.scene.optimizer.core` module path +and the `SceneOptimizerCore` class name survive upstream only as deprecated +aliases and must not appear in new configs. + +Direct API with per-operation results (1.0.4-verified shape): + +```python +from usd_optimize.core import ExecutionContext, UsdOptimizeCore +from pxr import Usd + +stage = Usd.Stage.Open(input_path) +context = ExecutionContext() +context.set_stage(stage) +results = UsdOptimizeCore.getInstance().executeConfig(context, [ + {"operation": "meshCleanup", "mergeVertices": True}, +]) +for success, error, output in results: + if not success: + raise RuntimeError(error) +stage.Export(output_path) +``` + +## Invalid Call Shape + +Do not pass a plain `pxr.Usd.Stage` directly as the second argument to +`SceneOptimizerCore.executeOperation` or `executeConfig`. The binding expects an +`ExecutionContext`; the stage must be attached with `context.set_stage(stage)`. +The bad shape below reproduces the failure seen in Horde testing: + +```python +SceneOptimizerCore.getInstance().executeOperation("printStats", stage, {}) +# AttributeError: 'Stage' object has no attribute '_impl' +``` + +If `_impl` appears in an operation log, stop the operation pass, mark the +attempt as an invalid SO invocation, and rerun through the supported shapes +above. Do not export or report a successful optimized stage from that failed +pass. + +## Save Policy + +- Export optimized output to a NEW `.usdc` path under `/`. + Never overwrite the source stage. +- Use `stage.Export(path)` for clean output. Use `Sdf.Layer.Export()` only + for individual layer cleanup (Phase 4.5). +- Use in-place `Save()` only for newly created layers or explicitly + user-approved source edits. +- Do not flatten unless the user asks for a flattened deliverable. + +## Per-Operation Parameters + +Per-operation parameter tables, defaults, and implementation caveats are owned +by upstream `usd-optimize`. The same package paths listed in the standalone +section above contain the full operation reference. If GitHub raw fetch is +available, the web URL below is acceptable for docs-only reads: + +- [https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/docs/cli.rst](https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/docs/cli.rst) + +Do not clone the source repo just to read docs. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/operation-safety.md b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/operation-safety.md new file mode 100644 index 00000000..41e14ff4 --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/operation-safety.md @@ -0,0 +1,275 @@ +# Operation Safety + +Use this reference before running any Usd Optimize chain that may delete, +collapse, regenerate, or otherwise irreversibly change authored content. +Usd Optimize operation mechanics are owned by upstream +[usd-optimize](https://github.com/NVIDIA-Omniverse/usd-optimize/) and the +prebuilt Usd Optimize package. Resolve guidance from an extracted package +root via `$USD_OPTIMIZE_ROOT`. If no package +root exists, download/extract the published the prebuilt Usd Optimize release package (current asset name + download: `references/upstreams/usd-optimize.md`) +package (direct archive URLs are in `references/upstreams/usd-optimize.md`) or +use the package path, URL, or extracted root supplied by the user. Do not clone the +source repo just to read SO guidance. This file owns only the digitaltwin +approval gate and confirmation focus. + +## Confirmation Prompt + +Always prepend the full runtime context block from +`skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md` +Format A. A destructive-op approval must name the Kit application, Scene +Optimizer version, and usd-validation-nvidia version that will mutate the stage. + +## Parameter Prerequisites Gate + +Before composing the confirmation prompt for any destructive or bounded-loss +operation, read its YAML frontmatter `parameter_prerequisites` block (in +`references/operations/.md`). + +For each entry: + +- **`field:` entries with `required: true`** — verify the named field exists in + the SA report (`asset_physical_context` section) or `setup-preflight.json`. If + missing, **BLOCK** with reason: `"asset preflight incomplete: missing {field}"`. + Do not proceed to the confirmation prompt. +- **`field:` entries with `required: false`** — if present, use the value to + enrich suggested defaults or context derivation. If absent, proceed normally; + do not block. +- **`elicit_from_user:` entries** — include the `canonical_question` with its + `defaults` as options in the single upfront confirmation prompt. Use the + `conversion` formula to map the user's answer to the Usd Optimize parameter. If a + `context_derivation` is present and the referenced field is available, use + it to suggest a default. +- **`skip_option`** — always offer the skip option. If the user selects it, + remove that operation from the chain. +- **`default_option`** — if present, this is the pre-selected answer when the + user doesn't express a preference. It does NOT remove the operation (unlike + `skip_option`). + +All `elicit_from_user` questions for a given operation MUST be batched into a +single prompt (the "single upfront prompt" pattern). Do not ask them as +separate mid-run gates. + +### Anti-pattern: rate-framing + +**Do not frame tolerance questions as "reduce by X%" or "how much to keep?"** +unless the user has explicitly provided a target reduction rate (memory budget, +LOD level target, explicit percentage). + +The canonical framing is fidelity-budget: "what detail to preserve?" This maps +to `maxMeanError` which preserves silhouette quality proportional to the +specified tolerance. + +Rate-mode (`reductionFactor` as primary stop) bypasses the silhouette-preserving +default and produces decisions the user cannot evaluate without first seeing +rendered output. It is acceptable ONLY when: + +1. The user explicitly says "reduce to N triangles" or "keep X%", or +2. The workflow is LOD generation with known level targets. + +### Anti-pattern: improvised option sets + +Do not present options that don't trace to a `parameter_prerequisites` block +or a user-supplied constraint. If the agent is about to ask "10% or 25%?", the +contract says: "no — tolerance questions go through the `elicit_from_user` +template; rate questions require explicit user-supplied targets." + +See also: `references/usd-optimize-run-operations/references/units-and-tolerances.md` for +the shared unit conversion formula and parameter glossary. + +List the destructive operations in the proposed chain, explain what each one +does, then ask for confirmation before invoking the runner. + +## Destructive Or Bounded-Loss Operations + +| Op | Risk | Confirmation focus | +|---|---|---| +| `findOccludedMeshes` → `removePrims` | Deletes internal geometry. | Two-stage, and the stages split on AUTHORITY not cost: (1) the scoped probe on SA containment pairs runs WITHOUT approval — cost is bounded by scope + `timeout_recorded`; (2) the deletion of discovered occluded prims is intent-gated (the agent cannot know whether the twin needs its internals), so present it on the opt-in menu. Exclude transparent enclosures. The scoped probe runs in Phase 4 (no approval); when the deletion is opted into, it runs FIRST among that target's applies. | +| `deduplicateHierarchies` | Replaces subtrees with instanceable references to shared prototypes. | Confirm dedupe-candidate groups (from hierarchy-dedupe-candidates report). Lossless but structural — changes composition topology. Invoke per frontier region: `paths` scoped to that region plus a per-region `maxDepth` to control grain; never one stage-wide `maxDepth` across branches (see the `deduplicateHierarchies` operations catalog entry). Placement-correct by construction: root `xformOp:*` excluded from identity, duplicate local transform preserved. | +| `decimateMeshes` | Drops vertices. | mm tolerance (maxMeanError); applied uniformly to all meshes. See upstream `docs/operations/decimateMeshes.rst`. | +| `fitPrimitives` | Replaces mesh geometry with analytic primitives. | Analysis first and data-preservation intent; see upstream `docs/operations/fitPrimitives.rst`. | +| `removeSmallGeometry` | Removes small meshes. | Threshold, visibility, user intent; see upstream `docs/operations/removeSmallGeometry.rst`. | +| `meshCleanup` with `makeManifold: true` | Repairs topology. | Topology repair vs. simpler cleanup; see upstream `docs/operations/meshCleanup.rst`. | +| `optimizeMaterials` with `convertToColor: true` | Replaces material networks with colors. | Only run on explicit flat-color requests; see upstream `docs/operations/optimizeMaterials.rst`. | +| `removePrims` / `deletePrims` / `removeUntypedPrims` / `deleteHiddenPrims` | Deletes prims. | Affected prim list, variant/runtime visibility, reversible alternatives; see the matching operation reference. | +| `boxClip` | Removes or retains geometry by AABB. | Extent and keep-vs-clip mode; see the `boxClip` entry in `references/operations/README.md` and the upstream handoff. | +| `diceMeshes`, `manifoldMeshes`, `remeshMeshes`, `shrinkwrap` | Regenerates or slices topology. | Grid/voxel settings, topology loss, preview scope. | +| `merge` | Collapses multiple meshes into one or more meshes. | Loss of source hierarchy/path identity and instancing risk. | +| `pythonScript` | Executes user-supplied code. | Require a user-supplied or reviewed script. | +| `removeAttributes` | Removes or blocks attributes. | Exact attribute list and downstream consumers. | +| `sparseMeshes` | Analysis that often drives split/dice follow-ups. | Confirm acting on the analysis result. | + +## Apply authority: auto vs intent-gated routing + +The axis that decides "needs a user decision" is **authority + reversibility, not +compute cost**. A scoped analysis probe is cost-bounded and runs without approval; +*applying* a result that deletes geometry or collapses identity needs the user, +because only they know the digital twin's purpose (a showroom exterior render can +drop an engine; a service/training/CFD twin cannot; a maintenance twin needs +per-instance selection, a viz twin does not). Cost is orthogonal — PointInstancer +conversion is cheap to analyze but identity-losing to apply. + +Each op's **base** apply-authority class is machine-readable as the +`apply_authority` field on every entry in +`references/operations/operations.json` (enum `auto` / `auto-within-tolerance` / +`intent-gated`). That catalog field is the single source a data-driven consumer +(status derivation, the scheduler, interpret-validators) reads to DERIVE the +class; this section is the canonical *explanation* of what each class means and +owns the **target-conditional** gating rule the static field cannot express. The +field encodes only the BASE class and is cross-checked against +`requires_confirmation` (`requires_confirmation == (apply_authority != "auto")`): +`auto` never gates; `intent-gated` and `auto-within-tolerance` both carry +`requires_confirmation: true`, because `auto-within-tolerance` keeps the +conservative flag set until a target is confirmed visually-toleranced at the +conservative band (see the downgrade rule below). There are **three** +apply-authority classes: + +- **`auto` (lossless — not in the table above):** `removeUnusedUVs`, + `deduplicateGeometry`, `optimizeMaterials` dedup, `computeExtents`, + `pruneLeaves`, `optimizeTimeSamples`. Run in **iteration 1** per target, no + prompt, unattended-friendly. (`meshCleanup` invoked **weld-only** also runs + here — see the sub-mode note below — but its catalog BASE class is + `intent-gated`, not `auto`, because the full op bundles topology-repair + sub-modes that need a decision.) +- **`auto-within-tolerance` (bounded-loss × conservative per-target band × + visually-toleranced target):** the bounded-loss ops with a deviation parameter + (`decimateMeshes`, `fitPrimitives`) run with a **one-line notice, not a + prompt**, when ALL of these hold: (a) the op runs at the *conservative* + per-target scale band (resolved per target from its extent — see + `units-and-tolerances.md`), and (b) the target is **visually-toleranced** (no + functional-precision signal). This is the deliberate mild bounded-loss default + that guards against under-optimization (the ludicrously-over-tessellated mesh + that a pure opt-in menu lets sail through). The notice names the op, the + per-target band, and that deviation is bounded to the band. +- **intent-gated (in the table above):** never silently dropped; always presented + for an explicit decision. A bounded-loss op drops from `auto-within-tolerance` + back to **intent-gated** whenever (a) it would run **above the conservative + band** (more aggressive deviation), OR (b) the target carries a + **functional-precision signal** — `articulated` / physics / sim-ready / + metrology / variant-bearing — because the band measures *visual* deviation, not + *functional* tolerance (mating faces, collision/airflow surfaces, kinematic + features); when the signal is ambiguous, fall back to intent-gated. The + functional-tolerance signal is read from SA semantics + the existing + `importance` / `articulated` target-tree tags — **not a new closed + archetype enum**. Routes: + - **Inline-elicited** (`decimateMeshes`, `fitPrimitives` when above-band or on + a functional-precision target): offered in-plan through their + `parameter_prerequisites` (fidelity budget, data-preservation intent). The + tolerance question carries the authority. + - **Purpose/identity-gated** (`findOccludedMeshes`→`removePrims`, + `removeSmallGeometry`, `merge`, `optimizeMaterials`+`convertToColor`, + PointInstancer-convert): identity-losing — no tolerance can bound them, so + they stay intent-gated for ALL archetypes. Presented as the **batched + per-asset opt-in menu in Phase 7 iteration 2**, with win AND loss quantified + per asset. The scoped detection probe (e.g. `findOccludedMeshes`) runs earlier + in Phase 4 without approval — its result quantifies the menu; only the + destructive apply fires on opt-in. + +The real authority boundary is **above-band / identity-losing / functional-precision +target**, not lossless-vs-lossy. A bounded-loss op at the conservative band on a +visually-toleranced target is `auto-within-tolerance` (notice); the same op above +the band, or on an articulated/physics/sim-ready target, is `intent-gated` +(prompt). This `auto-within-tolerance` → `intent-gated` downgrade is +**target-conditional, not op-static**, so it is deliberately NOT written into the +per-op `apply_authority` field (which carries the BASE class only): it is applied +at plan time from SA semantics + the `importance` / `articulated` target-tree tags. + +**`meshCleanup` is sub-mode-conditional (the same pattern, on a different axis).** +Its catalog BASE `apply_authority` is `intent-gated` because the full op bundles +topology-repair sub-modes (`makeManifold`, isolated/degenerate removal — see the +destructive table) that change geometry and need a decision. But the +**vertex-weld-only** invocation — the default Phase-4 step-1 use, welding +coincident verts within tolerance — is lossless and **effectively `auto`**: it +runs unattended in iteration 1 alongside the other lossless ops. As with the +`auto-within-tolerance` downgrade, this weld-only-is-auto nuance is +**invocation-conditional, not op-static**, so it is deliberately NOT written into +the per-op `apply_authority` field (which carries the conservative BASE class +only); the prose owns it. `requires_confirmation: true` stays set on the catalog +entry because the conservative base holds until a weld-only invocation is the +confirmed scope — the same reason `auto-within-tolerance` keeps its flag set. + +### Caveat: `pruneLeaves` on unloaded payloads + +`pruneLeaves` removes prims that have no children. A prim whose **payload is +authored but not loaded** presents as a childless leaf, because its real +children live inside the unloaded payload — so `pruneLeaves` will delete it and +silently lose that content. `pruneLeaves` must NOT target prims with unloaded +payloads. Before pruning, either **load the payloads** across the target subtree +so the real children are visible, or **exclude prims that have unloaded payloads** +from the prune target set. Never let an unloaded-payload prim be mistaken for an +empty leaf. + +## Conservative Fallback + +If the user is uncertain, run only `safe-cleanup` first: + +- `computeExtents` +- `pruneLeaves` +- `deduplicateGeometry` +- `optimizeMaterials` +- `optimizeTimeSamples` + +Run destructive or bounded-loss operations as a later pass after the user has +reviewed the safe-cleanup result. + +## Pipeline Notes + +For named pipelines, only `mesh-count-reduction` and `data-quality-baseline` +contain destructive ops today. `safe-cleanup`, `memory-reduction`, and +`load-time-reduction` are lossless. For hierarchy-level dedupe, use +`usd-hierarchy-dedupe-candidates` plus `apply-restructure`; do not substitute +mesh merge for a USD-authored hierarchy rewrite. + +`merge` (Merge Static Meshes) is a different, complementary tool: a **draw-call +within-prototype** op — fuse small adjacent meshes inside a prototype so +the win propagates to every instance. It is **not** a disk lever (merge +concatenates geometry; bytes ~= sum, and the crate already byte-dedups within a +layer), and it is only eligible on **spatially-coherent, weak/none-identity** +clusters: merging dispersed meshes balloons the AABB and degrades BVH/raytracing. +See `../../usd-structure-assessment/references/apply-restructure/references/mesh-merge-rewrite-spec.md` +§9 (op-chain `merge → conditional vertex-weld → computeExtents` and the +bounds-coherence eligibility guard). Any bytes the weld tail reclaims are credited +to the disk tier via the weld source, never attributed to the merge. + +### Anti-pattern: silently dropping intent-gated ops + +**Do NOT skip, omit, or silently defer an intent-gated op without ever presenting +it.** Every intent-gated op must reach the user as an explicit decision — via +either the iteration-1 inline-elicitation prompt (`decimateMeshes`, +`fitPrimitives`) or the batched per-asset opt-in menu in Phase 7 iteration 2 +(occlusion removal, `removeSmallGeometry`, `merge`, `convertToColor`, +PointInstancer). Removal is legitimate ONLY when the user selects `skip_option` +or declines the menu item. + +The batched iter-2 menu IS the explicit offer: deferring an identity/purpose-gated +op to it preserves user agency and is NOT the silent-deferral anti-pattern. (This +is also why the Conservative Fallback runs destructive ops as a reviewed later +pass — same principle.) + +Acceptable: "decimateMeshes is recommended — what's the smallest detail to +preserve? [0.1 / 0.5 / 1.0 / 2.0 / 5.0 mm / skip decimation]" (inline, iteration 1). + +Acceptable: "Iteration-2 options for this prototype: remove 1,240 occluded interior +meshes (−X MB, but you lose the internals); convert 3 fastener families to +PointInstancers (−18K prims, but you lose per-screw selection). Pick per asset." + +Not acceptable: running lossless ops and then declaring the run done while +intent-gated wins were never surfaced to the user at all. That removes agency. + +--- + +## Red Flag: SO Operation Returns Success With Zero Work on Known-Heavy Target + +| Signal | Meaning | +|--------|---------| +| `elapsed_ms: 0` or < 1ms on a target with known high vertex/mesh count | Operation could not find meshes to process | +| `success: true` but vertex_count delta = 0 on a target SA flagged for optimization | Structural blockage, not "nothing to do" | +| Multiple operations show zero work on same target | Almost certainly a traversal issue (Over-spec ancestors, population mask, wrong root prim) | + +**Action:** Do NOT report "operation found nothing to optimize" when SA or manifest +metadata indicates the target should have significant geometry. Instead: + +1. Check specifiers on ancestor prims (Over vs Def) — see `restructure-mode.md` + §"Authoring Requirements" for the diagnostic snippet. +2. Check that the target's `defaultPrim` is set correctly. +3. Check that the stage is not masked or filtered in a way that excludes content. +4. Report the structural issue to the user rather than rationalizing the no-op. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md new file mode 100644 index 00000000..6ce4b842 --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md @@ -0,0 +1,43 @@ +# Pipeline Recipes - Upstream Handoff + +This local reference preserves the digitaltwin workflow milestone. Scene +Optimizer mechanics for this step are owned by upstream `usd-optimize`. + +- Public repository: [https://github.com/NVIDIA-Omniverse/usd-optimize/](https://github.com/NVIDIA-Omniverse/usd-optimize/) +- Package path: `docs/choosing-operations.rst` + `config_presets/*.json` (1.1.x packages), or `.agents/operations/PIPELINES.md` (1.0.x packages) +- Upstream web URL: [https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/docs/choosing-operations.rst](https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/docs/choosing-operations.rst) + +Resolve the upstream guide without cloning the source repo, using the +version-tolerant lookup stated in `references/upstreams/usd-optimize.md`: + +1. `$USD_OPTIMIZE_ROOT/docs/choosing-operations.rst` (plus `config_presets/*.json`) +2. `$USD_OPTIMIZE_ROOT/.agents/operations/PIPELINES.md` (1.0.x fallback) + +If no package root is available, download and extract the prebuilt Usd Optimize release package (current asset name + download: `references/upstreams/usd-optimize.md`) (direct +archive URLs are in `references/upstreams/usd-optimize.md`), or use the package +path/URL supplied by the user. If the user supplies an extracted +package root directly, resolve this same package path under that root. If +GitHub raw fetch is available, the web URL above is acceptable for docs-only +reads. Do not clone the source repo just to read upstream SO guidance. + +## Local Responsibilities + +- Keep workflow phase order, prototype-first ordering, and broad optimization milestone ordering in `workflow.md`. +- Use `config-from-evidence.md` for local evidence-to-request routing and `operation-safety.md` for approvals. +- Use `batch-mode.md` for digitaltwin's scheduler-backed multi-target policy: adaptive concurrency, dependency-aware target groups, status artifacts, and resume prompts. + +Named pipeline parameters and per-operation defaults belong upstream. If a +digitaltwin workflow needs to cite a chain, cite the upstream path and record +only the local evidence, target set, approval state, and report fields here. + +## Local Routing Keys + +The local workflow may route evidence to these operation keys before handing +mechanics to upstream: `computeExtents`, `decimateMeshes`, +`deduplicateGeometry`, `fitPrimitives`, `generateNormals`, `merge`, +`meshCleanup`, `optimizeMaterials`, `optimizeTimeSamples`, `pruneLeaves`, +`pythonScript`, `removeSmallGeometry`, and `removeUnusedUVs`. `merge` +(Merge Static Meshes) is the intent-gated within-prototype prim-count +consolidation step — see `workflow.md` Phase 4 and +`usd-structure-assessment/references/apply-restructure/references/mesh-merge-rewrite-spec.md` +§9 for its op-chain and eligibility guard. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/units-and-tolerances.md b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/units-and-tolerances.md new file mode 100644 index 00000000..e700d7ee --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/units-and-tolerances.md @@ -0,0 +1,176 @@ +# Units and Tolerances + +Shared reference for any operation that converts user-specified mm tolerances +to Usd Optimize stage-unit parameters. Referenced by `operation-safety.md` +and consumed by any `parameter_prerequisites` block with a `conversion` field. + +## Source of Truth + +The `asset_physical_context` section of the SA report provides: + +| Field | Meaning | +|-------|---------| +| `metersPerUnit` | Stage scale factor (1.0 = meters, 0.01 = cm, 0.001 = mm) | +| `upAxis` | Stage orientation (X, Y, or Z) | +| `scale_hint` | Human label: "meters", "centimeters", "millimeters", "other" | + +## Conversion Formula + +``` +tolerance_stage_units = mm_tolerance / (metersPerUnit × 1000) +``` + +### Worked Examples + +| User says | metersPerUnit | Stage units | Result | +|-----------|---------------|-------------|--------| +| "0.5 mm" | 0.01 (cm) | centimeters | 0.5 / (0.01 × 1000) = **0.05** | +| "1.0 mm" | 1.0 (m) | meters | 1.0 / (1.0 × 1000) = **0.001** | +| "2.0 mm" | 0.001 (mm) | millimeters | 2.0 / (0.001 × 1000) = **2.0** | +| "0.1 mm" | 0.01 (cm) | centimeters | 0.1 / (0.01 × 1000) = **0.01** | + +## Scale-banded per-target default tolerance + +The default bounded-loss tolerance is **not a single number** — it tracks each +*target's* physical scale and differs by op family (`fitPrimitives` runs ~10× +looser than `decimateMeshes`). These are the **conservative** bands that the +`auto-within-tolerance` apply-authority class (see `operation-safety.md`) runs +with a notice rather than a prompt: + +| Target scale | `decimateMeshes` | `fitPrimitives` | +|--------------|------------------|-----------------| +| Building / entire-building (`large-spatial` archetype, or max extent ≥ ~10 m — tunable) | 1 mm | 1 cm | +| Component & smaller (default) | 0.1 mm | 1 mm | + +**Resolved per target.** Because Phase 4 optimizes per target and the bounded +recursive descent gives each target its own extent + `archetype` tag, the band is resolved +per target: a building shell (`assembly_root` / `large-spatial`) gets the coarse +pair, while an extracted valve gets the fine pair *even though it lives inside +the building*. The user overrides the default globally and, optionally, per +archetype. + +**These real-world lengths convert to stage units** via the formula above using +the target's `asset_physical_context` (`metersPerUnit`, `scale_hint`), so the +same declared band yields the right stage-unit value on a centimeter CAD asset +and a meter-scale architecture asset. + +**Functional-tolerance gate.** The bands measure *visual* deviation. When a +target carries a functional-precision signal (`articulated` / physics / +sim-ready / metrology / variant-bearing — read from SA semantics + the +`importance` / `articulated` target-tree tags), bounded-loss ops drop from +`auto-within-tolerance` back to `intent-gated` regardless of band, because a +visual band cannot bound functional tolerance. `operation-safety.md` owns this +routing. + +## Elicitation Template + +When asking the user for a physical tolerance, follow this structure: +1. **State the asset's physical scale:** + > "This stage uses {scale_hint} (metersPerUnit = {metersPerUnit})." + +2. **Ask the canonical question** from the operation's `parameter_prerequisites`: + > "{canonical_question}" + +3. **Offer defaults** from the prerequisites block: + > Present the `defaults` array from the operation's `parameter_prerequisites`. + > The user picks one or provides their own value. + +4. **Offer the skip option.** + +## Parameter Glossary + +| SO Parameter | Unit | Range | Meaning | +|-------------|------|-------|---------| +| `maxMeanError` | stage units | 0.0 = disabled | QEM error budget per vertex. Primary quality knob. | +| `reductionFactor` | integer 0–100 | 100 = keep all | Percentage of triangles to **KEEP**, not remove. Secondary stop condition. | +| `maxTriangles` | integer | 0 = disabled | Absolute triangle cap per mesh. | +| `pinBoundaries` | boolean | — | Preserve mesh boundary edges. Always `true` for sub-mesh decimation. | + +**Critical:** `reductionFactor` is "keep percent", NOT "reduce percent". +`reductionFactor: 90` means keep 90% of triangles (remove 10%). + +## Anti-Patterns + +1. **Do NOT ask "reduce by 10%?"** — that's rate-framing. + The canonical question is fidelity-budget: "what detail to preserve?" + See `operation-safety.md § Anti-pattern: rate-framing`. + +2. **Do NOT use integer `0` for disabled float conditions** — use `0.0`. + JSON `"maxMeanError": 0` is ambiguous; `"maxMeanError": 0.0` is explicit. + +3. **Do NOT omit `pinBoundaries: true`** when decimating sub-meshes or + meshes that share boundary edges with neighbors. + +4. **Do NOT invent percentage options** without the user first providing a + rate-based constraint. If the user hasn't said "I want N triangles" or + "keep X%", the tolerance question is the correct entry point. + +5. **Do NOT skip the conversion step.** A user saying "1mm tolerance" on a + centimeter stage means `maxMeanError: 0.1`, not `maxMeanError: 1.0`. + +## Operations That Use This Reference + +Any operation with tolerance knobs benefits from this formula: + +- `decimateMeshes` — `maxMeanError` (primary) +- `deduplicateGeometry` — `tolerance` (coincidence threshold) +- `findCoincidingGeometry` — `tolerance` +- `mergeVertices` — `tolerance` +- `removeSmallGeometry` — `threshold` (min extent in stage units) +- `findSmallGeometry` — `threshold` + +## deduplicateGeometry parameter gotchas (field-validated) + +These were learned on real large-CAD optimization runs; upstream docs own the +full parameter reference, but these three traps are load-bearing enough to +record locally: + +- **`tolerance` is ABSOLUTE (stage units, worldspace) on usd-optimize 1.0.4** + — verified empirically (2026-06-11): the same 0.01-unit point delta deduped + at `tolerance: 0.02` and not at `0.005`, identically at coordinates ~1 and + ~10,000, so the mm-conversion formula above DOES apply on 1.0.4 (matching + the argument description "stage unit in worldspace"). Over-matching is the dangerous + direction: when in doubt, tune DOWN first. +- **`considerDeepTransforms` defaults to `true` and can corrupt placement** — + the standalone run observed instances landing with wrong transforms under the + default. Set `considerDeepTransforms: false` unless placement has been + verified on a sample after a trial run. +- **`duplicateMethod` default (Instanceable Reference, 2) makes later + decimation a no-op** — dedupe output is instances, and `decimateMeshes` + skips instanced prims. Decimate before dedupe, or use a non-instancing + method and author `instanceable` afterwards. See the ordering-invariant + caveat in `workflow.md § Operation ordering invariants`. + +## fitPrimitives parameter gotchas (primvar preservation) + +`fitPrimitives` replaces tessellated meshes with fitted primitives (cylinder, +cone, cube, sphere). Two boolean parameters govern which meshes it touches. **The +defaults are aggressive (fit more); override only to PRESERVE data, never +reflexively.** + +- **`ignoreNonConstPrimvars` (default `true`).** At the default, fitPrimitives + fits a candidate mesh even when it carries non-constant primvars, **discarding + any non-`Normal` primvars (UVs, displayColors) on replacement**. Set it to + `false` — the RESTRICTIVE setting — to SKIP meshes whose validator analysis + reports non-constant non-`Normal` primvars, preserving those primvars intact. + Per upstream `Primitive.cpp:321-322`, `Normal` primvars are explicitly + allow-listed and never block fitting at any setting, so a scene whose only + non-constant primvar is `normals` fits identically with default args. +- **`ignoreSubsets` (default `true`).** Analogous: the default fits meshes that + carry `GeomSubset` partitions; set `false` to skip them when subsets must + survive. + +**When to override.** Add `ignoreNonConstPrimvars: false` (and/or +`ignoreSubsets: false`) only when BOTH hold: validator analysis reports +`nonconstPrimvarMeshCount > 0`, AND the user has asked to preserve UVs / +displayColors / subsets. Otherwise use default args. + +**Anti-pattern.** Do NOT reflexively set `ignoreNonConstPrimvars: false` on every +CAD/BIM scene. The default already fits; the restrictive setting only narrows +what gets fitted, and is justified only by an explicit preservation intent. This +corrects a historic inverted-doc reading that told agents to set `false` +everywhere. + +Each operation's `parameter_prerequisites` frontmatter specifies which fields +it needs and what conversion applies. This file owns the shared formula; +individual ops own their specific parameter semantics. diff --git a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/so-create-proxy/README.md b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/usd-optimize-create-proxy/README.md similarity index 59% rename from skills/omniverse-usd-performance-tuning/references/so-run-operations/references/so-create-proxy/README.md rename to skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/usd-optimize-create-proxy/README.md index 58398e24..957dae08 100644 --- a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/so-create-proxy/README.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/usd-optimize-create-proxy/README.md @@ -1,22 +1,18 @@ - - - -# so-create-proxy - Specialty Handoff +# usd-optimize-create-proxy - Specialty Handoff This local reference preserves the digitaltwin workflow milestone. Scene Optimizer mechanics for this step are owned by upstream `usd-optimize`. -- Public repository: [https://github.com/NVIDIA-omniverse/usd-optimize/](https://github.com/NVIDIA-omniverse/usd-optimize/) +- Public repository: [https://github.com/NVIDIA-Omniverse/usd-optimize/](https://github.com/NVIDIA-Omniverse/usd-optimize/) - Package path: `.agents/skills/create-proxy/SKILL.md` -- Upstream web URL: [https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/skills/create-proxy/SKILL.md](https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/skills/create-proxy/SKILL.md) +- Upstream web URL: [https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/.agents/skills/create-proxy/SKILL.md](https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/.agents/skills/create-proxy/SKILL.md) Resolve the upstream guide without cloning the source repo: -1. `$SCENE_OPTIMIZER_PACKAGE_ROOT/.agents/skills/create-proxy/SKILL.md` -2. `$SO_HOME/.agents/skills/create-proxy/SKILL.md` +1. `$USD_OPTIMIZE_ROOT/.agents/skills/create-proxy/SKILL.md` +2. `$USD_OPTIMIZE_ROOT/.agents/skills/create-proxy/SKILL.md` -If no package root is available, download and extract the published -`scene_optimizer_core_...release.zip` package for the target platform (direct +If no package root is available, download and extract the prebuilt Usd Optimize release package (current asset name + download: `references/upstreams/usd-optimize.md`) (direct archive URLs are in `references/upstreams/usd-optimize.md`), or use the package path/URL supplied by the user. If the user supplies an extracted package root directly, resolve this same package path under that root. If diff --git a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/so-create-proxy/references/bounding-box-proxy-modes.md b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/usd-optimize-create-proxy/references/bounding-box-proxy-modes.md similarity index 53% rename from skills/omniverse-usd-performance-tuning/references/so-run-operations/references/so-create-proxy/references/bounding-box-proxy-modes.md rename to skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/usd-optimize-create-proxy/references/bounding-box-proxy-modes.md index 22bb6ddb..f435360f 100644 --- a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/so-create-proxy/references/bounding-box-proxy-modes.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/usd-optimize-create-proxy/references/bounding-box-proxy-modes.md @@ -1,22 +1,18 @@ - - - # Bounding-Box Proxy Modes - Upstream Handoff This local reference preserves the digitaltwin workflow milestone. Scene Optimizer mechanics for this step are owned by upstream `usd-optimize`. -- Public repository: [https://github.com/NVIDIA-omniverse/usd-optimize/](https://github.com/NVIDIA-omniverse/usd-optimize/) +- Public repository: [https://github.com/NVIDIA-Omniverse/usd-optimize/](https://github.com/NVIDIA-Omniverse/usd-optimize/) - Package path: `.agents/skills/create-proxy/references/bounding-box-modes.md` -- Upstream web URL: [https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/skills/create-proxy/references/bounding-box-modes.md](https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/skills/create-proxy/references/bounding-box-modes.md) +- Upstream web URL: [https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/.agents/skills/create-proxy/references/bounding-box-modes.md](https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/.agents/skills/create-proxy/references/bounding-box-modes.md) Resolve the upstream guide without cloning the source repo: -1. `$SCENE_OPTIMIZER_PACKAGE_ROOT/.agents/skills/create-proxy/references/bounding-box-modes.md` -2. `$SO_HOME/.agents/skills/create-proxy/references/bounding-box-modes.md` +1. `$USD_OPTIMIZE_ROOT/.agents/skills/create-proxy/references/bounding-box-modes.md` +2. `$USD_OPTIMIZE_ROOT/.agents/skills/create-proxy/references/bounding-box-modes.md` -If no package root is available, download and extract the published -`scene_optimizer_core_...release.zip` package for the target platform (direct +If no package root is available, download and extract the prebuilt Usd Optimize release package (current asset name + download: `references/upstreams/usd-optimize.md`) (direct archive URLs are in `references/upstreams/usd-optimize.md`), or use the package path/URL supplied by the user. If the user supplies an extracted package root directly, resolve this same package path under that root. If diff --git a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/so-create-proxy/references/decimate-step-recipes.md b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/usd-optimize-create-proxy/references/decimate-step-recipes.md similarity index 53% rename from skills/omniverse-usd-performance-tuning/references/so-run-operations/references/so-create-proxy/references/decimate-step-recipes.md rename to skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/usd-optimize-create-proxy/references/decimate-step-recipes.md index 447c5e7e..0f1b8889 100644 --- a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/so-create-proxy/references/decimate-step-recipes.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/usd-optimize-create-proxy/references/decimate-step-recipes.md @@ -1,22 +1,18 @@ - - - # Decimate Step Recipes - Upstream Handoff This local reference preserves the digitaltwin workflow milestone. Scene Optimizer mechanics for this step are owned by upstream `usd-optimize`. -- Public repository: [https://github.com/NVIDIA-omniverse/usd-optimize/](https://github.com/NVIDIA-omniverse/usd-optimize/) +- Public repository: [https://github.com/NVIDIA-Omniverse/usd-optimize/](https://github.com/NVIDIA-Omniverse/usd-optimize/) - Package path: `.agents/skills/create-proxy/references/decimate-mode.md` -- Upstream web URL: [https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/skills/create-proxy/references/decimate-mode.md](https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/skills/create-proxy/references/decimate-mode.md) +- Upstream web URL: [https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/.agents/skills/create-proxy/references/decimate-mode.md](https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/.agents/skills/create-proxy/references/decimate-mode.md) Resolve the upstream guide without cloning the source repo: -1. `$SCENE_OPTIMIZER_PACKAGE_ROOT/.agents/skills/create-proxy/references/decimate-mode.md` -2. `$SO_HOME/.agents/skills/create-proxy/references/decimate-mode.md` +1. `$USD_OPTIMIZE_ROOT/.agents/skills/create-proxy/references/decimate-mode.md` +2. `$USD_OPTIMIZE_ROOT/.agents/skills/create-proxy/references/decimate-mode.md` -If no package root is available, download and extract the published -`scene_optimizer_core_...release.zip` package for the target platform (direct +If no package root is available, download and extract the prebuilt Usd Optimize release package (current asset name + download: `references/upstreams/usd-optimize.md`) (direct archive URLs are in `references/upstreams/usd-optimize.md`), or use the package path/URL supplied by the user. If the user supplies an extracted package root directly, resolve this same package path under that root. If diff --git a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/so-create-proxy/references/decimation-tuning.md b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/usd-optimize-create-proxy/references/decimation-tuning.md similarity index 53% rename from skills/omniverse-usd-performance-tuning/references/so-run-operations/references/so-create-proxy/references/decimation-tuning.md rename to skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/usd-optimize-create-proxy/references/decimation-tuning.md index e49cdf8d..7fdd2ef8 100644 --- a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/so-create-proxy/references/decimation-tuning.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/usd-optimize-create-proxy/references/decimation-tuning.md @@ -1,22 +1,18 @@ - - - # Decimation Tuning - Upstream Handoff This local reference preserves the digitaltwin workflow milestone. Scene Optimizer mechanics for this step are owned by upstream `usd-optimize`. -- Public repository: [https://github.com/NVIDIA-omniverse/usd-optimize/](https://github.com/NVIDIA-omniverse/usd-optimize/) +- Public repository: [https://github.com/NVIDIA-Omniverse/usd-optimize/](https://github.com/NVIDIA-Omniverse/usd-optimize/) - Package path: `.agents/skills/create-proxy/references/parameter-tuning.md` -- Upstream web URL: [https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/skills/create-proxy/references/parameter-tuning.md](https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/skills/create-proxy/references/parameter-tuning.md) +- Upstream web URL: [https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/.agents/skills/create-proxy/references/parameter-tuning.md](https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/.agents/skills/create-proxy/references/parameter-tuning.md) Resolve the upstream guide without cloning the source repo: -1. `$SCENE_OPTIMIZER_PACKAGE_ROOT/.agents/skills/create-proxy/references/parameter-tuning.md` -2. `$SO_HOME/.agents/skills/create-proxy/references/parameter-tuning.md` +1. `$USD_OPTIMIZE_ROOT/.agents/skills/create-proxy/references/parameter-tuning.md` +2. `$USD_OPTIMIZE_ROOT/.agents/skills/create-proxy/references/parameter-tuning.md` -If no package root is available, download and extract the published -`scene_optimizer_core_...release.zip` package for the target platform (direct +If no package root is available, download and extract the prebuilt Usd Optimize release package (current asset name + download: `references/upstreams/usd-optimize.md`) (direct archive URLs are in `references/upstreams/usd-optimize.md`), or use the package path/URL supplied by the user. If the user supplies an extracted package root directly, resolve this same package path under that root. If diff --git a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/so-create-proxy/references/proxy-config-recipes.md b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/usd-optimize-create-proxy/references/proxy-config-recipes.md similarity index 88% rename from skills/omniverse-usd-performance-tuning/references/so-run-operations/references/so-create-proxy/references/proxy-config-recipes.md rename to skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/usd-optimize-create-proxy/references/proxy-config-recipes.md index 4cfd4828..b83a4687 100644 --- a/skills/omniverse-usd-performance-tuning/references/so-run-operations/references/so-create-proxy/references/proxy-config-recipes.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/usd-optimize-create-proxy/references/proxy-config-recipes.md @@ -1,6 +1,3 @@ - - - # Proxy Config Recipes - Upstream Handoff This local reference preserves the digitaltwin workflow milestone. Scene diff --git a/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/scripts/batch-plan.schema.json b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/scripts/batch-plan.schema.json new file mode 100644 index 00000000..7e397f64 --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/scripts/batch-plan.schema.json @@ -0,0 +1,86 @@ +{ + "$comment": "SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.\nSPDX-License-Identifier: Apache-2.0", + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Batch Plan", + "description": "Contract for the plan JSON consumed by the batch scheduler (usd-optimize-run-operations/scripts/run_batch.py, --plan). This makes the descent -> apply-restructure manifest -> scheduler handoff a real contract: ONE target = ONE own-layer file = ONE job (the edit-target invariant). The agent decides max_workers, archetype tags, op chains, and intent-gated opt-ins; the runner owns spawning, dependency ordering, per-target/per-op timeouts, the GPU-cliff guard, status emission, and resume. The frontier metadata from apply-restructure-manifest.json phase4_targets[] flows into per-target jobs (level / archetype / role carried through). The emitted status.json is owned by status.schema.json.", + "type": "object", + "required": ["targets"], + "additionalProperties": true, + "properties": { + "run_id": { + "type": "string", + "description": "Stable id for this batch (used in status.json and the per-target output hash). Defaults to 'batch' when absent." + }, + "source_manifest": { + "type": "string", + "description": "Optional path to the apply-restructure-manifest.json whose phase4_targets[] this plan was built from (provenance for the handoff)." + }, + "targets": { + "type": "array", + "description": "One job per Phase-4 target. Each target file is an INDEPENDENT own-root-layer edit target (never the composed assembly); that independence is why per-target work parallelizes.", + "items": { + "type": "object", + "required": ["path", "command"], + "additionalProperties": true, + "properties": { + "path": { + "type": "string", + "description": "The target's own root-layer file path. SO's edit target IS this file's bytes." + }, + "role": { + "type": "string", + "enum": ["assembly_root", "prototype", "shared_layer", "loadable_subasset", "monolith"], + "description": "Restructure role (mirrors the manifest phase4_targets[] target_class, plus 'monolith' for an N=1 optimize-as-is run)." + }, + "target_class": { + "type": "string", + "description": "Alias accepted for role (matches the manifest field name)." + }, + "level": { + "type": ["string", "null"], + "enum": ["assembly", "component", "subcomponent", "detail", null], + "description": "Descent level carried from the manifest (drives ordering / weight, not authority)." + }, + "archetype": { + "type": ["string", "null"], + "description": "large-spatial | encapsulated-product | piping | generic — selects which op-chain steps apply." + }, + "dep_group": { + "type": "string", + "enum": ["shared_first", "dependent_after", "independent"], + "description": "Prototype-first ordering: shared_first targets (prototypes/shared layers) run to completion before dependent targets so changes propagate. Independent targets ride the dependent wave. Alias: dependency_group." + }, + "dependency_group": { + "type": "string", + "enum": ["shared_first", "dependent_after", "independent"] + }, + "gpu_bound": { + "type": "boolean", + "description": "When true and the runtime_context reports no CUDA, the runner SKIPS the target (state skipped_gpu_unavailable) rather than entering a long CPU fallback." + }, + "command": { + "type": "array", + "items": { "type": "string" }, + "minItems": 1, + "description": "Argv for the standalone single-asset worker process. The worker runs the per-target op chain (e.g. meshCleanup -> deduplicateGeometry -> computeExtents; pruneLeaves is NOT in the per-prototype chain) and emits its summary to summary_path." + }, + "timeout_sec": { + "type": ["number", "null"], + "minimum": 0, + "description": "Per-target wall-clock budget; a worker exceeding it is killed (state timeout), bounding a hung op without stalling the batch." + }, + "summary_path": { + "type": "string", + "description": "Path the worker writes its before/after summary to. The runner derives the coverage disposition (optimized | no_op | unknown) from before/after deltas — 'done' alone is never 'optimized'." + }, + "log_path": { "type": "string" }, + "steps_applied": { + "type": "array", + "items": { "type": "string" }, + "description": "Op-chain steps planned/applied for this target (advisory; the worker summary is authoritative for outcome)." + } + } + } + } + } +} diff --git a/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/scripts/run_batch.py b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/scripts/run_batch.py new file mode 100644 index 00000000..4282f891 --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/scripts/run_batch.py @@ -0,0 +1,395 @@ +#!/usr/bin/env python3 +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""Parallel execution harness — resource-aware per-target scheduler. + +Turns the Phase-4b batch-mode prose into a real, deterministic runner. The +*agent* still decides max_workers, archetype tags, which op chains, and +intent-gated opt-ins; this runner owns the mechanics it must own deterministically: +spawning standalone single-asset workers, dependency ordering, per-target/per-op +timeouts (killable subprocess), the GPU-cliff guard, status emission, and resume. + +Key contracts (see ``status.schema.json`` and +``skills/.../usd-optimize-run-operations/references/batch-mode.md``): + +* **The status artifact is the contract.** Everything else (CLI bars, a future + web dashboard) is a *view* over ``status.json``. +* **``state: done`` is NOT coverage ``disposition: optimized``.** Worker + completion proves the op ran, not that it changed anything. The runner records + per-target before/after deltas (when the worker emits a summary) and derives a + ``disposition`` from those deltas — it never assumes ``done`` ⇒ ``optimized``. +* **Two safety behaviors are encoded:** per-target ``subprocess.run(timeout=...)`` + (a hung worker is killed without stalling the batch), and a GPU-cliff guard + that skips/warns ``gpu_bound`` targets on a CPU-only host (CUDA read from the + setup preflight ``runtime_context``, never from SO's own ``hasNvidiaGpu()``). +* **``--resume`` replaces the improvised remainder script:** resuming off + ``status.json`` re-runs only the unfinished targets. + +Workers are standalone single-asset processes (each target file is independent; +optimization/validation never uses Kit; standalone is the sole optimization +runtime). The opt-in Kit->omniperf profiling path is capped separately and sits +outside this fan-out. +""" + +from __future__ import annotations + +import argparse +import concurrent.futures +import datetime as _dt +import json +import subprocess +import sys +import threading +import time +from pathlib import Path +from typing import Any + +SHARED_FIRST = "shared_first" +DEPENDENT_AFTER = "dependent_after" +INDEPENDENT = "independent" + +# Target states. +QUEUED = "queued" +RUNNING = "running" +DONE = "done" +FAILED = "failed" +TIMEOUT = "timeout" +SKIPPED_GPU = "skipped_gpu_unavailable" + +# Coverage dispositions derived from the before/after outcome (NOT from state). +DISP_OPTIMIZED = "optimized" +DISP_NO_OP = "no_op" +DISP_UNKNOWN = "unknown" + +_TERMINAL_STATES = {DONE, SKIPPED_GPU} + + +def _utcnow() -> str: + return _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") + + +def _read_json(path: Path) -> Any: + with path.open("r", encoding="utf-8") as fh: + return json.load(fh) + + +def _cuda_available_from_preflight(preflight_path: Path) -> bool: + """Read the CUDA signal from the setup preflight ``runtime_context``. + + The plan is explicit: detect CUDA from setup preflight / ``runtime_context``, + NOT from Usd Optimize's own ``hasNvidiaGpu()``. We look for an explicit + boolean and fail closed (treat as unavailable) when the signal is absent, so + a CPU-only/WSL host never silently enters a long GPU fallback. + """ + try: + data = _read_json(preflight_path) + except (OSError, ValueError): + return False + rc = data.get("runtime_context", data) + for key in ("cudaAvailable", "cuda_available", "hasCuda", "gpu_available"): + if isinstance(rc.get(key), bool): + return rc[key] + gpu = rc.get("gpu") + if isinstance(gpu, dict) and isinstance(gpu.get("available"), bool): + return gpu["available"] + return False + + +def _derive_disposition(summary_path: str | None) -> tuple[str, dict | None, dict | None]: + """Read a worker summary and derive a coverage disposition from deltas. + + ``done`` only means the worker exited 0. A target is ``optimized`` only when + a real before/after change is recorded; ``mesh_count``/``tris`` unchanged is + ``no_op`` (the no-op-masquerade guard). Missing summary => ``unknown``, which + keeps the coverage gate honest rather than fabricating an ``optimized`` mark. + """ + if not summary_path: + return DISP_UNKNOWN, None, None + p = Path(summary_path) + if not p.is_file(): + return DISP_UNKNOWN, None, None + try: + s = _read_json(p) + except (OSError, ValueError): + return DISP_UNKNOWN, None, None + before = s.get("before") + after = s.get("after") + if not isinstance(before, dict) or not isinstance(after, dict): + return DISP_UNKNOWN, before if isinstance(before, dict) else None, after if isinstance(after, dict) else None + changed = any(before.get(k) != after.get(k) for k in set(before) | set(after)) + return (DISP_OPTIMIZED if changed else DISP_NO_OP), before, after + + +class _Target: + def __init__(self, spec: dict, index: int): + self.spec = spec + self.index = index + self.path = spec.get("path", f"target_{index}") + self.role = spec.get("role") or spec.get("target_class") or "monolith" + self.level = spec.get("level") + self.archetype = spec.get("archetype") + self.dep_group = spec.get("dep_group") or spec.get("dependency_group") or INDEPENDENT + self.gpu_bound = bool(spec.get("gpu_bound", False)) + self.command = spec.get("command") or [] + self.timeout_sec = spec.get("timeout_sec") + self.summary_path = spec.get("summary_path") + self.log_path = spec.get("log_path") + self.state = QUEUED + self.disposition = DISP_UNKNOWN + self.started: str | None = None + self.ended: str | None = None + self.duration_seconds: float | None = None + self.exit_code: int | None = None + self.error: str | None = None + self.steps_applied: list[str] = list(spec.get("steps_applied", [])) + self.before: dict | None = None + self.after: dict | None = None + + def to_status(self) -> dict: + return { + "path": self.path, + "role": self.role, + "level": self.level, + "archetype": self.archetype, + "dep_group": self.dep_group, + "gpu_bound": self.gpu_bound, + "state": self.state, + "disposition": self.disposition, + "steps_applied": self.steps_applied, + "started": self.started, + "ended": self.ended, + "duration_seconds": self.duration_seconds, + "exit_code": self.exit_code, + "log_path": self.log_path, + "summary_path": self.summary_path, + "before": self.before, + "after": self.after, + "error": self.error, + } + + +class BatchScheduler: + def __init__( + self, + plan: dict, + status_path: Path, + max_workers: int = 4, + cuda_available: bool = False, + resume: bool = False, + progress: bool = False, + ): + self.run_id = plan.get("run_id") or "batch" + self.status_path = status_path + self.max_workers = max(1, int(max_workers)) + self.cuda_available = cuda_available + self.progress = progress + self.started = _utcnow() + self._lock = threading.Lock() + self.targets = [_Target(t, i) for i, t in enumerate(plan.get("targets", []))] + if resume: + self._apply_resume() + + # -- resume ----------------------------------------------------------- + def _apply_resume(self) -> None: + if not self.status_path.is_file(): + return + try: + prev = _read_json(self.status_path) + except (OSError, ValueError): + return + prev_by_path = {t.get("path"): t for t in prev.get("targets", [])} + for tgt in self.targets: + done = prev_by_path.get(tgt.path) + if done and done.get("state") in _TERMINAL_STATES: + # Carry the finished result forward; do not re-run. + tgt.state = done["state"] + tgt.disposition = done.get("disposition", tgt.disposition) + tgt.started = done.get("started") + tgt.ended = done.get("ended") + tgt.before = done.get("before") + tgt.after = done.get("after") + tgt.steps_applied = done.get("steps_applied", tgt.steps_applied) + + # -- execution -------------------------------------------------------- + def _run_one(self, tgt: _Target) -> None: + # GPU-cliff guard: never enter a long CPU fallback for a gpu_bound op. + if tgt.gpu_bound and not self.cuda_available: + with self._lock: + tgt.state = SKIPPED_GPU + tgt.error = "gpu_bound op skipped: no CUDA in runtime_context (CPU-only host)" + self._write_status() + return + if not tgt.command: + with self._lock: + tgt.state = FAILED + tgt.error = "no command specified for target" + self._write_status() + return + with self._lock: + tgt.state = RUNNING + tgt.started = _utcnow() + self._write_status() + stdout_target = None + rc: int | None = None + timed_out = False + start = time.monotonic() + try: + if tgt.log_path: + Path(tgt.log_path).parent.mkdir(parents=True, exist_ok=True) + stdout_target = open(tgt.log_path, "w", encoding="utf-8") + proc = subprocess.run( + tgt.command, + timeout=tgt.timeout_sec, + stdout=stdout_target or subprocess.PIPE, + stderr=subprocess.STDOUT, + text=True, + ) + rc = proc.returncode + err = None if rc == 0 else f"worker exited with code {rc}" + except subprocess.TimeoutExpired: + timed_out = True + err = f"timeout after {tgt.timeout_sec}s (worker killed)" + except (OSError, ValueError) as exc: # spawn failure + err = f"spawn error: {exc}" + finally: + if stdout_target is not None: + stdout_target.close() + duration = round(time.monotonic() - start, 3) + with self._lock: + tgt.ended = _utcnow() + tgt.duration_seconds = duration + tgt.exit_code = rc + if err is None: + tgt.state = DONE + disp, before, after = _derive_disposition(tgt.summary_path) + tgt.disposition = disp + tgt.before = before + tgt.after = after + elif timed_out: + # A killed-by-timeout worker is a distinct outcome from a worker + # that ran to a non-zero exit — the per-rule-timeout hang this + # scheduler exists to bound. Surface it as its own state, not generic failed. + tgt.state = TIMEOUT + tgt.error = err + else: + tgt.state = FAILED + tgt.error = err + self._write_status() + + def _run_group(self, group: list[_Target]) -> None: + pending = [t for t in group if t.state not in _TERMINAL_STATES] + if not pending: + return + with concurrent.futures.ThreadPoolExecutor(max_workers=self.max_workers) as ex: + futures = [ex.submit(self._run_one, t) for t in pending] + for fut in concurrent.futures.as_completed(futures): + fut.result() + + def run(self) -> dict: + # Prototype-first ordering: shared_first group runs to completion before + # dependent targets, so prototype changes propagate. Independent targets + # ride with the dependent wave. + shared = [t for t in self.targets if t.dep_group == SHARED_FIRST] + rest = [t for t in self.targets if t.dep_group != SHARED_FIRST] + self._write_status() + self._run_group(shared) + self._run_group(rest) + self._write_status() + return self.snapshot() + + # -- status ----------------------------------------------------------- + def _overall(self) -> dict: + counts = {"total": len(self.targets), "done": 0, "failed": 0, + "timeout": 0, "running": 0, "queued": 0, "skipped": 0} + for t in self.targets: + if t.state == DONE: + counts["done"] += 1 + elif t.state == FAILED: + counts["failed"] += 1 + elif t.state == TIMEOUT: + counts["timeout"] += 1 + elif t.state == RUNNING: + counts["running"] += 1 + elif t.state == SKIPPED_GPU: + counts["skipped"] += 1 + else: + counts["queued"] += 1 + return counts + + def snapshot(self) -> dict: + return { + "run_id": self.run_id, + "started": self.started, + "max_workers": self.max_workers, + "cuda_available": self.cuda_available, + "overall": self._overall(), + "targets": [t.to_status() for t in self.targets], + } + + def _write_status(self) -> None: + # Serialize writes: concurrent workers all emit status, and an atomic + # replace from a shared temp path would race. Hold the lock and use a + # per-write unique temp name. + with self._lock: + self.status_path.parent.mkdir(parents=True, exist_ok=True) + snap = self.snapshot() + tmp = self.status_path.with_name( + f"{self.status_path.name}.{threading.get_ident()}.tmp" + ) + with tmp.open("w", encoding="utf-8") as fh: + json.dump(snap, fh, indent=2) + tmp.replace(self.status_path) + if self.progress: + o = snap["overall"] + sys.stderr.write( + f"\r[{self.run_id}] done {o['done']}/{o['total']} " + f"failed {o['failed']} timeout {o['timeout']} " + f"skipped {o['skipped']} running {o['running']} " + ) + sys.stderr.flush() + + +def _build_arg_parser() -> argparse.ArgumentParser: + p = argparse.ArgumentParser(description="Resource-aware per-target batch scheduler.") + p.add_argument("--plan", required=True, help="Batch plan JSON (targets[] with command/timeout/dep_group/gpu_bound).") + p.add_argument("--status", help="status.json output path (default: /status.json).") + p.add_argument("--max-workers", type=int, default=4) + p.add_argument("--resume", action="store_true", help="Reuse an existing status.json; re-run only unfinished targets.") + p.add_argument("--progress", action="store_true", help="Print a compact progress line to stderr.") + cuda = p.add_mutually_exclusive_group() + cuda.add_argument("--cuda", choices=["available", "unavailable"], help="Explicit CUDA signal.") + cuda.add_argument("--preflight", help="setup-preflight.json to read the runtime_context CUDA signal from.") + return p + + +def main(argv: list[str]) -> int: + args = _build_arg_parser().parse_args(argv) + plan_path = Path(args.plan) + plan = _read_json(plan_path) + status_path = Path(args.status) if args.status else plan_path.parent / "status.json" + + if args.cuda is not None: + cuda_available = args.cuda == "available" + elif args.preflight: + cuda_available = _cuda_available_from_preflight(Path(args.preflight)) + else: + cuda_available = False # fail closed: no signal => treat host as CPU-only + + sched = BatchScheduler( + plan, + status_path=status_path, + max_workers=args.max_workers, + cuda_available=cuda_available, + resume=args.resume, + progress=args.progress, + ) + snap = sched.run() + if args.progress: + sys.stderr.write("\n") + o = snap["overall"] + # Non-zero exit when any target failed or timed out, so CI / the agent notices. + return 1 if (o["failed"] or o.get("timeout")) else 0 + + +if __name__ == "__main__": + raise SystemExit(main(sys.argv[1:])) diff --git a/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/scripts/status.schema.json b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/scripts/status.schema.json new file mode 100644 index 00000000..f3da14e3 --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/scripts/status.schema.json @@ -0,0 +1,66 @@ +{ + "$comment": "SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.\nSPDX-License-Identifier: Apache-2.0", + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Batch Scheduler Status", + "description": "Contract for /status.json emitted by the batch scheduler (usd-optimize-run-operations/scripts/run_batch.py). The status artifact IS the contract; CLI/dashboard views are derived from it. CRITICAL: target.state == 'done' is NOT coverage disposition 'optimized' — 'done' only proves the worker ran. The Phase-4e target_coverage.entries[]/coverage_ledger derive from target.disposition (computed from before/after deltas), never from bare 'done'. --resume re-runs only targets whose state is not terminal (done/skipped_gpu_unavailable).", + "type": "object", + "required": ["run_id", "started", "max_workers", "overall", "targets"], + "additionalProperties": true, + "properties": { + "run_id": { "type": "string" }, + "started": { "type": "string" }, + "max_workers": { "type": "integer", "minimum": 1 }, + "cuda_available": { + "type": "boolean", + "description": "CUDA signal read from the setup preflight runtime_context (never from SO hasNvidiaGpu()). When false, gpu_bound targets are skipped (state skipped_gpu_unavailable), never silently entered into a long CPU fallback." + }, + "overall": { + "type": "object", + "required": ["total", "done", "failed", "running", "queued"], + "properties": { + "total": { "type": "integer", "minimum": 0 }, + "done": { "type": "integer", "minimum": 0 }, + "failed": { "type": "integer", "minimum": 0 }, + "timeout": { "type": "integer", "minimum": 0 }, + "running": { "type": "integer", "minimum": 0 }, + "queued": { "type": "integer", "minimum": 0 }, + "skipped": { "type": "integer", "minimum": 0 } + } + }, + "targets": { + "type": "array", + "items": { + "type": "object", + "required": ["path", "state", "disposition"], + "properties": { + "path": { "type": "string" }, + "role": { "type": "string" }, + "level": { "type": ["string", "null"], "enum": ["assembly", "component", "subcomponent", null] }, + "archetype": { "type": ["string", "null"] }, + "dep_group": { "type": "string", "enum": ["shared_first", "dependent_after", "independent"] }, + "gpu_bound": { "type": "boolean" }, + "state": { + "type": "string", + "enum": ["queued", "running", "done", "failed", "timeout", "skipped_gpu_unavailable"], + "description": "'timeout' is a worker killed by its per-target/per-op wall-clock budget (subprocess.run timeout) — distinct from 'failed' (worker ran to a non-zero exit or failed to spawn). Distinguishing them surfaces the per-rule-timeout hang the scheduler exists to bound." + }, + "disposition": { + "type": "string", + "enum": ["optimized", "no_op", "unknown"], + "description": "Coverage disposition derived from before/after deltas, independent of state. 'done' worker with no recorded change is 'no_op'; missing summary is 'unknown' (keeps the coverage gate honest instead of fabricating 'optimized')." + }, + "steps_applied": { "type": "array", "items": { "type": "string" } }, + "started": { "type": ["string", "null"] }, + "ended": { "type": ["string", "null"] }, + "duration_seconds": { "type": ["number", "null"] }, + "exit_code": { "type": ["integer", "null"], "description": "Worker process return code; null on timeout or spawn failure." }, + "log_path": { "type": ["string", "null"] }, + "summary_path": { "type": ["string", "null"] }, + "before": { "type": ["object", "null"] }, + "after": { "type": ["object", "null"] }, + "error": { "type": ["string", "null"] } + } + } + } + } +} diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/README.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/README.md index cf794558..e7517564 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/README.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/README.md @@ -1,22 +1,16 @@ # USD Structure Assessment - - - ## When to Use Use when scoping USD structural validation; do not use for fixes or validator execution. ## Instructions -1. Confirm the target asset, artifact, or user intent and check the prerequisites listed below. -2. Read only the referenced files needed for the current phase, failure mode, or output contract. -3. Follow the workflow, rules, and safety gates in this reference before invoking downstream references or shell commands. -4. Return the result using the Output Format section and name any blocked prerequisite or unresolved user decision. +See `references/_shared/standard-instructions.md`. ## Output Format -Return a concise status or report that names the input, selected runtime or evidence source, actions planned or performed, artifacts written, blockers, and the next validation or user-decision step. When a schema or template is referenced below, conform to that contract. +See `references/_shared/standard-output-format.md`. ## Purpose @@ -54,16 +48,14 @@ Before producing the SA report, re-read and confirm: ## Limitations -- SA Stage 1 is purely structural: metadata, composition arcs, prim traversal. - No geometry arrays (points, faceVertexCounts) are read. No renderer, viewport, - or BBoxCache computation. Mesh-level stats (triangle counts, density) are - deferred to Phase 2c validators (SO analysis mode). +- SA Stage 1 is purely structural (no geometry-array reads, no renderer/viewport/ + BBoxCache); mesh-level stats are deferred to Phase 2c validators. The canonical + statement of this scope lives in [§ SA Stage 1](#sa-stage-1-structure-analysis-no-geometry-load). - SA Stage 2 heuristics flag validation candidates; they do not justify operations by themselves. -- Outlier detection (§2.1) uses authored `extentsHint` attributes when present. - If extents are not authored, SA cannot flag spatial outliers — Phase 2c - validators (`countVertices` / `MeshDensityChecker`) catch density outliers - downstream with SO loaded. +- Density/over-tessellation outliers are not an SA concern: SA reads no geometry + arrays. Phase 2c validators (`countVertices` / `MeshDensityChecker` → + `perf_high_vertex_count`) catch density outliers downstream with SO loaded. ## Troubleshooting - If assets, layers, and composition arcs are conflated, re-read the reference @@ -90,7 +82,7 @@ attributes like `extentsHint`. Mesh-level statistics (triangle counts, vertex density) are **not** SA's job. Those are produced by Phase 2c validators (`countVertices`, `MeshDensityChecker`) -which run Scene Optimizer in analysis mode. +which run Usd Optimize in analysis mode. ### 1.1 Composition inventory @@ -108,7 +100,7 @@ which run Scene Optimizer in analysis mode. from stage metadata (zero cost). `mesh_count` from prim-type traversal (count prims of type `UsdGeom.Mesh` — no geometry arrays needed). These fields are consumed by downstream operations - (see `so-run-operations/references/units-and-tolerances.md`). + (see `usd-optimize-run-operations/references/units-and-tolerances.md`). ### 1.2 Asset inventory Group layers into assets. An asset is typically a directory containing: @@ -124,100 +116,80 @@ Report: - Assets missing expected layers (no payload, no interface, geometry-only). - The **referenced asset manifest**: list of geometry layer paths for downstream per-asset work. -### 1.3 Layer health - -- File formats (usdc vs usda vs usd). -- Flag large `.usda` data files (>100KB) — should be `.usdc`. -- Flag tiny layers (<500B) — accumulated automation artifacts? -- Flag anonymous or session layers. -- Total size on disk. - -### 1.4 Instancing analysis +### 1.3 Instancing analysis - Count instanceable prims and active instances. - Count prototypes. - Identify repeated references to the same asset — these are instancing candidates. - Compute instance ratio: instances / total referenceable prims. -### 1.5 Variant and payload state - -- Count variant sets and selected variants. -- Identify unloaded payloads. -- Flag variant-dependent geometry or material differences. - -### 1.6 Kind hierarchy +### 1.4 Kind hierarchy - Check that kind metadata is present and consistent (assembly → component → subcomponent). - Flag prims with geometry but no kind assignment. - Flag kind assignments that don't match the hierarchy (e.g., a component inside a component). +- Sample meshes-per-kind while checking (kind-trust reliability): authored kind + is a reliable boundary only when components bound multi-mesh parts. When + ~every `kind=component` subtree holds <= 1 mesh (common on monolithic CAD + imports — exporters tag every mesh a component), the SA report must surface + "kind present but ~1 mesh/component — unreliable boundary" so downstream + frontier selection demotes it instead of trusting it (see the + `usd-hierarchy-dedupe-candidates` finder spec §6.0.1 kind-trust preflight). ## SA Stage 2: Structural Heuristics (metadata only, narrows validation scope) -These checks use authored extent metadata (`extentsHint`) and structural -patterns to identify assets that likely need deep validation. They do not -load geometry arrays. If `extentsHint` is not authored on a prim, SA skips -spatial heuristics for that prim — Phase 2c validators catch it downstream. - -### 2.1 Outlier detection - -Using `extentsHint` or authored extent attributes (when present): - -- Flag assets where a single mesh's authored extent spans a large fraction of - the overall stage extent. This suggests fused architectural geometry that should - be split into separate assets (e.g., floor + walls + ceiling as one mesh). -- Flag assets with authored extents disproportionately small relative to their - subtree depth or sibling count — possible over-tessellation candidates. -- If extents are not authored, SA cannot flag spatial outliers. This is expected - for many real-world assets. Phase 2c validators (`countVertices` / - `MeshDensityChecker`) provide the density signal when SO is loaded. - -### 2.2 Containment detection - -Using authored extent overlap analysis (only when `extentsHint` is present): - -- Identify asset pairs where one asset's authored extent is fully enclosed - by another's. These are candidates for occlusion testing — the inner - asset may be invisible from the outside (e.g., piping inside a cabinet). -- **Check enclosure opacity:** For each containment pair, inspect the - enclosing asset's bound material for transparency signals: - - UsdPreviewSurface: `opacity` < 1.0 or `opacityThreshold` present - - MDL: glass/transmission shader, `ior` parameter, alpha-blend mode - - Any material with `opacity`, `transmission`, or `ior` inputs - Set `enclosure_opaque: true` when the enclosing material is fully opaque. - Set `enclosure_opaque: false` when any transparency signal is detected. - This is a metadata read (material binding → shader attributes) — no - geometry access needed. -- **Asset type context:** Containment is most actionable for equipment, - machines, vehicles, cabinets, housings, enclosures, pumps, motors, - compressors — sealed assemblies with opaque shells. Flag the asset type - when identifiable from prim names or kind metadata. -- Only flag pairs, don't confirm occlusion — that requires expensive - geometry analysis via `findOccludedMeshes` in Phase 4. -- Skip this check for prims without authored extents. - -### 2.3 Repetition detection - -- Identify assets with similar authored extent dimensions - that reference different source layers (when extentsHint is authored). These may be near-duplicates - that could share a common source via deduplication. -- Distinguish from intentional instancing (same source, already shared). -- Treat repeated CAD/BIM assembly names as a deep-tree signal, not just a - root-level signal. Clean root children or clean depth-2 groups do not rule - out duplicated modules nested under floor, discipline, category, or linked - model containers. -- If the stage is monolithic, has no references/payloads, has low instance - count, or contains repeated CAD/BIM assembly names, invoke - `usd-hierarchy-dedupe-candidates` for subtree-hash candidate detection before - recommending mesh-level deduplication. - -### 2.4 Hierarchy depth analysis +These checks use structural patterns and boundary nomination to identify assets +that likely need deep validation. They do not load geometry arrays. Authored +extent metadata (`extentsHint`), when present, is used only as optional +*confirmation* of a nomination — never as a required input. If `extentsHint` is +not authored, SA proceeds on structural/semantic signal alone; geometry-intrinsic +issues (density, over-tessellation) are deferred to Phase 2c validators. + +### 2.1 Containment detection (boundary-nomination primary; bbox confirmation-only) + +Internal/occluded geometry is found by **boundary nomination** (the two sources — +`candidate_source` `hash` and `semantics` — are defined once in §2.5), not by a +first-step bounding-box containment sweep. + +A containment pair exists only when a nominated `enclosing` boundary contains a +nominated `enclosed` boundary. **A `hash` nomination alone does not create a +pair:** hash groups are repeated/sibling modules (blades in a rack), not +shell/interior relationships. Emit a pair only when both sides carry a +`spatial_role` (`enclosing` + `enclosed`) established from semantics/kind/hierarchy +(or, when authored extents exist, a `bbox_confirmed` containment check). + +For each nominated enclosing/enclosed pair: + +- **Enclosure opacity is an optional hint, not a required assertion** (metadata + read, no geometry access). Inspect the enclosing boundary's bound material for + transparency signals (UsdPreviewSurface `opacity` < 1.0 / `opacityThreshold`; + MDL glass/transmission/`ior`; any `opacity`/`transmission`/`ior` input). Set + `enclosure_opaque: true` when provably opaque, `false` when a transparency + signal is found, and **omit it when opacity is not determinable from binding + metadata alone** — do not guess. Unknown opacity still schedules the probe; the + Tier-3 probe resolves it. +- **Asset type context:** most actionable for equipment, machines, vehicles, + cabinets, housings, enclosures, pumps, motors, compressors — sealed assemblies + with opaque shells. +- Emit each pair into `validation_scope.cross_component_pairs[]` as a boundary-ID + reference object. The Tier-3 probe runs unless the pair is *explicitly* + transparent (`enclosure_opaque: false`). +- **bbox is confirmation-only and informational.** When authored `extentsHint` is + present, an enclosing-extent-contains-enclosed-extent check may *confirm* a + nominated pair (record `bbox_confirmed: true`). It **never** gates whether the + probe is scheduled, and a missing/non-overlapping bbox does not retract a + hash/semantics nomination. +- Only nominate pairs and scope the probe — never confirm occlusion here. That + requires the expensive `findOccludedMeshes` geometry analysis in Phase 4. + +### 2.2 Hierarchy depth analysis - Flag deep nesting without kind boundaries (many Xform ancestors before reaching a component or assembly kind). - Flag flat hierarchies where a single prim has hundreds of direct children with geometry — may benefit from grouping into subcomponents. -### 2.5 Prim count and mesh sizing interpretation +### 2.3 Prim count and mesh sizing interpretation Use `summary_counts`, extents, and hierarchy context to explain scale before recommending a downstream validation or optimization path: @@ -244,7 +216,7 @@ recommending a downstream validation or optimization path: - Any recommendation that may drop geometry, collapse hierarchy, or discard authored attrs/metadata requires explicit user confirmation downstream. -### 2.6 Duplicate subtree detection +### 2.4 Duplicate subtree detection Identify subtrees that are structurally identical and positioned at the same transform. This is common in BIM/Revit exports where linked models are @@ -292,12 +264,60 @@ Recommendation: - Quantify the saving: removing N-1 copies of each group eliminates (N-1)/N of the scene's prims and associated prototypes. -### 2.7 Asset boundary identification +### 2.5 Asset boundary identification For monolithic stages, identify natural grouping levels that could become separate assets. Present candidates to the user rather than prescribing a specific level. +**Boundary-inference re-entry (bounded recursive descent).** This §2.5 inference is +re-run on EACH extracted asset after Phase 2f — assembly boundaries first, then +component, then subcomponent boundaries within important sub-hierarchies — to a +bounded depth. The descent contract, the `level`/`importance`/`articulated`/ +`archetype` target-tree tags, and the stopping rule live in `workflow.md` +Phase 2g; the manifest carries the tags on each `phase4_targets[]` entry. +Externalize via shared prototypes (`instanceable=true`), never N unshared +per-node payloads, and never let layer count explode (the over-structuring +pitfall the depth bound guards against). + +**Identity first, reuse second (the order that keeps parts addressable).** A +boundary is a property of the asset's authored intent and real-world +decomposition, not something read off the geometry. Recover it in priority order, +and only then confirm reuse: + +1. **Authored `kind`.** `assembly` → `group` → `component` (smallest + separately-publishable model) → `subcomponent` (a named, addressable part). A + `component` / `subcomponent` boundary is a real boundary by default — it is the + intended unit of reference. Default, not unconditional: when the §1.4 + meshes-per-kind sample shows kind does not bound multi-mesh parts (~1 + mesh/component, the CAD-exporter artifact), DEMOTE authored kind and fall + through this ladder as if it were absent — the structural fallback below may + then propose the grain, flagged `kind_untrusted` (finder spec §6.0.1). +2. **Namespace / naming.** A meaningful authored name (`assetInfo`, display name, + variant set) marks a "thing"; `Mesh_017` or a transform-only `Xform` is + plumbing. The transition from named typed scopes down to anonymous `Mesh`/`Gprim` + leaves is the **floor of the model hierarchy** — cross it and you have left the + parts and entered the geometry. For referenced/instanced assets, identity lives + on the referenced family / `kind`-tagged definition, not the leaf instance name; + and a generic family name (`Standard_124`) is *not* license to treat a real + family as anonymous geometry. +3. **Semantic recognizability.** Does the subtree correspond to something a domain + expert names and services / swaps as one piece? This is the signal a structural + pass cannot see and the agent must deliberately use. + +Run the hierarchy hash (`usd-hierarchy-dedupe-candidates`) **only after** these +signals have marked the meaningful candidates: it confirms which of them repeat and +how exactly (variant vs identical), it does **not** choose the grain. Letting the +hash choose the grain is the failure that over-shares at the mesh level. The single +exception is a **fallback** where authored identity is entirely absent: the hash may +propose the **coarsest repeating subtree** as the grain (record `grain_source = +structural_fallback`), still stopping at that coarsest unit, never the leaves. The +per-unit disposition matrix (identity × reuse → externalize / internal-share / +keep-local, with the optional reduction route) lives in +`references/instancing-readiness/references/instancing-tradeoffs.md`; the +three-axes / nested-not-flat / repair-first framing lives in `workflow.md` +Phase 2g. + Analyze the existing hierarchy for repeating patterns: - **Disciplines** (HVAC, Architectural, Structural, Electrical, Plumbing, Facades) @@ -332,8 +352,8 @@ boundaries. In that case: - Route to `restructure-decision` even when mesh optimization can proceed "as-is". - Ask whether the user wants loadable sub-assets (for example per-floor or - per-discipline-per-floor payloads), wants to optimize the monolith as-is, or - wants a diagnosis-only exit. + per-discipline-per-floor payloads) or wants to optimize the monolith as-is. + Both proceed into the optimization pipeline; there is no diagnosis-only exit. - Do not record `choice: optimize-as-is` without presenting that selective loading choice to the user. @@ -359,14 +379,40 @@ monolithic, recommend running it before finalizing the boundary plan. The combined SA + dedupe-candidates output is what `restructure-decision` (Phase 2e in the tuning workflow) consumes when asking the user to confirm. -### 2.8 Prototype library assessment +#### Boundary records and semantics nomination (`asset_boundary_suggestions.boundaries[]`) + +Populate `asset_boundary_suggestions.boundaries[]` with the nominated +enclosing/enclosed product boundaries that occlusion detection keys off. Each +record carries a `boundary_id`, `prim_path`, `candidate_source`, and optionally +`spatial_role`, `enclosure_opaque`, `semantic_label`. This is the **canonical +definition** of the two nomination sources (§2.1 references it): + +- **`candidate_source: hash`** — the boundary aligns with a + `usd-hierarchy-dedupe-candidates` group (duplicate-count ≥ 2). The strong signal + for **repeated** modules (blades in a rack, identical aircon units). A hash + nomination is a candidate boundary only; on its own it does **not** imply + containment (hash groups are siblings/repeats, not shell/interior). +- **`candidate_source: semantics`** — a **unique, one-off enclosed product** from + kind / naming / discipline-container signals (a single engine in a car, a + one-off compressor inside a skid). The hash finder cannot nominate a singleton + (needs duplicate-count ≥ 2), so semantics is the only path that surfaces it. + `semantic_label` (the driving signal) is **required** for this source. + +Set `spatial_role` (`enclosing` | `enclosed` | `standalone`) — required on any +boundary referenced by a `cross_component_pair`. `enclosure_opaque` is an optional +opacity hint on enclosing boundaries (omit when undetermined; see §2.1). +`validation_scope.cross_component_pairs[]` references these boundaries by +`boundary_id` to scope the Tier-3 occlusion probe. Hash-OR-semantics nomination is +the primary occlusion signal; the old bbox containment sweep is confirmation-only. + +### 2.6 Prototype library assessment For scenes with explicit prototypes: - Identify the authored prototype hierarchy path (e.g., `/Root/Prototypes/`). - Count prototypes and assess whether they should be extracted into a shared library layer (per the VFI "component + subcomponent library packaging" pattern). -- Assess whether the prototype pool is inflated by duplicate subtrees (see 2.6). +- Assess whether the prototype pool is inflated by duplicate subtrees (see 2.4). Extraction recommendation: @@ -416,7 +462,6 @@ Emit a structure assessment report containing: "well_structured": N, "manifest": ["path/to/A.geom.usd", ...], }, - "layer_health": { "large_usda": [...], "tiny": N, ... }, "instancing": { "instances": N, "prototypes": N, "candidates": N, "ratio": 0.0 }, "hierarchy_dedupe": { "recommended": true, @@ -425,36 +470,35 @@ Emit a structure assessment report containing: { "path_pattern": "...", "subtree_prims": 0, "copies": 0, "estimated_prim_savings": 0 } ] }, - "scale_assessment": { - "prim_count_interpretation": "structural_reuse_needed | local_cleanup_first | acceptable", - "mesh_sizing_flags": ["small_mesh_detail", "large_overlap_candidate"], - "merge_posture": "prototype_local_preferred | whole_assembly_requires_user_confirmation" - }, "asset_boundary_suggestions": { "candidate_levels": [ { "level": "per-floor", "child_count": 8, "hash_matched_groups": 0, "promoted": false }, { "level": "per-discipline-per-floor", "child_count": 56, "hash_matched_groups": 4, "promoted": true, "reason": "4 hash-matched assembly groups align with this cut - immediate dedupe wins on extraction" } ], + "boundaries": [ + { "boundary_id": "b_car_body", "prim_path": "/World/Car/Body", "candidate_source": "semantics", + "spatial_role": "enclosing", "enclosure_opaque": true, "semantic_label": "Body/Shell" }, + { "boundary_id": "b_engine", "prim_path": "/World/Car/Engine", "candidate_source": "semantics", + "spatial_role": "enclosed", "semantic_label": "Engine" } + ], "user_choice_required": true, "choice_reason": "payload_count is 0 and clear spatial/discipline boundaries exist; selective loading is a user decision even if geometry reuse is already strong", "consumed_by": "restructure-decision (Phase 2e)" }, - "flagged_assets": [ - { "asset": "...", "reason": "outlier_extent", "details": "..." }, - { "asset": "...", "reason": "containment", "pair": "...", "enclosure_opaque": true, "details": "..." }, - { "asset": "...", "reason": "repetition", "similar_to": "...", "details": "..." }, - ], "validation_scope": { "per_asset": ["list of assets needing individual validation"], - "cross_component_pairs": ["list of (A,B) pairs needing spatial analysis"], + "cross_component_pairs": [ + { "enclosing_boundary_id": "b_car_body", "enclosed_boundary_id": "b_engine", + "enclosure_opaque": true, "probe": "spatial_occluded" } + ], "skip": ["list of assets with no flags — low priority for deep validation"], }, "phase_recommendation": "structuring | optimization | already_optimized" } ``` -The `validation_scope` section feeds directly into `so-run-validators` — it tells +The `validation_scope` section feeds directly into `usd-optimize-run-validators` — it tells the agent which assets to validate and which to skip. The `summary_counts` section is the compact handoff consumed by @@ -470,12 +514,12 @@ do not mistake it for a total arc-item count. The `phase_recommendation` indicates which phase of the three-phase pipeline (extraction → structuring → optimization) the scene is currently in, based on -the structural evidence. This guides the edit-target planner and Scene Optimizer +the structural evidence. This guides the edit-target planner and Usd Optimize handoff decisions. If `hierarchy_dedupe.recommended` is true, run `usd-hierarchy-dedupe-candidates` before `restructure-decision` or mesh-level -`so-run-operations`. That skill is read-only and decides whether repeated +`usd-optimize-run-operations`. That skill is read-only and decides whether repeated subtrees should be turned into shared prototype/reference assets before any mesh-level dedupe. @@ -484,13 +528,11 @@ mesh-level dedupe. - Do not read geometry arrays (points, faceVertexCounts, normals). SA is structural only. Mesh-level stats belong to Phase 2c validators. - Do not run geometry validators in this reference; hand validation scope to - `usd-validation-runner` / `so-run-validators`. + `usd-validation-runner` / `usd-optimize-run-validators`. - Do not recommend operations based on structural heuristics alone — heuristics flag candidates for validation, not confirmed issues. - Report `summary_counts` explicitly. Asset counts are the primary scope metric; layer counts and arc counts are supporting evidence. -- Report `scale_assessment` when prim count, mesh size, or merge strategy affects - the validation or optimization path. - Do not set `hierarchy_dedupe.recommended: false` from only a root-child or depth-2 name scan on CAD/BIM exports. Deep repeated names require a deeper normalized scan or `usd-hierarchy-dedupe-candidates` evidence. @@ -499,9 +541,9 @@ mesh-level dedupe. strong and the mesh-optimization path is otherwise "optimize as-is". - Use the reference docs to distinguish assets from layers from arcs — conflating them leads to incorrect scope estimates. -- Spatial heuristics (§2.1, §2.2, §2.3) use only authored `extentsHint` - attributes. If extents are not authored, skip the spatial check for that - prim — do not compute bounds to fill the gap. +- The containment bbox-confirmation check (§2.1) uses only authored `extentsHint` + attributes. If extents are not authored, skip the confirmation — do not compute + bounds to fill the gap. The nomination itself does not depend on extents. ## Tools for asset extraction diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/README.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/README.md index 855e03c6..aed5ed30 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/README.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/README.md @@ -1,22 +1,16 @@ # apply-restructure - - - ## When to Use -Use this reference when you need to tool of restructure-decision and usd-edit-target-planner. Orchestrates USD reference rewriting for Phase 2f (monolithic -> prototypes) and Phase 5 (parent assemblies -> optimized children + stage-level cleanup). Two cognate modes under one skill since both reduce to 'write USD files + rewrite references'. +Use this reference to execute the plan from restructure-decision and usd-edit-target-planner. Orchestrates USD reference rewriting for Phase 2f (monolithic -> prototypes) and Phase 5 (parent assemblies -> optimized children + stage-level cleanup). Two cognate modes under one skill since both reduce to 'write USD files + rewrite references'. ## Instructions -1. Confirm the target asset, artifact, or user intent and check the prerequisites listed below. -2. Read only the referenced files needed for the current phase, failure mode, or output contract. -3. Follow the workflow, rules, and safety gates in this reference before invoking downstream references or shell commands. -4. Return the result using the Output Format section and name any blocked prerequisite or unresolved user decision. +See `references/_shared/standard-instructions.md`. ## Output Format -Return a concise status or report that names the input, selected runtime or evidence source, actions planned or performed, artifacts written, blockers, and the next validation or user-decision step. When a schema or template is referenced below, conform to that contract. +See `references/_shared/standard-output-format.md`. > **Invocation.** Tool of `restructure-decision` (Phase 2e gate, mode=`restructure`) and the `optimize-loop` (mode=`ref_remap`, after Phase 4 mesh ops produce optimized sub-assets). In Codex / generic shell agents, invoke by name. In Claude Code, also available as `/apply-restructure`. > @@ -26,7 +20,8 @@ Return a concise status or report that names the input, selected runtime or evid Orchestrate USD reference rewriting in two cognate use cases that both reduce to "write USD files + rewrite references": -- **`mode=restructure`** (Phase 2f, after `restructure-decision` returns `extract-as-assets` or `decompose-for-selective-loading`): materialize the asset boundaries identified by `usd-structure-assessment` §2.7 and the dedupe candidates from `usd-hierarchy-dedupe-candidates`. Hierarchy dedupe is implemented as a USD rewrite from the candidate report: write shared prototypes, replace duplicate local subtrees with references, and then validate the new assembly root. +- **`mode=restructure`** (Phase 2f, after `restructure-decision` returns `extract-as-assets` or `decompose-for-selective-loading`): materialize the asset boundaries identified by `usd-structure-assessment` §2.5 and the dedupe candidates from `usd-hierarchy-dedupe-candidates`. Hierarchy dedupe is driven **per descent region** by the native `deduplicateHierarchies` op: the identity-first frontier (`usd-hierarchy-dedupe-candidates/scripts/select_frontier.py`) selects the `paths` and a small per-region `maxDepth`, the per-level driver invokes `deduplicateHierarchies(paths=[node], maxDepth=)` on each node and recurses, and `apply-restructure` owns the identity gate, writes the shared prototypes / rewrites duplicate sites as `instanceable=true` references, emits the restructure-role manifest, then validates the new assembly root. Never drive it with a single stage-wide `maxDepth`. The hand-authored `Sdf` path stays permitted for what the native op does not cover (external-prototype materialization into payload files, and material-network closure at a prototype boundary). Execution detail: `references/restructure-mode.md`. + - **Bounded recursive descent.** Restructure is a bounded *descent*, not one cut: after extracting assemblies, the workflow re-runs boundary inference (§2.5) on each extracted asset to find component, then subcomponent boundaries, to a bounded depth (the stopping rule in `workflow.md` Phase 2g). Tag each `phase4_targets[]` entry with its target-tree tags — `level` (assembly/component/subcomponent = USD `kind`), `importance` / `articulated`, and `archetype` — per the manifest schema; Phase 4 reads them to gate the op chain and per-target tolerance. **Share, don't scatter:** every externalized node MUST be a shared prototype with `instanceable=true` references; N unshared per-node payloads are not the optimization win (the Phase-6 gate fails closed on a repack or unshared split). Articulated assets instance at rigid-body/link level, never whole-asset. - **`mode=ref_remap`** (Phase 5, after Phase 4 mesh ops): given a map of `original_path -> optimized_path` for each sub-asset Phase 4 produced, compute the parent-assembly impact set, copy each parent to a new path, rewrite its references to point at the optimized children, then run stage-level cleanup ops. Both modes share the same primitives (write USD, rewrite refs) so they live in one skill body. @@ -35,7 +30,7 @@ Both modes share the same primitives (write USD, rewrite refs) so they live in o - A USD asset path that opens cleanly under the active runtime (Phase 0 chosen). - A writable `output_dir` distinct from the input stage's directory (no in-place overwrites by default). -- USD Python access (`pxr.Usd`, `pxr.Sdf`, and `pxr.UsdUtils`) from the active runtime. Scene Optimizer is optional for later stage-level cleanup ops, but is not required for hierarchy dedupe. +- USD Python access (`pxr.Usd`, `pxr.Sdf`, and `pxr.UsdUtils`) from the active runtime. Usd Optimize (with `deduplicateHierarchies` in `operationsAvailable`) is the per-region authoring primitive for the internal instanceable-reference collapse; it is not required for the hand-authored `Sdf` paths (external-prototype materialization, material-network closure) that cover what the op does not. - For `mode=restructure`: a `restructure_plan` packet from `restructure-decision` (boundary cut points + optional dedupe candidates). - For `mode=ref_remap`: an `optimized_targets` map (every `original_path` actually appears as a reference in the input stage; every `optimized_path` exists and opens cleanly). @@ -43,8 +38,8 @@ Both modes share the same primitives (write USD, rewrite refs) so they live in o Before executing restructure writes, re-read and confirm: -- [ ] `references/hierarchy-dedupe-rewrite-tool-spec.md` — exact rewrite - semantics, reference patching, prototype extraction rules. +- [ ] `references/restructure-mode.md` § Dedupe Plan — per-region native-op driver, + reference patching, prototype extraction rules, and material-network closure. - [ ] User has explicitly approved the restructure plan from Phase 2e. - [ ] Backup / non-destructive output path — restructure writes new layers, never overwrites the original stage in-place. @@ -63,7 +58,7 @@ Before executing restructure writes, re-read and confirm: ## Troubleshooting - If the input plan from `restructure-decision` references prim paths that do not exist on the stage, return an error that names the missing paths and ask the user to refresh the SA report. -- If the hierarchy rewrite would collapse unrelated assemblies or drop local child overrides, stop and refresh the candidate report with stricter hash settings. See `references/hierarchy-dedupe-rewrite-tool-spec.md` and `skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md` "Merge safety". +- If the hierarchy rewrite would collapse unrelated assemblies or drop local child overrides, stop and refresh the candidate report with stricter hash settings. See `references/restructure-mode.md` § Dedupe Plan and `skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md` "Merge safety". - If a parent-assembly copy fails reference rewriting (e.g. the original reference uses a relative path that resolves differently in the new location), capture the resolver context and surface to the user before continuing. - If minimum USD validation fails on a written output, do NOT delete it; report the failure and let the user inspect the bad file. @@ -95,6 +90,7 @@ Manifest schema: "input_stage": "", "output_dir": "", "new_assembly_root": "", + "assembly_root": { "path": "", "mesh_count": 0 }, "outputs": [ { "path": "", @@ -170,12 +166,22 @@ only when this `mesh_count` is `0`, so a retained-mesh target cannot be silently - For `mode=restructure`: every extracted file has `defaultPrim` set to the root prim of the extracted sub-hierarchy. Validate with `Usd.Stage.Open(path).GetDefaultPrim().IsValid()`. -- For `mode=restructure`: the manifest documents what mesh content remains on - the assembly root after extraction. If the assembly root has > 0 mesh prims, - include it in `phase4_targets[]` with `target_class: "assembly_root"` so - Phase 4 does not skip it. Downstream Phase 4 must process that entry through - the per-target mesh op chain for its retained meshes; it is not limited to - final stage-level cleanup operations. +- For `mode=restructure`: **residual-mesh postcondition (fail loud).** With the + USD stage still open, measure the assembly root's default-predicate mesh count + after extraction and record it under the manifest's `assembly_root` + (`{ "path": , "mesh_count": }`). When that count is + `> 0`, the manifest MUST also include the same root in `phase4_targets[]` with + `target_class: "assembly_root"` and the identical authoritative `mesh_count`. + **Do not write a restructure manifest that records residual assembly-root + meshes without that `phase4_targets[]` entry — error out instead.** This check + lives here because only apply-restructure has the stage open to count residual + meshes; the report-time gate (`optimization-report/scripts/validate_report.py`) + only sees report↔manifest and cannot detect the residual itself. The manifest's + internal consistency is re-asserted by `validate_manifest_structure()` (in + `optimization-report/scripts/validate_report.py`): `assembly_root.mesh_count > 0` + with no matching `assembly_root` Phase-4 target fails. Downstream Phase 4 must + process that entry through the per-target mesh op chain for its retained meshes; + it is not limited to final stage-level cleanup operations. --- @@ -191,7 +197,9 @@ High-level steps: 1. Scan for internal references that escape candidate boundaries. 2. Validate input paths, boundary prim paths, and output directory. -3. Apply approved hierarchy-dedupe groups when present. +3. Drive the per-region native `deduplicateHierarchies` op per descent node from + the approved frontier (small per-region `maxDepth`; never one global cut), + owning the identity gate and manifest. 4. Materialize each accepted boundary, shared layer, loadable sub-asset, or dedupe group as USD output. 5. Validate every written output with the runner's minimum-openability check. @@ -213,7 +221,7 @@ High-level steps: 2. Stop on cyclic reference graphs. 3. Copy impacted parent layers and rewrite references to optimized children. 4. Pick the new assembly root. -5. Run lossless stage-level cleanup through `so-run-operations`. +5. Run lossless stage-level cleanup through `usd-optimize-run-operations`. 6. Validate written outputs and emit the manifest. --- @@ -233,10 +241,9 @@ High-level steps: - `skills/omniverse-usd-performance-tuning/references/workflow.md` - canonical 7-phase flow context. - `skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md` - merge safety policy (especially the "Do not recommend mesh merge when..." block). -- `references/hierarchy-dedupe-rewrite-tool-spec.md` - hierarchy dedupe rewrite behavior. -- `references/restructure-mode.md` - mode=`restructure` execution notes and internal-reference handling. +- `references/restructure-mode.md` - mode=`restructure` execution notes, the per-region native-op Dedupe Plan, material-network closure, and internal-reference handling. - `references/ref-remap-mode.md` - mode=`ref_remap` parent rewrite and stage cleanup notes. -- `skills/omniverse-usd-performance-tuning/references/so-run-operations/references/pipelines.md` - local handoff for Scene Optimizer operation chaining after hierarchy rewrite. -- `references/upstreams/usd-optimize.md` - upstream Scene Optimizer mechanics, invocation docs, and prebuilt package resolution. -- `usd-structure-assessment/README.md` §2.7 + "Tools for asset extraction" - boundary identification + USD API patterns this reference builds on. +- `skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/pipelines.md` - local handoff for Usd Optimize operation chaining after hierarchy rewrite. +- `references/upstreams/usd-optimize.md` - upstream Usd Optimize mechanics, invocation docs, and prebuilt package resolution. +- `usd-structure-assessment/README.md` §2.5 + "Tools for asset extraction" - boundary identification + USD API patterns this reference builds on. - `usd-structure-assessment/references/usd-edit-target-planner/README.md` - per-asset optimization with reference remapping pattern (mode=`ref_remap` is a generalization of this). diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/hierarchy-dedupe-rewrite-tool-spec.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/hierarchy-dedupe-rewrite-tool-spec.md deleted file mode 100644 index fa8fa93a..00000000 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/hierarchy-dedupe-rewrite-tool-spec.md +++ /dev/null @@ -1,182 +0,0 @@ - - - -# Hierarchy-Dedupe Rewrite Tool - Behavioral Specification - -Status: draft -Audience: a coding agent or human implementing a hierarchy rewrite from the -read-only output of `skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/references/instance-candidate-finder-spec.md`. - -## 1. Purpose - -Rewrite repeated local USD sub-hierarchies into shared prototype assets and -references. This is a USD authoring tool, not a Scene Optimizer operation. - -Use this behavior spec to author the rewrite with `pxr.Sdf`, `pxr.Usd`, and, -when running inside Kit, the same rule-pipeline discipline used by Isaac Sim -Asset Transformer: validate inputs, transform a copy, write explicit outputs, -then reload and validate. - -## 2. Inputs - -- `input_stage`: USD stage path that opens cleanly. -- `output_dir`: writable directory distinct from the input stage directory. -- `candidate_report`: output from the instance-candidate finder. -- `selected_groups`: candidate group ids or hashes approved by the user. -- `mode`: `internal_reference` or `external_prototype`. -- `material_policy`: `inline_local_external`, `preserve_external`, or - `block_on_external`. Default: `inline_local_external`. -- `dry_run`: when true, emit a manifest without writing output layers. - -The default mode is `external_prototype` for customer-facing digital twins -because it creates explicit assets that can be optimized, versioned, and -validated independently. `internal_reference` is acceptable for a single-file -experiment or when the user explicitly wants to keep one layer. - -## 3. Preconditions - -- Minimum USD validation passes on the input stage. -- The user has explicitly approved the selected candidate groups and output - location. -- Every selected group has an `instanceability` verdict of `clean` or - `review-required` with accepted findings. Do not auto-rewrite groups marked - `blocked`. -- Candidate groups are non-overlapping after nested-group collapse. If two - selected groups overlap, keep the parent group and drop the nested child - unless the user explicitly chooses a narrower scope. -- The rewrite must run against the layer that owns the source prim specs. If a - candidate's specs are spread across multiple layers, emit `blocked` and ask - for a flatten/export step or an explicit edit-target plan. - -## 4. Outputs - -- A new assembly root USD file under `output_dir`. -- For `external_prototype`, one prototype USD file per selected group. -- For `internal_reference`, one prototype namespace inside the new root layer, - such as `/__HierarchyPrototypes`. -- A manifest JSON with: - - input stage path - - output root path - - selected candidate groups - - prototype paths or prototype prim paths - - material networks inlined into each prototype - - rewritten instance sites - - skipped candidates and reasons - - validation result per written file - -Never overwrite the input stage in place. - -## 5. Rewrite Algorithm - -1. Open the input stage and root layer. -2. Copy the input root layer to a new assembly layer. -3. For each selected candidate group: - - Choose the first approved path as the prototype source unless the user - selected a specific prototype. - - Verify every candidate path still exists in the copied assembly layer. - - Verify the owning layer for each candidate root. If ownership is - ambiguous, block the group rather than guessing. -4. Materialize the prototype: - - `external_prototype`: create a new layer, copy the prototype source spec - to a stable root prim, set `defaultPrim`, save the layer. - - `internal_reference`: copy the prototype source spec under the prototype - namespace in the new assembly layer. -5. Resolve material-boundary dependencies for the prototype. See - [§6 Material Inlining](#6-material-inlining). -6. Rewrite each duplicate instance site: - - Keep the original root prim path and root placement opinions. - - Remove authored children and descendant specs that would duplicate the - prototype contribution. - - Add a reference to the prototype. Use a relative asset path for external - prototypes when possible. - - Set `instanceable = true` only when the candidate report found no local - child overrides or cross-boundary relationships that would make the site - invalid as an instance. -7. Save the new assembly layer and prototype layers. -8. Reopen the new assembly root from disk and run the minimum USD validation - reference owned by `usd-validation-runner`. - -Use `Sdf.CopySpec` for spec copying and `Usd.Prim.GetReferences().AddReference` -or direct `Sdf.Reference` list edits for references. Do not flatten the whole -stage unless the user has accepted the loss of composition structure. - -## 6. Material Inlining - -Cross-boundary material relationships are common in CAD and digital twin -assets: duplicate equipment, furniture, or HVAC assemblies often bind geometry -inside the candidate subtree to materials under a shared `/Looks`, -`/Materials`, or similar scope outside that subtree. If those relationships are -left pointing at the source stage, the prototype is harder to validate, -version, move, and optimize independently. - -When `material_policy=inline_local_external` (the default), the rewrite tool -must inline local material dependencies into each prototype: - -1. For the canonical source subtree, collect authored material bindings and - UsdShade connections whose targets are outside the selected subtree. -2. Treat material targets as inlineable when the target prim is part of the - input stage or package and is not an explicit external material-library - dependency. -3. Build the material-network closure for each inlineable material: the - Material prim, Shader and NodeGraph descendants, and connected shader or - nodegraph prims required by that network. -4. Copy each material network into the prototype, preferably under a stable - child scope such as `//Looks`. -5. Rewrite copied geometry bindings and copied shader connections so they - target the inlined material-network paths. -6. Preserve texture and other asset-valued inputs, but validate that they still - resolve from the prototype layer. If a relative asset path would stop - resolving, rewrite it relative to the prototype layer or mark the group - `blocked` until the dependency move is explicit. - -Do not decide material equivalence by material prim name alone. If different -copies bind to different material paths, compare the material-network closure -or split the candidate group. If the material networks differ, skip the group -or leave the affected sites uninstanceable; do not silently collapse distinct -looks. - -When `material_policy=preserve_external`, keep external material targets and -record them in the manifest. When `material_policy=block_on_external`, block -any selected group with material bindings or shader connections that cross the -prototype boundary. - -## 7. Safety Rules - -- Do not collapse candidates based only on display names. Display names can be - used for sorting or labels, but content identity must come from the candidate - hash and optional value checks. -- Preserve root transforms at each duplicate site. Root placement is per - instance; descendant transforms are prototype content. -- Preserve authored metadata on the duplicate root unless it conflicts with the - reference arc or instanceability. -- Do not rewrite non-material relationships or attribute connections that - target paths outside the candidate subtree unless the candidate report - explicitly marks the group as accepted after review. -- If a duplicate has authored child overrides, either keep it uninstanceable - with a normal reference or skip it. Do not mark it instanceable and silently - drop overrides. -- Validate every written file before reporting success. - -## 8. Reporting - -Report: - -- number of candidate groups selected -- prototype files or prims written -- material networks inlined or preserved as external dependencies -- duplicate sites rewritten -- sites left uninstanceable and why -- candidates skipped and why -- validation status -- estimated prim-count reduction from the candidate report, clearly labeled as - an estimate until post-write profiling confirms it - -## 9. Relationship to Scene Optimizer - -After the hierarchy rewrite, Scene Optimizer can still be used on the resulting -prototype assets: - -- Run `deduplicateGeometry` inside each prototype asset to catch mesh-level - duplicates. -- Run `optimizeMaterials`, `computeExtents`, and other lossless cleanup on the - prototype assets or new assembly root as appropriate. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/mesh-merge-rewrite-spec.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/mesh-merge-rewrite-spec.md new file mode 100644 index 00000000..0ad3d202 --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/mesh-merge-rewrite-spec.md @@ -0,0 +1,272 @@ +# Mesh-Merge Rewrite — Behavioral Specification + +Status: draft (rev 1) +Audience: a coding agent authoring the `reduction_route = merge` landing. +Style: behavior-only. + +## 1. Purpose and when it applies + +This is the authoring route for the reduction frontier's **`reduction_route = +merge`** decision (a scene-graph / draw-call win). It fuses a **fragmented fan of small sibling meshes** +into far fewer `Mesh` prims, cutting the rendered (unique) mesh-prim count and the +scene-graph weight (per-prim composition, traversal, stage-open, and per-mesh +renderer overhead). This route collapses **distinct, same-material fragments** +that recur only because a CAD/BIM/EDA converter authored one prim per modeled +face. Its counterpart route — collapsing **repeated** subtrees by reference — is +the point-instance route (`restructure-mode.md` § Point-Instance Route). + +The win is the **count of meshes, not bytes**. A merge concatenates geometry +(stored bytes ≈ the sum of the members, and the crate already byte-deduplicates +identical arrays within a layer), so merge makes **no disk claim** — it is scored +on the scene-graph axis, flagged `unverified-at-render` until a runtime +profile confirms it. Only the optional coincident-seam **vertex weld** the merge +enables is a small, legitimate disk credit (`disk_win_source = vertex_weld`), +never attributed to the merge itself. See `tools/oracle/score_run.py` and §9 +below (the per-prototype op chain and merge-eligibility guard). + +**It is geometrically lossless but identity-destroying.** The rendered result is +unchanged (the same triangles, re-packaged), but a merged mesh can no longer be +selected, overridden, or serviced as its constituent parts. **Identity is the +cost** — exactly the disposition-matrix `merge` row — so it is reserved for the +weak/none-identity row and is intent-gated (§2). + +This is a **USD authoring outcome**, realized either by the cataloged Scene +Optimizer `merge` op (run scoped, §4) or by direct `Sdf`/`UsdGeom` authoring when +the op does not fit. Like the point-instancer route, the precondition is an +importable `pxr` runtime; the Usd Optimize path additionally requires `merge` in +`usdOptimize.operationsAvailable`. + +## 2. Gating — archetype-gated merge depth + +Merge is **intent- and archetype-gated**; how deep it may go is a **product +decision**, not a technical one (how much component-level identity may be +dissolved without asking). The default is **conservative**: + +- **Default (all archetypes):** merge only **clearly identity-free leaf + fragments** — the anonymous per-face/per-feature shards (`Mesh_N`-named + tessellation pieces, pads, shells) that nobody addresses individually. Named or + `kind`-tagged components are **preserved**. +- **`render` / `visualization` archetype:** may merge **aggressively up to the + named-part boundary** (the nearest `kind`/named ancestor), because a + render-only twin never addresses the parts apart. +- **`service` / `BOM` / `simulation` archetype:** keeps **component identity** and + merges only **sub-component tessellation shards** below it. Never dissolves a + reference-designator (`U302`, `R14`) or any unit the consumer selects. + +A `merge` candidate that has not been confirmed for its archetype stays +`kept_inline_for_merge` (preserving the option) — it is surfaced via the Phase-7 +iteration-2 opt-in menu (the identity-losing batch), never run automatically. No +fidelity tolerance can bound an identity loss (`operation-safety.md` § Apply +authority). + +## 3. Inputs + +- `input_stage` / target: opened as its **own root layer** (edit-target + invariant — never the composed assembly; see `restructure-mode.md`). For + instanced content, merge runs **inside the prototype** (merge once, benefit N + instances), so the target is the prototype asset, never the composed stage. +- `merge_group`: the approved fan of sibling mesh paths to fuse, already + partitioned by the **(scope × material) key** (§4) and confirmed weak/none + identity. The fragmentation suggester + (`usd-mesh-fragmentation-candidates/`) proposes these; the user/archetype + confirms. +- `merge_boundary`: the nearest ancestor with real identity (the `kind`-tagged / + named `component`) — preserved, and the ceiling the merge must not cross. + +## 4. The merge unit — (scope × material), with a GeomSubset fallback + +You can only fuse meshes that **share a material**, or fuse into one mesh that +carries a per-material `UsdGeomSubset` so bindings survive. The merge group key is +therefore **(bounded scope × material)**: + +1. **Bound the scope at the merge boundary.** Within the nearest identity-bearing + ancestor (the `component`), gather its anonymous descendant `Mesh` fan. Never + reach across a sibling component, and **preserve the boundary prim and + everything at or above it** — you destroy only the meaningless per-face + pseudo-identity below it. +2. **Partition the fan by bound material.** Each material partition fuses to **one + `Mesh`**. Bindings and bounds are preserved; introduce no dangling. +3. **GeomSubset fallback when materials must coexist in one prim.** If the + boundary should collapse to a single `Mesh` (to take the prim count to 1) but + spans several materials, fuse into one `Mesh` and author a `UsdGeomSubset` + (familyName `materialBind`) per material, re-binding each subset. This keeps + one prim while preserving every material assignment. +4. **Stop when GeomSubset overhead erodes the win.** If a scope spans many + materials, the per-subset overhead approaches the per-mesh overhead it + replaced — leave it one mesh per material (step 2) or do not merge. The merge + exists to cut prim/mesh count; a one-prim result with dozens of subsets has not. + +The skill applies **no numeric threshold** to gate the merge and does **no** +up-front vertex-coincidence test (the weld is realized by the op, not measured to +decide — see `OQ12` and §6). The (scope × material) key and the user's +archetype-gated confirmation are the whole decision. + +## 5. Rewrite + +Prefer the cataloged Usd Optimize `merge` op where it fits; fall back to direct +`Sdf`/`UsdGeom` authoring. + +**SO `merge` path (preferred).** `merge` (Merge Static Meshes) is a real, +registered op (`operations/operations.json`, canonical, intent-gated, +`risk_class: high`). + +**Run ONE scoped call PER named-component subtree — NEVER a single global call.** +For each merge boundary, pass `meshPrimPaths` = *only the anonymous fan inside that +one component*, partitioned by material, and iterate over components. Do **NOT** +run one stage-wide `merge`: a global call buckets meshes by material **across the +entire stage**, so each bucket's members span many different parents, and +`mergePoint=Parent` then resolves to their **common ancestor — the stage root**. +The result is anonymous `//merged*` blobs at the root and the named +`kind`-tagged components **emptied of their geometry** — identity destruction, not +just a size regression (observed: a global call dumped hundreds of `merged*` prims under +the stage root and pulled geometry out of its components). Scoping per component +keeps each fused mesh **nested under its own boundary** and the named parts keep +their geometry. The per-material scoping also stops the **default material-collapse** +from flattening distinct materials into one (an unscoped `merge` collapses all +bound materials, which is lossy). If the prototype namespace is an abstract +`class`, de-class it (Class→Def) so the op can author. Then run the conditional +tail: `merge → vertex-weld-where-contiguous → computeExtents` (§9 below). + +**Direct-authoring fallback.** When the op does not fit (e.g. a GeomSubset-into-one +result), author the fused `Mesh` directly: concatenate the members' `points`, +`faceVertexCounts`, `faceVertexIndices`, and per-vertex/face primvars with the +correct index offsets; author per-material `GeomSubset`s if needed (§4.3); +re-bind materials; remove the now-redundant member prims. + +In both paths: + +- **Persist with a compacting `Sdf.Layer.Export(tmp) + atomic replace`, not + `Save()`** (as for every Phase-4 target) — `Save()` appends without GC'ing the + arrays the fuse orphaned and silently grows the file. +- **Recompute extents** and verify bounds are preserved. + +**Eligibility guard (do not restate — apply it).** Before fusing, apply the +**merge-eligibility guard** in §9 below: +weak/none identity only, and `merge_bounds_coherence ≤ K` (default 2.0) — a +dispersed merge balloons the AABB, harms the spatial structure, earns no scene-graph +credit, and must not be performed. + +## 6. Preserve the pre-merge source + +Keep the pre-merge source layer. Merge and point-instancing optimize different +axes and fight at the instance boundary (once you instance a part you must +un-instance it to merge). The reconciliation is **decision order ≠ execution +order**: + +- **Decision:** choose instancing granularity FIRST — instance coarsely at the + named component; never instance below the merge unit. A sub-unit left for a + later merge is marked `kept_inline_for_merge`. +- **Execution:** merge runs INSIDE the chosen prototype and **before the + geometry-dedup tail** (`deduplicateGeometry`/value-hash) — deduped faces would + have to be un-instanced to merge. Merge once in the prototype; the win + propagates to every instance site. + +Keeping the pre-merge source lets an alternate re-addressing / merge-first variant +stay producible. + +## 7. Reporting + +Record in the manifest `phase4_targets[]`: `reduction_route: merge`, +`identity_signal` (must be weak — `structure`/`none`), `identity_disposition`, +the `merge_boundary` preserved, and the per-(scope × material) grouping. + +Emit into the optimization report (`optimization-report.schema.json`): +`steps_applied` including the merge, `preservation.allow_merge = true` with +`rendered_mesh_merged_count` (so `rendered_mesh_count + merged == known`), and — +the **authoritative silent-loss invariant** — `preservation.rendered_triangle_count`. +A merge fuses prims and welds points, so the mesh count and the distinct point +count both legitimately change; **renderable triangles must not** (a re-pack +preserves every face), within the oracle's small `triangle_tolerance_pct` for the +zero-area degenerate faces a weld cleans. Emit `preservation.merge_locality_preserved` +(and `meshes_relocated_outside_boundary`): every fused mesh must stay UNDER its +named-component boundary — a merge that relocated geometry to a shallower ancestor +or the root fails preservation even if triangles balanced. Verify by checking each +merged prim's parent against its boundary; kind-prim *survival* alone is NOT enough +(the `kind` Xforms can persist while emptied of geometry). Also emit +`merge_identity_class` (weak/none), `merge_bounds_coherence`, and +`prototype_rendered_mesh_delta_pct`. The scene-graph win is `unverified-at-render` +until a runtime profile exists. + +## 8. Non-goals + +- **Identical tiny repeats** (the same bolt ×10,000) → a **PointInstancer** + (preserves the prototype's identity; the point-instance route in + `restructure-mode.md` § Point-Instance Route), not a merge. +- **Tiny parts the consumer addresses** → leave them; prefer an identity- + preserving mesh-count remedy (instancing of identical sub-parts, GeomSubset + consolidation) over destroying identity. +- **Crossing a composition boundary** (payload / reference / variant) or a sibling + component boundary without explicit approval. +- A disk-saving claim attributed to the merge (zeroed by the report's sharing-only + guard — the merge is a scene-graph win; only the separate `vertex_weld` tail + is a disk win). + +## 9. Relationship to Usd Optimize + +After the hierarchy rewrite, Usd Optimize can still be used on the resulting +prototype assets. **Open each prototype as its own root layer** — the edit-target +invariant ([restructure-mode.md § Edit-Target Invariant](restructure-mode.md#edit-target-invariant-never-optimize-through-a-reference)). + +- **Per-prototype op chain: `meshCleanup → deduplicateGeometry → computeExtents`.** + Run it inside each prototype asset (mesh-level dedup is last-mile cleanup, not + the structuring move). +- **Within-prototype mesh merge (draw-call / scene-graph reduction), when intended.** A mesh merge + fuses many small meshes into one. It is a **draw-call / scene-graph** + win, NOT a disk win — merge concatenates geometry (bytes ~= sum, and + the crate already byte-dedups within a layer, so it can be *worse* for instanced + geometry). Run merge as a **within-prototype** operation (`merge once, benefit N + times` across every instance), never *across* an instance boundary. Op-chain + pattern: **`merge` (within-prototype) → vertex weld where geometry is contiguous + → `computeExtents`**. The weld tail is **conditional** (a no-op for dispersed + meshes), must respect **UV seams and hard normals** (weld only coincident verts + within tolerance), and any bytes it reclaims are credited to **the disk tier via the + measured weld/dedup source (`disk_win_source: vertex_weld`)** — **never** attributed + to the merge. See the **merge-eligibility guard** below before fusing anything. + The **(scope × material) grouping mechanic, the GeomSubset fallback, and the + archetype-gated merge depth** that execute the manifest `merge` disposition live + in §4 (the (scope × material) merge unit and GeomSubset fallback) and §2 + (archetype-gated merge depth) of this spec; this section owns the per-prototype + op-chain placement and the eligibility guard it cites. +- **`pruneLeaves` is stage-level cleanup, not part of the per-prototype chain.** + Guard it against **unloaded payloads**: a prim whose payload is not loaded + composes no children, so it presents as an empty leaf and is silently pruned. + Never run `pruneLeaves` over prims with unloaded payloads (load them first, or + scope the op away). See `operation-safety.md` § Caveat: `pruneLeaves` on unloaded + payloads, and `ref-remap-mode.md` § Stage-Level Cleanup. +- **Persist with a compacting `Sdf.Layer.Export(tmp) + atomic replace`, not + `layer.Save()`.** `Save()` appends without garbage-collecting dedup-orphaned + arrays and silently grows the file; `Export` recompresses and GCs. +- Run `optimizeMaterials` and other lossless cleanup on the prototype assets or + new assembly root as appropriate. +- **Lossless dead-data removal (own pass after the geometry chain).** The + geometry chain shares duplicates but does not shrink disk; the disk lever is + removing data nothing consumes. The most common case is an **unused UV set**: + when no material samples a texture coordinate, `primvars:st` (and its indices) + is dead weight, and primvars usually dominate the bytes — removing it can be the + single biggest lossless saving. This step is **fail-closed**: delete a primvar + only after **proving zero consumers** (no `UsdUVTexture` / `UsdPrimvarReader`, + no MDL, no shader input reads it) and gate by archetype — a **textured or + scanned asset keeps its UVs**. Persist with the same `Export`-compact step. + +### Merge-eligibility guard (bounds coherence) + +Only merge **spatially-coherent clusters** of meshes. Do **NOT** merge spatially +**dispersed** geometry: fusing dispersed meshes produces one oversized/overlapping +AABB that **degrades BVH/raytracing** — false ray–box hits and worse culling — so +the runtime gets *slower* even though the draw-call count dropped. + +Gate the decision on `merge_bounds_coherence` = merged-prim AABB surface area ÷ +Σ(member AABB surface area). A value near `1` means the members were adjacent (a +real draw-call win); a value far above `1` means they were dispersed. **Do not +merge when it would exceed `K` (default `2.0`).** This is the same threshold the +report scoring enforces (the `MERGE_BOUNDS_COHERENCE_MAX` constant in the optimization-report scorer): +a merge that lands `merge_bounds_coherence > K` earns **no scene-graph credit**, so a +dispersed merge is both wrong to perform and unscored. + +Merge also requires **weak/none identity** (the disposition matrix's two +identity-destroying rows). Never merge a strong-identity, addressable +`component`/`subcomponent` — that destroys per-part selectability/serviceability +and fails the preservation gate (`merge_identity_class` must be `weak` or +`none`). `merge` (`mergeStaticMeshes`) is a cataloged, intent-gated Usd Optimize +op; it stays available — this guidance bounds *when* it is eligible, it does not +remove it. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/ref-remap-mode.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/ref-remap-mode.md index 93d1ac66..a378f514 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/ref-remap-mode.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/ref-remap-mode.md @@ -1,6 +1,3 @@ - - - # Ref Remap Mode Use this reference for `apply-restructure` mode=`ref_remap` after Phase 4 mesh @@ -44,10 +41,14 @@ root and apply the same path-remap policy. ## Stage-Level Cleanup After references are stable, run lossless cleanup on the new assembly root via -`so-run-operations`: +`usd-optimize-run-operations`: - `computeExtents` -- `pruneLeaves` +- `pruneLeaves` — **guard against unloaded payloads.** A prim whose payload is not + loaded composes no children, so it presents as an empty leaf and `pruneLeaves` + silently removes it. Load payloads first, or scope the op away from prims with + unloaded payloads. See `operation-safety.md` § Caveat: `pruneLeaves` on unloaded + payloads. - `removePrims` Do not include bounded-loss operations such as `decimateMeshes` or @@ -63,7 +64,7 @@ target. Per-prototype invocations cannot delete materials introduced through references. For the Python/API fallback path, use -`skills/omniverse-usd-performance-tuning/references/so-run-operations/references/invocation.md`. +`skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/invocation.md`. ## Instanceability @@ -72,5 +73,7 @@ candidate path approved by `instancing-readiness`. ## Output Validation -Run the runner's minimum-openability check on every written USD. Record -`pass | fail | skipped` in the manifest and never delete failed outputs. +> See [Output Validation](restructure-mode.md#output-validation) in +> `restructure-mode.md` for the shared rule (run the runner's minimum-openability +> check on every written USD; record `pass | fail | skipped` in the manifest; +> never delete failed outputs). diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/restructure-mode.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/restructure-mode.md index d32d33cd..b04b5672 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/restructure-mode.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/restructure-mode.md @@ -1,6 +1,3 @@ - - - # Restructure Mode Use this reference for `apply-restructure` mode=`restructure`, invoked when @@ -33,11 +30,53 @@ Confirm: ## Dedupe Plan -When the plan includes `dedupe`, follow -`hierarchy-dedupe-rewrite-tool-spec.md` while materializing boundaries: - -- Use the candidate report from `usd-hierarchy-dedupe-candidates`. +When the plan includes `dedupe`, the mid-level instanceable-reference collapse is +authored **per descent region by the native `deduplicateHierarchies` op**, driven +by the identity-first frontier — not by a single global cut and not by a +hand-authored rewrite of the whole candidate report. The frontier decision core +(`usd-hierarchy-dedupe-candidates/scripts/select_frontier.py`) selects, at each +level, the `paths` set and a **small per-region `maxDepth`**; the per-level driver +invokes `deduplicateHierarchies(paths=[node], maxDepth=)` on +each descent node and recurses (the native form of Phase 2g's "re-run boundary +inference on each extracted asset"). The op authors the internal instanceable +references; the driver owns the identity gate and emits the restructure-role +manifest (`kept_inline_for_merge` tagging, `descent_converged`, +`final_rescan_new_groups_above_floor`). Do **not** set one stage-wide `maxDepth` +and run once — named units sit at varying depths, so no single global cut lands on +the ragged frontier (see the `deduplicateHierarchies` catalog entry in +`operations/operations.json` for the measured depth→grain evidence). The +hand-authored `Sdf` path stays permitted for what the native op does not cover: +external-prototype materialization into payload files (below) and any boundary the +op cannot author cleanly. + +While materializing boundaries: + +- Use the candidate report from `usd-hierarchy-dedupe-candidates`; the frontier + (`select_frontier.py`) chooses the grain identity-first (`kind` → naming → + semantics; the hash only confirms reuse). - Keep only user-approved, non-overlapping candidate groups. +- **Author a bottom-up nested library by default** (the "author nested, not flat" + rule in `workflow.md` Phase 2g): parent prototypes *reference* child prototypes + rather than inlining them. Flat / outermost-only sharing is insufficient for + multi-file disk recovery. Honor the MINP inclusion floor, keep sub-floor leaves + inline for later merge, and on a mostly-identical-with-outliers group share the + majority and recurse only into the variant's differing branches. +- **Mesh merge is a WITHIN-prototype prim-count reduction, not a sharing move.** + It is a first-class Phase-4 step that EXECUTES the manifest `merge` disposition + (not a "someday" option): run `merge` *inside* a prototype (merge once, benefit + N instances), never across an instance boundary. The payoff is a + scene-graph win — cheaper stage-open + composition/traversal + per-prim memory, + plus fewer draw calls — NOT a disk win (bytes ~= sum; the crate already + byte-dedups). It is intent-gated (it destroys per-part addressability) and gated + on bounds coherence and weak/none identity, with a conditional vertex-weld tail + whose reclaimed bytes are credited to the disk tier via the weld source. Full op-chain + + eligibility: `mesh-merge-rewrite-spec.md` §9 (per-prototype op chain + + merge-eligibility guard). +- **Read existing composition first**: when the input arrives already instanced or + BIM/CAD-exported, treat existing prototypes as the candidate set at that level + (collapsing byte-identical-but-separately-authored prototypes) and resume the + descent there rather than restarting from the top (`workflow.md` Phase 2g, + "resume the descent from the level the asset is already at"). - Prefer `external_prototype` unless the user explicitly chooses `internal_reference`. - Inline local material bindings and UsdShade networks that cross the boundary @@ -127,6 +166,156 @@ Use: - `prim.SetActive(False)` only when deactivation is the chosen reversible alternative to deletion. +### Material-Network Closure at a Prototype Boundary + +The native `deduplicateHierarchies` op collapses structurally-identical subtrees +and preserves their bindings, but it does **not** judge what counts as a *valid* +prototype boundary when a material network crosses that boundary. That decision +stays here: whenever a subtree is externalized as a prototype (native-op internal +reference, hand-authored external prototype, or point-instancer prototype), decide +material-network closure before the boundary is final. + +Cross-boundary material relationships are common in CAD and digital twin assets: +duplicate equipment, furniture, or HVAC assemblies often bind geometry inside the +candidate subtree to materials under a shared `/Looks`, `/Materials`, or similar +scope outside that subtree. If those relationships are left pointing at the source +stage, the prototype is harder to validate, version, move, and optimize +independently. + +When `material_policy=inline_local_external` (the default), inline local material +dependencies into each prototype: + +1. For the canonical source subtree, collect authored material bindings and + UsdShade connections whose targets are outside the selected subtree. +2. Treat material targets as inlineable when the target prim is part of the input + stage or package and is not an explicit external material-library dependency. +3. Build the material-network closure for each inlineable material: the Material + prim, Shader and NodeGraph descendants, and connected shader or nodegraph prims + required by that network. +4. Copy each material network into the prototype, preferably under a stable child + scope such as `//Looks`. +5. Rewrite copied geometry bindings and copied shader connections so they target + the inlined material-network paths. +6. Preserve texture and other asset-valued inputs, but validate that they still + resolve from the prototype layer. If a relative asset path would stop resolving, + rewrite it relative to the prototype layer or mark the group `blocked` until the + dependency move is explicit. + +Do not decide material equivalence by material prim name alone. If different copies +bind to different material paths, compare the material-network closure or split the +candidate group. If the material networks differ, skip the group or leave the +affected sites uninstanceable; do not silently collapse distinct looks. + +When `material_policy=preserve_external`, keep external material targets and record +them in the manifest. When `material_policy=block_on_external`, block any selected +group with material bindings or shader connections that cross the prototype +boundary. + +## Point-Instance Route + +Use this for the reduction frontier's **`reduction_route = point_instance`** +decision (a scene-graph / draw-call win): replace many **anonymous, high-count +repeated** prims with a single `UsdGeomPointInstancer` — one (or a few) +prototype(s) plus `protoIndices`, `positions`, `orientations`, and `scales` arrays. + +**It is identity-losing and intent-gated.** Geometry is preserved, but per-prim +path addressability collapses into instance indices. It is reserved for the +disposition matrix's weak-identity row only: + +- **Eligible:** anonymous / `structural_fallback` units, in **very high counts**, + with **no path-level addressability need** (bolts, fasteners, vegetation, + repeated fixtures) — the `instancing-tradeoffs.md` "point instancer" row. +- **Never:** an addressable / `kind` / named / semantic subcomponent, anything + articulated / physics-bearing / variant-bearing, or any unit a maintenance or + service twin must select per-instance. The manifest contract (`identity_signal` + in {kind, naming, semantic} with `reduction_route` point_instance) **fails** this + gate — enforced in `usd-hierarchy-dedupe-candidates/scripts/select_frontier.py` + and `validate_report.py` `validate_manifest_structure`. + +It is **intent-gated for all archetypes** — no fidelity tolerance can bound an +identity loss (`operation-safety.md` § Apply authority). It is surfaced via the +Phase-7 iteration-2 opt-in menu (the identity-losing batch), never run +automatically. A `point_instance` candidate that has not been confirmed stays +`kept_inline_for_merge` instead (preserving within-prototype merge-ability). + +**Mechanism.** For the confirmed, intent-gated route, the native +`deduplicateGeometry(duplicateMethod=4)` op authors the `UsdGeomPointInstancer` +directly (usd-optimize 1.0.4+; issue #169). Where the native op does not fit — +notably external-prototype materialization into payload files — the hand-authored +path stays permitted: author the `UsdGeomPointInstancer` directly via the USD API. +That hand-authored path is a **USD authoring route**, **not a Usd Optimize +operation**, so it does **not** require a `usdOptimize.operationsAvailable` check; +its only precondition is an importable `pxr` (USD Python) runtime. Either way: +open the target as its **own root layer** (edit-target invariant), partition +occurrences into one value-variant per prototype, author the instancer at a stable +parent path with the prototype under its `prototypes` rel, decompose each +occurrence's transform into `positions` / `orientations` / `scales` with its +`protoIndices` id, remove the now-redundant per-occurrence prims, recompute +extents, and persist with the compacting `Sdf.Layer.Export` + atomic replace (not +`Save()`). + +**Material boundary.** This route inherits the same material-boundary problem as +hierarchy dedupe: bindings that cross the prototype boundary are silently dropped +when geometry moves into a Point Instancer prototype. Run the +[Material-Network Closure](#material-network-closure-at-a-prototype-boundary) step +above before rewriting. A PI rewrite that has not run that collection step is not +safe to apply. + +**Preserve the pre-instanced source.** Keep the pre-instanced source layer so an +alternate merge-first (draw-call-bound) deliverable can still be produced. +Point-instancing and mesh-merge optimize different axes; pick per target intent +(memory-bound vs draw-call-bound). Record in the manifest `phase4_targets[]`: +`reduction_route: point_instance`, `identity_signal` (must be weak — +`none`/`structural_fallback`), `copy_count`, and the `arc_estimate` contrast. The +scene-graph win is `unverified-at-render` until a Kit/omniperf profile exists. + +Do not use this route to convert addressable subcomponents (use references / the +nested library) or to animate populations (clip-driven Point Instancers are a +modeling choice, not this reduction route). + +## Post-Restructure Placement Check (mechanism-agnostic guardrail) + +Run the per-prim placement-drift gate after every restructure, **regardless of +which mechanism authored the references** — native `deduplicateHierarchies`, +hand-authored `Sdf`, or the point-instance route. It compares each mesh's +placement before and after and fails the restructure if any prim moved beyond +tolerance. + +Keep it for two honest reasons, and **not** because the native op drifts: + +- **The native op is transform-correct.** A dedicated drill-down measured it + placement-correct to sub-micron — max per-mesh world-centroid displacement + **0.00028 mm** across an **85,871-mesh automotive assembly**, by a path-based + 1:1 comparison of every mesh; rendered mesh count preserved at every depth. The + op excludes the root `xformOp:*` from identity and preserves each duplicate's + local transform by construction, so no hand-rolled transform-correct placement + is needed. +- **Cheap insurance over a still-permitted path.** The gate is cheap, and the + hand-authored `Sdf` paths remain permitted for what the op does not cover + (external-prototype materialization, material-network closure, direct + point-instancer authoring). A mechanism-agnostic check covers those paths too, + so the guardrail earns its keep without overstating native-op risk. + +## Edit-Target Invariant (never optimize through a reference) + +Usd Optimize authors into the stage's **current edit-target (root) layer**. +If a prototype / library arrives via a reference and you run SO on the *composed +assembly*, the edits land as **overrides on the assembly layer** while the +referenced library keeps its heavy geometry — that is override bloat, not +reduction. Therefore: + +- **Each library / sub-asset is opened as its OWN root layer** so SO's edit + target *is* that file's bytes. "Optimize the assembly in one pass" is wrong. + This is exactly the per-sub-asset parallel model the batch scheduler batches — + one target = one own-layer file = one job. +- **De-class abstract `class` prototype namespaces (`Class → Def`) before the + chain, and restore after.** Optimizing an abstract `class` namespace silently + no-ops: a default-predicate stage walk returns 0 of its meshes (see the + zero-work diagnostic below). +- **Every library file must resolve standalone** — its own material bindings and + nested children reachable via explicit asset paths — to be a valid independent + edit target. + ## Authoring Requirements (Critical for Phase 4 Compatibility) - `Sdf.CopySpec` preserves the source specifier. If copying from an over-only @@ -141,10 +330,13 @@ Use: ### Why Specifier Correctness Is Critical -Scene Optimizer operations that use USD's default-predicate prim traversal +Usd Optimize operations that use USD's default-predicate prim traversal (including `decimateMeshes`, `meshCleanup`, `fitPrimitives`, `removeSmallGeometry`) will **silently skip** all meshes under Over-spec ancestors. The operation returns -`success=True` with zero work done — no error, no warning, no indication of failure. +`success=True` with zero work done, and the tool itself surfaces no error or warning +to signal the failure. Because these operations mutate or delete geometry, warn the +user and get explicit confirmation before running them, and proactively raise this +silent-skip risk yourself — do not proceed on the tool's silent `success=True` alone. Operations that enumerate via material bindings or instance indices (`deduplicateGeometry`, `removeUnusedUVs`, `optimizeMaterials`) may still work, diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/scripts/apply-restructure-manifest.schema.json b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/scripts/apply-restructure-manifest.schema.json index 6e8d269b..6de093f9 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/scripts/apply-restructure-manifest.schema.json +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/scripts/apply-restructure-manifest.schema.json @@ -2,7 +2,7 @@ "$comment": "SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.\nSPDX-License-Identifier: Apache-2.0", "$schema": "http://json-schema.org/draft-07/schema#", "title": "Apply-Restructure Manifest", - "description": "Contract for /apply-restructure-manifest.json, the Phase 2f -> Phase 4 handoff. phase4_targets[] is the authoritative list of files Phase 4 must mesh-optimize; the final optimization-report's target_coverage must cover the UNION of every iteration's phase4_targets (see validate_report.py --manifest). A mode=restructure manifest MUST carry a non-empty phase4_targets[], and every entry MUST declare its default-predicate mesh_count so a 'skipped_zero_meshes' disposition cannot be faked.", + "description": "Contract for /apply-restructure-manifest.json, the Phase 2f -> Phase 4 handoff. phase4_targets[] is the authoritative list of files Phase 4 must mesh-optimize; the final optimization-report's target_coverage must cover the UNION of every iteration's phase4_targets (see validate_report.py --manifest). A mode=restructure manifest MUST carry a non-empty phase4_targets[], and every entry MUST declare its default-predicate mesh_count so a 'skipped_zero_meshes' disposition cannot be faked. apply-restructure POSTCONDITION: when extraction leaves > 0 mesh prims on the assembly root, record the authoritative residual count under 'assembly_root' AND list that same root in phase4_targets[] as target_class 'assembly_root'. validate_manifest_structure() fails loud if assembly_root.mesh_count > 0 has no matching phase4_targets[] entry.", "type": "object", "required": ["mode", "phase4_targets"], "properties": { @@ -13,6 +13,21 @@ "input_stage": { "type": "string" }, "output_dir": { "type": "string" }, "new_assembly_root": { "type": "string" }, + "assembly_root": { + "type": "object", + "description": "Residual-mesh state of the new assembly root after extraction, measured by apply-restructure with the USD stage open. When mesh_count > 0 the manifest MUST also list this root in phase4_targets[] with target_class 'assembly_root' (enforced by validate_manifest_structure), so a retained-mesh assembly root is never silently dropped from Phase 4.", + "properties": { + "path": { + "type": "string", + "description": "The new assembly-root file path; matches the phase4_targets[] assembly_root entry path when residual meshes exist." + }, + "mesh_count": { + "type": "integer", + "minimum": 0, + "description": "Authoritative default-predicate mesh count remaining on the assembly root after extraction (len of Usd.PrimRange.Stage(stage, Usd.PrimDefaultPredicate) filtered to UsdGeom.Mesh)." + } + } + }, "outputs": { "type": "array", "items": { @@ -32,7 +47,7 @@ }, "phase4_targets": { "type": "array", - "description": "Every written prototype/shared layer/loadable sub-asset that needs Phase 4 mesh optimization, PLUS the assembly root itself when it retains > 0 meshes after extraction.", + "description": "Every written prototype/shared layer/loadable sub-asset that needs Phase 4 mesh optimization, PLUS the assembly root itself when it retains > 0 meshes after extraction. ONLY path, target_class, and mesh_count are required output; all other members (copy_count, own_*, value_variant_*, arc_estimate, decision_reason, grain_source, package_group, descent_level, weight_hints, frontier.by_* rollups, etc.) are OPTIONAL decision/audit trail — select_frontier.py writes them and humans read them, but no machine gate consumes them, so they are never mandatory.", "items": { "type": "object", "required": ["path", "target_class", "mesh_count"], @@ -54,7 +69,130 @@ "type": "string", "enum": ["shared_first", "dependent_after", "independent"] }, + "level": { + "type": "string", + "enum": ["assembly", "component", "subcomponent"], + "description": "Target-tree tag (= USD `kind`). Drives the bounded-descent stopping rule (workflow.md Phase 2g): descend while there are dedupe/semantic boundaries AND (level < component OR the node is important)." + }, + "importance": { + "type": "string", + "enum": ["important", "normal"], + "description": "Target-tree tag. Descend to `subcomponent` only for `important` sub-hierarchies. Also a functional-tolerance signal input (with `articulated`) for the auto-within-tolerance lossy gate in operation-safety.md." + }, + "articulated": { + "type": "boolean", + "description": "Target-tree tag. True for articulated / physics / variant-bearing nodes. Articulated assets instance at rigid-body/link level (factory guide Step 4), never whole-asset. Also a functional-tolerance signal that drops bounded-loss ops from auto-within-tolerance back to intent-gated." + }, + "archetype": { + "type": "string", + "enum": ["large-spatial", "encapsulated-product", "piping", "generic"], + "description": "Target-tree tag, derived from semantic_label + structural signals. Selects which Phase-4 op-chain steps apply and the per-target scale-banded tolerance (see workflow.md op chain + usd-optimize-run-operations/references/units-and-tolerances.md)." + }, "source": { "type": "string" }, + "descent_level": { + "type": "string", + "enum": ["assembly", "component", "subcomponent", "detail"], + "description": "Descent frontier level. Carries the resume-from-existing-level entry point: when the input arrives already instanced / BIM-CAD-exported, the descent ENTERS at the level the asset is already at rather than restarting from the top." + }, + "identity_disposition": { + "type": "string", + "enum": ["externalize_shared", "internal_share", "keep_local"], + "description": "Frontier Axis A (where the definition lives; identity preserved). externalize_shared = nested external referenced prototype reused across components; internal_share = shared inside one parent; keep_local = meaningful one-off cleaned in place." + }, + "reduction_route": { + "type": "string", + "enum": ["point_instance", "merge", "fit_primitive", "mesh_cleanup_leaf", "none"], + "description": "Frontier Axis B (optional reduction). point_instance / merge are IDENTITY-LOSING (intent-gated, weak-identity units only). fit_primitive is identity-PRESERVING bounded-loss (the step-3 fitPrimitives op). mesh_cleanup_leaf is terminal lossless cleanup. none = placement only." + }, + "identity_signal": { + "type": "string", + "enum": ["kind", "naming", "semantic", "structural_fallback", "none"], + "description": "Which signal set the grain (the queryable boundary basis). kind/naming/semantic = STRONG authored identity; structural_fallback = identity absent, the coarsest repeating subtree proposed the grain (never a leaf); none = anonymous geometry. REQUIRED on every shared (externalize_shared/internal_share) or identity-destroying (point_instance/merge) entry. A shared entry with identity_signal=none (landed on anonymous meshes) fails the contract; an identity-destroying route on a strong-identity unit (kind/naming/semantic) fails the contract." + }, + "grain_source": { + "type": "string", + "enum": ["identity", "structural_fallback"], + "description": "Whether the grain came from authored identity (default) or the structural-fallback (coarsest repeating subtree where identity is absent)." + }, + "kind_untrusted": { + "type": "boolean", + "description": "Kind-trust preflight (finder spec §6.0.1, issue #172): true when this unit carried an authored kind that was demoted STAGE-WIDE because kind does not partition geometry (~1 mesh per component on monolithic CAD imports). The grain was re-derived structurally (grain_source=structural_fallback); the frontier.kind_trust block carries the sampled stats that justified the demotion." + }, + "value_variant_id": { + "type": ["string", "integer"], + "description": "Value-variant partition id within a structural group (one prototype per genuine variant, e.g. a group of 18 near-identical copies that partitions into 17 identical plus 1 real variant)." + }, + "value_variant_count": { + "type": "integer", + "minimum": 1, + "description": "Number of genuine value-variants in this candidate's structural group." + }, + "nested_parent_proto": { + "type": "string", + "description": "The parent prototype that references this one (the nested-library link; parents reference child prototypes, not inline copies)." + }, + "parent_target_id": { "type": "string" }, + "share_scope": { + "type": "string", + "enum": ["cross_component", "internal_parent", "none"] + }, + "own_prims": { + "type": "integer", + "minimum": 0, + "description": "NON-double-counted own prim count (a parent and its nested child do not both claim the same savings)." + }, + "own_meshes": { "type": "integer", "minimum": 0 }, + "own_points": { "type": "integer", "minimum": 0 }, + "copy_count": { + "type": "integer", + "minimum": 1, + "description": "Number of occurrences of this unit across distinct parents." + }, + "below_externalization_cutoff": { + "type": "boolean", + "description": "Input condition (not a disposition): the candidate did not pass the band-resolved externalization cutoff (copy_count / own-size). decision_reason carries the route taken." + }, + "kept_inline_for_merge": { + "type": "boolean", + "description": "Sub-MINP leaf intentionally NOT instanced so a later within-prototype mesh-merge can fuse it (instancing finely bakes in granularity a merge pass would have to tear down)." + }, + "non_double_counted_savings": { "type": "integer", "minimum": 0 }, + "arc_estimate": { + "type": "object", + "description": "Load-bearing anti-failure evidence: arcs if shared at the frontier vs arcs at mesh level (empirically ~100-150 vs ~156,691). A descent that explodes arcs without reusing proportionally more DISTINCT data is too deep.", + "properties": { + "frontier": { "type": "integer", "minimum": 0 }, + "mesh_level": { "type": "integer", "minimum": 0 } + } + }, + "package_group": { + "type": "string", + "description": "Advisory packaging grouping hint (discipline / system / family library) when externalized. Must not pull deployment packaging forward." + }, + "frontier_estimate_basis": { + "type": "string", + "enum": ["exact", "spot_check"], + "description": "Set to spot_check when the cost guard degraded the frontier scan to a masked spot-check on a large stage." + }, + "decision_reason": { + "type": "object", + "description": "Audit trail of the boundary call (NOT free text): which identity signal set the grain and which stop condition or descend trigger fired. Makes a too-deep or identity-destroying choice visible and reviewable rather than silent.", + "properties": { + "identity_signal": { + "type": "string", + "enum": ["kind", "naming", "semantic", "structural_fallback", "none"] + }, + "stop_condition": { + "type": "string", + "enum": ["min_meaningful_unit", "arc_cost", "below_floor"] + }, + "descend_trigger": { + "type": "string", + "enum": ["variant_outlier", "unique_container_shared_children"] + }, + "note": { "type": "string" } + } + }, "weight_hints": { "type": "object", "description": "Optional pre-extraction estimates for adaptive batching. NON-authoritative; mesh_count above is the authoritative count the gate uses." @@ -63,6 +201,102 @@ } } }, + "frontier": { + "type": "object", + "description": "Descent frontier summary. Carries the MEASURED remaining reuse so a scene-graph / consolidation win can only be reported from measurement, never estimated. When any phase4_targets[] entry is a shared (externalize_shared / internal_share) disposition, reuse_measured MUST be true (a consolidation claim requires measurement). When measured reuse is low, the plan pivots to the disk tier rather than forcing more sharing.", + "properties": { + "reuse_measured": { + "type": "boolean", + "description": "True when the remaining reuse was MEASURED (distinct vs total prototypes/units), not estimated. Required true whenever a shared disposition is claimed." + }, + "distinct_prototypes": { "type": "integer", "minimum": 0 }, + "total_units": { "type": "integer", "minimum": 0 }, + "descent_entry_level": { + "type": "string", + "enum": ["assembly", "component", "subcomponent", "detail"], + "description": "Resume-from-existing-level: the level the descent ENTERED at when the input arrived already partway down (already instanced / BIM-CAD). The stop/descend rules are unchanged from there." + }, + "descent_converged": { + "type": "boolean", + "description": "Convergence gate: true only when a re-run of the reuse analyzer on the authored structure surfaced NO new shareable group above the inclusion floor (MINP, occurrence >=2) — the descent reached a fixpoint. The remaining residue is sub-MINP kept_inline_for_merge leaves, already-split value-variants, or unique content. Phase 4 geometry ops (decimation, within-prototype merge) must NOT run until this is true; otherwise geometry is reduced/merged on a structure further sharing would still have collapsed, and a merge runs before its kept_inline_for_merge leaves were reserved." + }, + "final_rescan_new_groups_above_floor": { + "type": "integer", + "minimum": 0, + "description": "Evidence for descent_converged: the number of NEW shareable groups above the inclusion floor that the final convergence re-scan found. 0 == converged. A positive value with descent_converged=true is a contradiction the contract should reject." + }, + "low_reuse_disk_tier_pivot": { + "type": "boolean", + "description": "True when measured reuse was low (e.g. parametric MEP geometry, mostly unique) and the plan pivoted to the disk tier (unused-primvar removal, primitive-fit, decimation) instead of forcing sharing." + }, + "by_identity_signal": { + "type": "object", + "description": "Optional audit rollup: count of phase4_targets[] by their identity_signal. A quick read of how much of the frontier rests on strong authored identity (kind/naming/semantic) vs the structural_fallback grain vs anonymous (none). Additive; emitted by select_frontier.py.", + "properties": { + "kind": { "type": "integer", "minimum": 0 }, + "naming": { "type": "integer", "minimum": 0 }, + "semantic": { "type": "integer", "minimum": 0 }, + "structural_fallback": { "type": "integer", "minimum": 0 }, + "none": { "type": "integer", "minimum": 0 } + } + }, + "by_disposition": { + "type": "object", + "description": "Optional audit rollup: count of phase4_targets[] by their identity_disposition. Additive; emitted by select_frontier.py.", + "properties": { + "externalize_shared": { "type": "integer", "minimum": 0 }, + "internal_share": { "type": "integer", "minimum": 0 }, + "keep_local": { "type": "integer", "minimum": 0 } + } + }, + "by_stop_condition": { + "type": "object", + "description": "Optional audit rollup: count of phase4_targets[] by their decision_reason.stop_condition. Additive; emitted by select_frontier.py.", + "properties": { + "min_meaningful_unit": { "type": "integer", "minimum": 0 }, + "below_floor": { "type": "integer", "minimum": 0 } + } + }, + "frontier_estimate_basis": { + "type": "string", + "enum": ["exact", "spot_check"] + }, + "kind_trust": { + "type": "object", + "description": "Optional audit block (finder spec §6.0.1, issue #172): the stage-wide meshes-per-kind preflight stats, so a sampled-and-REJECTED kind is auditable in the manifest (why kind-labeled units arrived as structural_fallback / kind_untrusted). Additive; emitted by the finder's --emit-candidates packet and passed through by select_frontier.py.", + "properties": { + "kind_trusted": { + "type": "boolean", + "description": "False when kind failed the preflight (single_mesh_fraction >= max_single_mesh_fraction OR median_meshes_per_kind <= 1) and kind-derived identity was demoted." + }, + "sampled_kind_prims": { + "type": "integer", + "minimum": 0, + "description": "Stage-wide sample size: walked prims with an authored kind in {component, subcomponent, group}." + }, + "single_mesh_fraction": { + "type": "number", + "minimum": 0, + "maximum": 1, + "description": "Fraction of sampled kind prims whose subtree holds <= 1 mesh." + }, + "median_meshes_per_kind": { + "type": ["number", "null"], + "description": "Median subtree mesh count across the sample (null when the sample is empty)." + }, + "max_single_mesh_fraction": { + "type": "number", + "description": "The KIND_TRUST_MAX_SINGLE_MESH_FRACTION threshold the run used (default 0.80)." + }, + "articulation_check": { + "type": "string", + "enum": ["enabled", "unavailable"], + "description": "Whether the walk-up articulation stop could consult UsdPhysics; 'unavailable' means the guard was skipped gracefully." + } + } + } + } + }, "rewrite_steps": { "type": "array" }, "material_rewrites": { "type": "array" }, "warnings": { "type": "array" } diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/asset-structure-principles.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/asset-structure-principles.md index af3064fe..f6fe0ff0 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/asset-structure-principles.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/asset-structure-principles.md @@ -1,6 +1,3 @@ - - - # Principles of Scalable Asset Structure in OpenUSD > **Canonical URL:** https://docs.omniverse.nvidia.com/usd/latest/learn-openusd/independent/asset-structure-principles.html @@ -981,7 +978,7 @@ def Xform "Neighborhood" ( } ## Principles Quick Reference -A scalable asset structure promotes the scalability needs of an organization by being **legible**, **modular**, **performant**, and **navigable**. +A condensed checklist of the four properties introduced in [Planning an Asset Structure](#planning-an-asset-structure) — **legible**, **modular**, **performant**, **navigable**. ### Legibility *A legible asset structure should be easy to inspect and onboard new users familiar with a domain.* diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/composition-audit.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/composition-audit.md index cb503722..0457fb94 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/composition-audit.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/composition-audit.md @@ -1,6 +1,3 @@ - - - # USD Composition Audit > Composition audit is performed as part of `usd-structure-assessment` SA Stage 1; this reference holds the deeper checklist, findings taxonomy, and output schema mapping. @@ -17,7 +14,7 @@ This is invoked as a section of `usd-structure-assessment` SA Stage 1 (compositi This reference is the canonical guidance for composition auditing. It produces findings consumed by: -- The umbrella `usd-structure-assessment` JSON shape (the agent's day-to-day output) - composition findings appear under that report's `composition`, `assets`, and `layer_health` sections (see `usd-structure-assessment/README.md` Output section). +- The umbrella `usd-structure-assessment` JSON shape (the agent's day-to-day output) - composition findings appear under that report's `composition` and `assets` sections (see `usd-structure-assessment/README.md` Output section). - The standalone `../scripts/audit-report.schema.json` shape, which is preserved for tools and pipelines that consume composition-only audit output without the full SA umbrella. Treat `audit-report.schema.json` as a sub-shape: the SA report is a superset that includes (and may inline) the audit-report fields. When in doubt, write the SA umbrella shape - the audit-report subset is recoverable from it. @@ -38,7 +35,7 @@ When in doubt, write the SA umbrella shape - the audit-report subset is recovera - Treat unresolved asset paths, unloaded payloads, and ambiguous generated layers as blockers or open questions in the report. - If no safe edit target is obvious, hand off to `usd-edit-target-planner` instead of guessing. -- For data-heavy `.usda` or runtime `.usdz` inputs, call out the packaging risk before Scene Optimizer handoff. +- For data-heavy `.usda` or runtime `.usdz` inputs, call out the packaging risk before Usd Optimize handoff. ## Examples @@ -68,8 +65,8 @@ When in doubt, write the SA umbrella shape - the audit-report subset is recovera - Processor blockers. - Candidate edit targets. - Payloads or variants requiring separate coverage. -- Evidence needed before Scene Optimizer handoff. -- **Referenced asset manifest** - a list of unique asset layer paths that contain geometry or material data via references or payloads. Downstream skills (`usd-edit-target-planner`, `apply-restructure`, Scene Optimizer handoff) need this list to plan per-asset optimization. +- Evidence needed before Usd Optimize handoff. +- **Referenced asset manifest** - a list of unique asset layer paths that contain geometry or material data via references or payloads. Downstream skills (`usd-edit-target-planner`, `apply-restructure`, Usd Optimize handoff) need this list to plan per-asset optimization. ## Output @@ -85,9 +82,10 @@ Emit composition findings into the `usd-structure-assessment` umbrella report (p ## References -Before auditing, read these to understand asset structure and the distinction between assets, layers, and composition arcs: - -- `skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/asset-structure-principles.md` - what an asset is, interface/payload/geometry layers, the reference-payload pattern. -- `skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/factory-level-structuring.md` - how assets compose into assemblies, asset boundary identification. +Before auditing, read the asset-structure references — `asset-structure-principles.md` +and `factory-level-structuring.md` — to understand the distinction between assets, +layers, and composition arcs. These are the same prerequisites listed in +[usd-structure-assessment/README.md § References](../README.md#references), kept in +one place there. If you have network access, prefer the live URLs (noted in each reference file) for the most current version. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/factory-level-structuring.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/factory-level-structuring.md index 29f991f2..ae2d70ea 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/factory-level-structuring.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/factory-level-structuring.md @@ -1,6 +1,3 @@ - - - # Factory-Level USD Structuring > **Canonical URL:** https://docs.omniverse.nvidia.com/vfi/latest/guide/factory-level-structuring.html diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/README.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/README.md index 940b9515..af74eaac 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/README.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/README.md @@ -1,27 +1,18 @@ # Instancing Readiness - - - -## When to Use - -Use when checking repeated USD references for safe instanceable authoring after structure assessment. - ## Instructions -1. Confirm the target asset, artifact, or user intent and check the prerequisites listed below. -2. Read only the referenced files needed for the current phase, failure mode, or output contract. -3. Follow the workflow, rules, and safety gates in this reference before invoking downstream references or shell commands. -4. Return the result using the Output Format section and name any blocked prerequisite or unresolved user decision. +See `references/_shared/standard-instructions.md`. ## Output Format -Return a concise status or report that names the input, selected runtime or evidence source, actions planned or performed, artifacts written, blockers, and the next validation or user-decision step. When a schema or template is referenced below, conform to that contract. +See `references/_shared/standard-output-format.md`. -## Purpose +## Purpose / When to Use Use this reference after `usd-structure-assessment` identifies repeated references -that are instancing candidates. This reference determines whether each candidate +that are instancing candidates — i.e. when checking repeated USD references for +safe `instanceable` authoring. This reference determines whether each candidate can safely be marked `instanceable = true` without breaking the scene. ## Prerequisites diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-guide.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-guide.md index 08d3e2c8..ac0ed3c5 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-guide.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-guide.md @@ -1,6 +1,3 @@ - - - # Asset Modularity and Instancing > **Canonical URLs:** @@ -134,57 +131,21 @@ scenario.usda ### By hierarchical inheritance Instances can be spatially varied because transformation operations in OpenUSD are hierarchical. Properties that have computed hierarchical inheritance are expected to work with instancing. For example, an instance with an “invisible” ancestor should never be imaged, regardless of the visibility state of the “prototype”. -scenario.usda - 1#usda 1.0 - 2 - 3def Scope "Factory" - 4 ( - 5 references = @./factory.usda@ - 6 ) - 7{ - 8 over "AssembledBarrels" () { - 9 # Visibility is inherited from the ancestor prim into the instances -10 token visibility = "invisible" -11 } -12} +*`scenario.usda` — identical to the version shown earlier in this guide.* Properties that don’t have inheritance semantics must be varied through composition arcs to preserve instancing (see “refining instances” below). ### By parameterization -There are two ways instance root prims can be parameterized: primvars and variants. +Instance root prims are parameterized the same two ways as any asset entrypoint — +primvars and variants. The mechanics, the `RaceCar` variant/primvar examples, and +the public-interface conventions are documented once in +[asset-structure-principles.md § Asset Parameterization](../../asset-structure-principles.md#asset-parameterization). -The example below applies parameterization to an instanced asset. - -The root prim of an asset will be the first place where a user goes to figure out if prims have discrete variants. Asset structures may enforce naming conventions and the presence of specific variants. For example, it may be expected that assets provide color_variant to describe supported albedo variations. - -def Xform "RaceCar" ( - variantSets = ["color_variant"] - ) { - variantSet "colorVariant" = { - - "red" { ... } - "blue" { ... } - "green" { ... } - - } - } - -Some variation cannot be effectively or efficiently discretized into variants. For these cases, primvars can be used as another form of asset parameterization. Primvars are extra interpolatable parameters primarily for Gprim prims to provide additional data to shading contexts. In OpenUSD, primvars have inheritance semantics and can be authored on parent scopes, including the entrypoint of an instance. Materials can be constructed to read primvars:asset_base_color or other entrypoint primvars. In the event that multiple prims in a hierarchy author the same primvar, keep in mind that child opinions are stronger than parents. Below, we use `asset_` as a prefix to avoid namespace collisions. - -def Xform "RaceCar" { - - color3f primvars:asset_base_color ( - doc = "primary paint color" - ) - - color3f primvars:asset_accent_color ( - doc = "color of accent stripe" - ) -} - -Unless otherwise documented or annotated as internal, variants and primvars authored on an asset entrypoint should be generally considered “public” and safe for downstream contexts to edit and set with an expectation of stability. - -Both variant selection and primvars on the asset entrypoint are compatible with scene graph instancing. Variations of variant selections will generate new prototypes for downstream contexts while primvars will not. This generally makes parameterization through primvars the lighter choice for single property parameters, providing upfront memory savings at the cost of additional lookups in materials. +Two points specific to instancing: variant selections that differ between +instances generate new prototypes (one per unique selection), while primvars do +not — so for single-property variation, primvars are the lighter parameterization +on an instance, trading a little material-lookup cost for not multiplying +prototypes. ### Explicit “Refinement Namespaces” OpenUSD’s prototypes are implicit and read only. However, because they are keyed off of composition, it is possible to construct arcs in a way that provide a namespace (prim) where explicit prototype edits can be placed. Depending on the use case, the specific placement and contents of the namespace might be different. For example, it may contain the entire definition of the asset or simply provide an opportunity for downstream consumers to add refining edits. @@ -466,20 +427,7 @@ barrel.usda This allows downstream consumers to add edits into all Barrel instances in the stage, regardless of their depth of instancing. -scenario.usda - 1#usda 1.0 - 2 - 3class Scope "prototypes" { - 4 over "Barrel" { - 5 over "Geometry" { - 6 over "barrel" { - 7 color3f[] primvars:displayColor = [(.6, .2, .2)] - 8 } - 9 } -10 } -11} -12 -13def "Factory" (references = @./factory.usda@) {} +*`scenario.usda` — identical to the version shown earlier in this guide.* At the point of assembly Specialize and inherit arcs are computationally more expensive than references and payloads (because they are evaluated “live”). Projects may also consume assets from external libraries, so it’s not always possible to add the arcs into the assets. @@ -522,20 +470,7 @@ factory.usda 33 } 34} -scenario.usda - 1#usda 1.0 - 2 - 3class Scope "prototypes" { - 4 over "Barrel" { - 5 over "Geometry" { - 6 over "barrel" { - 7 color3f[] primvars:displayColor = [(.6, .2, .2)] - 8 } - 9 } -10 } -11} -12 -13def "Factory" (references = @./factory.usda@) {} +*`scenario.usda` — identical to the version shown earlier in this guide.* This makes it possible to “inject” opinions into instanceable, externally referenced assets. @@ -591,20 +526,7 @@ factory.usda 38 } 39} -scenario.usda - 1#usda 1.0 - 2 - 3class Scope "prototypes" { - 4 over "Barrel" { - 5 over "Geometry" { - 6 over "barrel" { - 7 color3f[] primvars:displayColor = [(.6, .2, .2)] - 8 } - 9 } -10 } -11} -12 -13def "Factory" (references = @./factory.usda@) {} +*`scenario.usda` — identical to the version shown earlier in this guide.* ## Point Instancing Point instancing provides a vectorized representation of instances that share the same scene description but may differ in (potentially animated) attributes like position, orientation, or scale. Point Instancing is more efficient than scene graph instancing, as it does not require a prim for each instance and implicit prototypes do not need to be computed. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md index 1f229f9a..98a442b8 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md @@ -1,6 +1,3 @@ - - - # USD Instancing and Dedupe - Tradeoffs and Decision Tree > The actionable decisions in the agent flow are split between `usd-hierarchy-dedupe-candidates` (find candidate subtrees, read-only) and `instancing-readiness` (per-candidate safety gate). This reference holds the deeper trade-off framing, merge safety policy, and findings taxonomy that both skills cite. @@ -16,7 +13,7 @@ This reference is consulted by: - `usd-hierarchy-dedupe-candidates` when choosing between hierarchy dedupe vs unscoped mesh dedupe. - `instancing-readiness` when explaining merge safety to the user before authoring `instanceable=true`. - `apply-restructure` when planning Phase 2f restructure orchestration. -- `so-interpret-validators` when recommending merge or dedupe ops based on validator findings. +- `usd-optimize-interpret-validators` when recommending merge or dedupe ops based on validator findings. ## Prerequisites @@ -26,7 +23,7 @@ This reference is consulted by: ## Limitations -- This is decision guidance only; it does not run Scene Optimizer operations or rewrite the stage. +- This is decision guidance only; it does not run Usd Optimize operations or rewrite the stage. - Mesh-level dedupe does not collapse copied hierarchies or create shared asset boundaries by itself. - Point instancing and mesh merge reduce editability, so they need explicit fit with the user's workflow. @@ -63,11 +60,75 @@ Duplicated hierarchies: Duplicate mesh data: -- Scene Optimizer dedupe can help at the mesh-data level. +- Usd Optimize dedupe can help at the mesh-data level. - It does not collapse entire repeated hierarchies by itself. - Avoid whole-stage mesh dedupe on very large mesh counts unless the user explicitly accepts a long run. Prefer explicit prototypes, authored sub-assets, or scoped `meshPrimPaths`. - If a stage has ~50K+ meshes and no instancing, treat unscoped `deduplicateGeometry` as high-risk for customer friction. +## The boundary / disposition matrix (identity × reuse) + +Once boundaries are recovered **identity-first** (authored `kind` → meaningful +name → semantic recognizability; the hash only *confirms* reuse — see +`usd-structure-assessment/README.md` §2.5 and `workflow.md` Phase 2g), each +candidate unit's disposition follows from two questions: *does it have identity?* +and *does it repeat, and how?* + +| Identity (kind / name / semantics) | Reuse | Disposition | +|---|---|---| +| Strong — named component / subcomponent | repeats ≥2, single variant | **Externalize once, reference** (`inherits` + `instanceable`) — the default; preserves name, selectability, override, serviceability | +| Strong | repeats, with a few real variants | **One prototype per genuine variant**; recurse into the differing branches only | +| Strong | unique, but contains shared children | **Keep as an addressable container; reference its shared children** (nested library) | +| Strong | unique, no shared interior | **Keep local; clean in place** — no sharing | +| Weak — anonymous, identity not wanted | repeats in very high counts | **Point instancer** — compact, but *only because* identity isn't wanted here | +| Weak — identity-free, adjacent | n/a | **Merge** — draw-call win; only when per-part identity is genuinely irrelevant | +| Weak — below the inclusion floor | any | **Leave inline** for a later merge pass | + +The two "weak identity" rows are the **only** places identity may be destroyed, +and both are deliberate, intent-gated choices — never the default, and never +applied to anything identity signals marked as a real part. + +### What each disposition costs (OpenUSD content-reuse guidance) + +The choice between reference, point instancer, and merge is a choice about what you +keep and what you spend. Citing the OpenUSD content-reuse guidance: + +- **Reference (scenegraph instance).** Keeps **name, selectability, override, and + serviceability** — the part stays a part you can point at, override per-instance, + and swap. Costs roughly *(one prototype per variant) + (one reference per + occurrence)* in composition arcs. This is the default for anything with identity. +- **Point instancer.** Compact and cheap to compose for very high counts, but pays + in **"flexibility, addressability and legibility"** — instances are array + elements, not named prims, so you lose per-part selection and override. Reserve it + for anonymous high-count repeats (fasteners, vegetation, bolts) where identity is + genuinely unwanted. Never for an addressable subcomponent. This is the + `reduction_route = point_instance` landing; it is authored via the + point-instance route + (`apply-restructure/references/restructure-mode.md` § Point-Instance Route) + and is intent-gated. +- **Merge.** Buys **draw calls** by fusing meshes, but **destroys per-part + identity** and crosses boundaries. Only for identity-free static fragments. + +Two constraints govern how these are applied: + +- **Share at the coarsest unit that captures the reuse — the named subcomponent, + never the individual mesh.** Mesh-level sharing explodes anonymous arcs and throws + away identity; the same reuse at the subcomponent level needs orders of magnitude + fewer arcs and leaves every part addressable. (Reuse recovery may then justify + descending to finer *named* subcomponents — never to meshes.) +- **Instancing and merging fight at the instance boundary.** Once you instance a + tiny part you cannot merge it into its parent without un-instancing first, so + instancing finely *bakes in* a granularity a later draw-call pass must tear down. + **Instance coarsely; do any mesh merging *inside* the shared prototype** (merge + once, benefit on every instance); keep the pre-instanced source for a possible + merge-first variant. + +Sharing (the matrix) is orthogonal to **data reduction**: any unit you keep or +share can additionally have its geometry reduced within its fidelity band without +touching identity — drop unused primvars, index primvars, decimate, or **refit a +mesh that is really a primitive to that primitive** (box / cylinder / cone). On +prismatic CAD/BIM geometry, primitive-fitting and unused-primvar removal are +frequently the dominant *disk* levers even after sharing is done. + ## Merge safety Do not recommend mesh merge when: @@ -85,18 +146,30 @@ Consider merge when: - Materials and spatial clustering make the merge coherent. - Before/after validation and visual review are part of the plan. +**Group the fan by `(scope × material)`.** You can only fuse meshes that share a +material, or fuse into one mesh carrying a per-material `UsdGeomSubset`. So within +the merge boundary (the nearest named/`kind` ancestor, preserved) gather the +same-material fan and fuse it to one `Mesh` per material; when a few materials must +coexist in a single prim, fuse into one `Mesh` + a `UsdGeomSubset` per material so +bindings survive — and stop when the per-subset overhead approaches the per-mesh +overhead it replaced. The grouping/execution mechanic and the archetype-gated +merge depth are specified in +`usd-structure-assessment/references/apply-restructure/references/mesh-merge-rewrite-spec.md`, +surfaced by `usd-structure-assessment/references/usd-mesh-fragmentation-candidates/`. + ## Findings taxonomy -When emitting findings (e.g. from `usd-hierarchy-dedupe-candidates` or `so-interpret-validators`), use these tags so downstream references can route consistently: +When emitting findings (e.g. from `usd-hierarchy-dedupe-candidates` or `usd-optimize-interpret-validators`), use these tags so downstream references can route consistently: - `copied-hierarchy-candidate` - `reference-instancing-candidate` - `point-instancer-candidate` - `mesh-dedupe-candidate` +- `mesh-fragmentation-candidate` — a converter face-explosion fan to merge by `(scope × material)` - `merge-risk-instanced-content` - `merge-risk-geometry-streaming` -## Handoff to Scene Optimizer +## Handoff to Usd Optimize Only hand off dedupe or merge operations after: diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/layer-health.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/layer-health.md index 2855378b..fc0c05fa 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/layer-health.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/layer-health.md @@ -1,6 +1,3 @@ - - - # USD Layer Health > Layer-health checks are performed as a section of `usd-structure-assessment` Phase 1.3; this reference holds the deeper checklist, file-format guidance, asset-path hygiene, and flattening policy. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/optimization-tradeoffs.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/optimization-tradeoffs.md index c466282a..8d3cc955 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/optimization-tradeoffs.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/optimization-tradeoffs.md @@ -1,6 +1,3 @@ - - - # Asset Structure Performance Optimizations and Tradeoffs > **Canonical URL:** https://docs.omniverse.nvidia.com/vfi/latest/guide/asset-structure-optimizations-and-tradeoffs.html @@ -114,9 +111,9 @@ Monolithic baseline 3.7 GB ↓ -469158 ↓ +~470k ↓ -3664 +~3.7k Disaggregated Structure @@ -128,9 +125,9 @@ Disaggregated Structure 3.5 GB -192479 +~190k -11488 +~11k Component + subcomponent library packaging @@ -142,7 +139,7 @@ Component + subcomponent library packaging 3.5 GB ↑ -192455 ↑ +~190k ↑ 8 ↑ diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/restructure-decision/README.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/restructure-decision/README.md index 9aeabfca..0fa0f5cc 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/restructure-decision/README.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/restructure-decision/README.md @@ -1,19 +1,12 @@ # Restructure Decision - - - ## When to Use Use to decide whether a monolithic USD stage should be restructured (asset-boundary materialization + hierarchy dedupe) before optimization, or optimized as-is. Asks the user; invokes apply-restructure when the user confirms. ## Instructions -1. Confirm the target asset, artifact, or user intent and check the prerequisites listed below. -2. Read only the referenced files needed for the current phase, failure mode, or output contract. -3. Follow the workflow, rules, and safety gates in this reference before invoking downstream references or shell commands. -4. Return the result using the Output Format section and name any blocked prerequisite or unresolved user decision. - +See `references/_shared/standard-instructions.md`. ## Pre-flight Checklist @@ -22,11 +15,12 @@ Before presenting the restructure gate, re-read and confirm: - [ ] SA report contract — `phase_recommendation`, `hierarchy_dedupe`, `asset_boundary_suggestions` fields. - [ ] `setup-preflight.json` runtime header — know what runtime is available. -- [ ] Present all three options (restructure / optimize-as-is / exit) — do not - pre-select on the user's behalf. +- [ ] Present the restructure choices plus optimize-as-is — do not pre-select on + the user's behalf. The gate chooses *how* to optimize, never *whether*; there + is no diagnose-and-exit option. ## Output Format -Return a concise status or report that names the input, selected runtime or evidence source, actions planned or performed, artifacts written, blockers, and the next validation or user-decision step. When a schema or template is referenced below, conform to that contract. +See `references/_shared/standard-output-format.md`. ## Purpose @@ -38,16 +32,48 @@ skill is the user-confirm gate that decides whether to restructure the stage before optimization. This is a small decision-tier skill. It does not perform the rewrite - that's -the execution-tier `apply-restructure`, which uses `pxr`/`Sdf` USD authoring to -materialize boundaries and apply the hierarchy-dedupe rewrite described in -`skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/hierarchy-dedupe-rewrite-tool-spec.md`. +the execution-tier `apply-restructure`, which drives the per-region native +`deduplicateHierarchies` op (and `pxr`/`Sdf` authoring for what the op does not +cover) to materialize boundaries and apply the hierarchy dedupe described in +`skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/restructure-mode.md` +§ Dedupe Plan. + +**Bounded recursive descent.** This gate fires once per descent level: +after the first restructure, boundary inference re-runs on each extracted asset +(assembly → component → subcomponent) to a bounded depth, so the gate may recur +per node. The descent contract, the `level`/`importance`/`articulated`/ +`archetype` target-tree tags, and the stopping rule are defined in `workflow.md` +Phase 2g. Always prefer shared prototypes with `instanceable=true` references +over N unshared per-node payloads; descend to `subcomponent` only for +"important" (articulated / physics / variant-bearing) sub-hierarchies. + +**Descent convergence gate (confirm per level) — this reference is the per-level confirm point.** + +> **A low prototype count — or parts that "look like merge candidates" at a coarse level — means descend, not merge.** Within-prototype merge comes only after the descent is done. + +The full rule and the manifest fields to record live in `workflow.md` Phase 2g +(the single source); this is where you run the per-level confirmation. In short: +sharing happens in passes, biggest repeated pieces first, one level deeper each +pass. After authoring a level, re-run the reuse scan one level down and +**present the new worth-sharing groups to the user with their cost (more layers, +parts less directly selectable), then ask whether to descend further or stop.** Always ask before +crossing a named-part boundary or doing anything that destroys identity +(point-instancing / merging); a plain lossless-sharing tail can be auto-finished +if the user opts in. The descent is **done** when the user stops it, or when the +re-scan finds nothing new worth sharing. Do **NOT** start Phase 4 geometry ops +(decimation, within-prototype merge) until then, and record +`descent_converged: true` + `final_rescan_new_groups_above_floor: 0` in the +manifest — running geometry ops on an unfinished structure fuses or coarsens +geometry that more sharing would have removed. Phase 7 `resume-descent` is the +only exception (reuse that became visible after a transform, or a deliberately +deferred level), and it re-confirms convergence before re-entering geometry ops. ## Prerequisites - A completed `usd-structure-assessment` report including: - `phase_recommendation` (`structuring | optimization | already_optimized`). - `hierarchy_dedupe.recommended` and `hierarchy_dedupe.top_candidates` (when present). - - The §2.7 asset-boundary identification output (when the stage is monolithic). + - The §2.5 asset-boundary identification output (when the stage is monolithic). - Optional: `usd-hierarchy-dedupe-candidates` read-only candidate report when the stage is monolithic. - Optional: Phase 2c `usd-validation-runner` findings corpus (informs the decision when validators flagged structural-only issues that restructure would help with). @@ -63,7 +89,7 @@ The agent assembles a decision packet from prior phases: | Input | From | Used to decide | |---|---|---| | SA classification | `usd-structure-assessment` Phase 2a | Monolithic vs composed; restructure recommended? | -| Asset-boundary candidates | `usd-structure-assessment` §2.7 + `usd-hierarchy-dedupe-candidates` | Where the cut points are if restructure is chosen | +| Asset-boundary candidates | `usd-structure-assessment` §2.5 + `usd-hierarchy-dedupe-candidates` | Where the cut points are if restructure is chosen | | Validator findings | Phase 2c `usd-validation-runner` selected probes | Whether structural-only fixes would be wasted on a stage about to be restructured | | Instancing assessment | Phase 2d (read from SA `instancing` field) | Estimated leverage from restructure | | User constraints | session context | Time budget, mutation policy, output policy | @@ -74,37 +100,42 @@ Compute the recommended branch from the inputs, then **always present the choice | SA classification | hierarchy_dedupe.recommended | Recommended | Branches offered | |---|---|---|---| -| `monolithic-needs-restructure` | true | ask (see below) | deduplicate-internally / extract-as-assets / optimize-as-is / exit | -| `monolithic-needs-restructure` | false | decompose-for-selective-loading | decompose-for-selective-loading / optimize-as-is / exit | -| `monolithic-fine-as-is` | — | optimize-as-is | optimize-as-is / exit | -| `monolithic-fine-as-is` + `payload_count=0` + clear boundaries | — | ask | decompose-for-selective-loading / optimize-as-is / exit | -| `composed` (already structured) | — | continue (no Phase 2f) | continue (Phase 3) / exit | -| `phase_recommendation = already_optimized` | — | jump to Phase 6 | jump-to-verify / continue / exit | +| `monolithic-needs-restructure` | true | ask (see below) | deduplicate-internally / extract-as-assets / optimize-as-is | +| `monolithic-needs-restructure` | false | decompose-for-selective-loading | decompose-for-selective-loading / optimize-as-is | +| `monolithic-fine-as-is` | — | optimize-as-is | optimize-as-is (continue) | +| `monolithic-fine-as-is` + `payload_count=0` + clear boundaries | — | ask | decompose-for-selective-loading / optimize-as-is | +| `composed` (already structured) | — | continue (no Phase 2f) | continue (Phase 3) | +| `phase_recommendation = already_optimized` | — | continue (Phase 3-5 find no work) | continue → `no_op` report | #### When hierarchy_dedupe.recommended=true -Present exactly two restructure strategies (plus optimize-as-is and exit): +Present exactly two restructure strategies (plus optimize-as-is): -1. **Deduplicate hierarchies internally** — Scene Optimizer's - `deduplicateHierarchies` creates internal references to shared prototypes - within the same stage file. The referencing prims are marked - `instanceable=true`. The stage remains monolithic (single file, no payloads). - Fastest path; appropriate when selective loading is not needed. +1. **Deduplicate hierarchies internally** — prototypes stay inside the single + stage (internal namespace), no per-asset Phase 4 fan-out. Appropriate when + selective loading is not needed. Full authoring contract: see + [§ deduplicate-internally](#deduplicate-internally) below. -2. **Extract duplicate hierarchies as payloaded, instanced assets** — The - hierarchy-dedupe rewrite tool runs with `mode: external_prototype`, extracting - each shared prototype as an external asset file. Each instance site references - the prototype via a payload arc, making it independently loadable. This is - the full restructure: the monolith becomes an assembly root + prototype - assets. Appropriate when selective loading matters (large scenes, - collaborative workflows, streaming). +2. **Extract duplicate hierarchies as payloaded, instanced assets** — each shared + prototype becomes an external asset file referenced via a payload arc, so the + monolith becomes an assembly root + independently loadable prototype assets. + Appropriate when selective loading matters (large scenes, collaborative + workflows, streaming). Full authoring contract: see + [§ extract-as-assets](#extract-as-assets) below. -Both strategies produce instanced prototypes. The difference is whether -prototypes live inside the stage (internal references, SO handles it) or as -separate files (external payloaded assets, `apply-restructure` handles it). +Both strategies run the **same descent through `apply-restructure`** and produce +instanced prototypes; the only differences are materialization (internal namespace +vs external files) and whether Phase 4 fans out per-asset (external only). The +shared-descent rationale and how the native `deduplicateHierarchies` op fits (a +per-region authoring primitive the descent drives, with `apply-restructure` +staying the phase executor that emits the manifest) are detailed once in +[§ deduplicate-internally](#deduplicate-internally). The boundary plan records: -- `goal: deduplicate_internally` → SO's `deduplicateHierarchies` in Phase 4 +- `goal: deduplicate_internally` → hands off to `apply-restructure` with + `dedupe.mode: internal_reference` (value-hash nested library authored into an + internal namespace, `identity_disposition: internal_share`, restructure-role + manifest with `kept_inline_for_merge` tagging). - `goal: extract_as_assets` → hands off to `apply-restructure` with `dedupe.mode: external_prototype` Do NOT offer a "selective loading without instancing" option — extracting N @@ -121,7 +152,6 @@ building-wing boundaries, present a selective-loading choice: loadable sub-assets (payloads). Each boundary becomes its own file. - `optimize-as-is`: keep the monolithic delivery package and proceed to validation / SO optimization. -- `exit`: write the diagnosis/report and stop. If the user picks `decompose-for-selective-loading`, ask which candidate level from `asset_boundary_suggestions.candidate_levels` should be used unless the @@ -165,12 +195,39 @@ restructure-for-its-own-sake. ### deduplicate-internally -User accepts the dedupe candidates but wants the stage to stay monolithic. -Skip Phase 2f (`apply-restructure`). Record the choice and selected groups in -the optimization plan. Phase 4 includes `deduplicateHierarchies` in the SO op -chain (gated by `operationsAvailable`). - -Continue to Phase 3 with the original monolithic stage. +User accepts the dedupe candidates but wants the stage to stay a single file. +**Run the same structured descent as the external path — do NOT skip it.** Invoke +`apply-restructure` with `dedupe.mode: internal_reference`: it authors the +value-hash nested library into an internal namespace, rewrites each duplicate site +as an `instanceable=true` reference, and returns a **restructure-role manifest** +(`identity_disposition: internal_share`) — the same frontier, identity gate, and +`kept_inline_for_merge` tagging as the external path. Do NOT hand this branch to +`deduplicateHierarchies` on its own. The native op is the per-region authoring +primitive for the instanceable-reference collapse (invoked per frontier region +with `paths` + a per-region `maxDepth`), but on its own it emits no +restructure-role manifest, frontier/identity gating, or `kept_inline_for_merge` +tagging — the contract this phase requires. `apply-restructure` is the executor +that fulfills that contract: its per-level driver calls the native op per descent +region (`paths` scoped to that region, a small per-region `maxDepth`) and emits +the manifest. Invoking `deduplicateHierarchies` with `paths` + `maxDepth` +directly, with no manifest, is canonical only for standalone approved-chain dedup +runs outside the Phase 0-7 pipeline (`usd-optimize-run-operations`). The last-mile +`deduplicateGeometry` cleanup still runs inside the authored leaf prototypes +(after any within-prototype merge). + +The two paths differ ONLY in materialization (internal namespace + single file vs +extracted files) and parallelism (no per-asset Phase 4 fan-out for one file); the +descent decisions are identical. Skipping the frontier here is what leaves +high-count tiny repeats un-instanced and drops the merge frontier: with no +`kept_inline_for_merge` reservation, a later within-prototype merge runs *after* +the dedup/instancing passes already shared the geometry, has to un-instance it to +fuse, and inflates triangles/disk (the `mesh-merge-rewrite-spec.md` §9 +failure). The `kept_inline_for_merge` tagging reserves sub-MINP merge-candidate +leaves from the dedup/instancing passes so the merge runs **before** the +geometry-dedup tail. + +Hand off to `apply-restructure`, then continue to Phase 3 with the restructured +(single-file) stage. ### extract-as-assets @@ -199,19 +256,20 @@ Continue to Phase 3 with the decomposed stage. User accepts the existing structure. Skip Phase 2f. Continue to Phase 3 (instancing) and Phase 4 (mesh ops) targeting the original stage. -### exit - -User declines mutation. Skip to Phase 6d and write a diagnosis-only optimization report capturing the SA + validator findings. +This gate chooses *how* to optimize, never *whether* to. There is no +diagnose-and-exit option: every branch proceeds into the optimization pipeline. -### jump-to-verify +### already_optimized -Used when SA's `phase_recommendation = already_optimized`. The agent runs Phase 6a/6b on the original stage to confirm and writes the report. +Used when SA's `phase_recommendation = already_optimized`. Continue through the +pipeline; Phases 3-5 find no work, and Phase 6 produces a report with +`workflow_mode: no_op` and `verdict: neutral`. (No skip-to-verify shortcut.) ## How to ask The Phase 2e prompt commits the user to a structural decision that downstream phases cannot easily undo. The user must see exactly which Kit / Scene -Optimizer / Asset Validator versions authored the assessment and will execute +Optimizer / usd-validation-nvidia versions authored the assessment and will execute the restructure. **Prepend the full runtime context block** from `skills/omniverse-usd-performance-tuning/references/setup-usd-performance-tuning/references/runtime-context-header.md` (Format A) before any of the analysis or choice text below. Source: the `runtime_context` object in @@ -226,16 +284,18 @@ Present the recommended branch with the evidence behind it, then list the altern Kit application: USD Composer 110.1.0 path: D:\build\chk\usd_composer-fat\110.1.0+main.…\kit build: 110.1.0+main.10181.f4b28ef2.gl.windows-x86_64.release -Scene Optimizer: omni.scene.optimizer.core 110.0.4 -Asset Validator: omniverse-asset-validator 1.x.y via kit-extension +Usd Optimize: omni.scene.optimizer.core 110.0.4 +usd-validation-nvidia: usd-validation-nvidia 1.x.y via pip ─────────────────────────────────────────────────────────────────────────── The asset analysis shows: - 1 monolithic root layer, 0 references, 0 prototypes. - 4 repeated assembly patterns detected (suggesting 4 candidate prototypes saving an estimated 47% of prims). - - 8 of the 12 Tier 2 validator failures will be invalidated by restructuring - (geometry that's about to be replaced). + - Most duplicate geometry that would need per-mesh cleanup sits inside those + 4 repeated patterns — restructuring replaces it with shared prototypes, so + per-target mesh fixes on the copies would be wasted (Tier 2/3 validation + runs later, per prototype, in Phase 4). Recommended: extract as payloaded, instanced assets. This will: - Materialize 4 prototype USDs to /prototypes/ @@ -245,7 +305,6 @@ Recommended: extract as payloaded, instanced assets. This will: Alternatives: - optimize-as-is: skip restructure, run mesh ops on the monolith. Faster to start but fewer downstream wins. - - exit: write a diagnosis-only report and stop. Which would you like? ``` @@ -257,7 +316,7 @@ Record the user's choice in the optimization plan and emit it for downstream pha ```json { "phase": "2e", - "choice": "deduplicate-internally | extract-as-assets | decompose-for-selective-loading | optimize-as-is | exit | jump-to-verify", + "choice": "deduplicate-internally | extract-as-assets | decompose-for-selective-loading | optimize-as-is | already_optimized", "recommended": "deduplicate-internally", "reasoning": "monolithic with 4 repeated patterns; restructure recommended", "boundary_plan_ref": "", @@ -280,28 +339,32 @@ Record the user's choice in the optimization plan and emit it for downstream pha - Always present the selective-loading choice when SA reports `payload_count: 0` and clear asset-boundary candidates, even if hierarchy dedupe is not recommended and the asset is otherwise ready for mesh optimization. -- If the user picks `deduplicate-internally`, skip Phase 2f (`apply-restructure`). - The stage stays monolithic. Record the choice and continue to Phase 4 where - SO's `deduplicateHierarchies` runs (gated by `operationsAvailable`). +- If the user picks `deduplicate-internally`, run Phase 2f: `apply-restructure` + with `mode: internal_reference` — the same structured descent authored into an + internal namespace, producing the restructure-role manifest (`internal_share`, + `kept_inline_for_merge`). The native `deduplicateHierarchies` op is the + per-region authoring primitive the descent drives — the per-level driver in + `apply-restructure` calls it per region and emits the manifest; invoking it with + `paths` + `maxDepth` directly, with no manifest, is for standalone + approved-chain runs outside this pipeline, not this branch. Do NOT skip the + frontier. - If the user picks `extract-as-assets`, hand off to `apply-restructure` with the boundary plan and `goal: extract_as_assets`; do not perform writes from this reference. - If the user picks `decompose-for-selective-loading`, hand off to `apply-restructure` with the selected boundary level and `goal: selective_loading`; do not perform writes from this reference. -- If the user picks `exit`, immediately go to Phase 6d (`optimization-report`) - do not silently continue to Phase 3. ## Limitations - Decision skill only; does not write USD files. - Depends on SA's classification quality; if SA's `phase_recommendation` is missing, return to `usd-structure-assessment` rather than guessing. -- Asset-boundary candidates from SA §2.7 are suggestions, not enforcement; the user can override the cut points before invoking `apply-restructure`. +- Asset-boundary candidates from SA §2.5 are suggestions, not enforcement; the user can override the cut points before invoking `apply-restructure`. ## Troubleshooting - If SA reports no candidates and the user wants to restructure anyway, ask for explicit cut points (prim paths) before invoking `apply-restructure`. - If validator findings (Phase 2c) say the asset has structural issues that would block restructure (e.g. unresolved references), surface them to the user before asking for a choice. -- If the USD Python runtime is unavailable in the active environment, `apply-restructure` cannot author the rewrite. In that case `extract-as-assets` and `decompose-for-selective-loading` are effectively unavailable; tell the user clearly and offer `deduplicate-internally`, `optimize-as-is`, or `exit` only. ## References @@ -309,5 +372,5 @@ Read before deciding: - `skills/omniverse-usd-performance-tuning/references/workflow.md` - the canonical 7-phase flow context for where this gate sits. - `skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md` - merge safety and dedupe trade-offs that affect the restructure-vs-optimize-as-is call. -- `usd-structure-assessment/README.md` §2.7 (Asset boundary identification) - the source of boundary candidates. +- `usd-structure-assessment/README.md` §2.5 (Asset boundary identification) - the source of boundary candidates. - `usd-structure-assessment/references/usd-edit-target-planner/README.md` - downstream skill that places the restructure outputs into a coherent edit-target plan. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/README.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/README.md index c7c05093..068debe7 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/README.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/README.md @@ -1,22 +1,16 @@ # USD Edit Target Planner - - - ## When to Use Use when choosing where USD optimization edits are authored; do not use for processor execution. ## Instructions -1. Confirm the target asset, artifact, or user intent and check the prerequisites listed below. -2. Read only the referenced files needed for the current phase, failure mode, or output contract. -3. Follow the workflow, rules, and safety gates in this reference before invoking downstream references or shell commands. -4. Return the result using the Output Format section and name any blocked prerequisite or unresolved user decision. +See `references/_shared/standard-instructions.md`. ## Output Format -Return a concise status or report that names the input, selected runtime or evidence source, actions planned or performed, artifacts written, blockers, and the next validation or user-decision step. When a schema or template is referenced below, conform to that contract. +See `references/_shared/standard-output-format.md`. ## Purpose diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/output-saving.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/output-saving.md index 47c1e125..b3d84ebb 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/output-saving.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/output-saving.md @@ -1,6 +1,3 @@ - - - # Output Saving Policy Use this reference whenever an optimization, restructure, or direct USD edit @@ -34,9 +31,9 @@ stage.Export("out.usdc") # flatten the composed stage to a new requested deliverable is a flattened file; it collapses composition structure and is not a generic save operation. -## Scene Optimizer Outputs +## Usd Optimize Outputs -Scene Optimizer operations mutate the opened stage in memory. The safe default +Usd Optimize operations mutate the opened stage in memory. The safe default is: ```python diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/variants-payloads.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/variants-payloads.md index 2a54955a..4d9113d5 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/variants-payloads.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/variants-payloads.md @@ -1,6 +1,3 @@ - - - # USD Variants and Payloads - Strategy and Trade-offs > The day-to-day stop-gates (require loaded payloads, single-variant publish stop, mask coverage check, draw-mode preservation, output folder policy per variant) have been folded into `usd-edit-target-planner` as a "Variant and payload gates" subsection. This reference holds the deeper trade-off framing, payload/variant strategy bullets, output policy detail, and stop-conditions that the planner cites. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/README.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/README.md index 5035b0b3..963d0fb8 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/README.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/README.md @@ -1,22 +1,16 @@ # USD Hierarchy Dedupe Candidates - - - ## When to Use Use when finding repeated USD subtrees that may become shared prototypes or references before mesh-level dedupe. ## Instructions -1. Confirm the target asset, artifact, or user intent and check the prerequisites listed below. -2. Read only the referenced files needed for the current phase, failure mode, or output contract. -3. Follow the workflow, rules, and safety gates in this reference before invoking downstream references or shell commands. -4. Return the result using the Output Format section and name any blocked prerequisite or unresolved user decision. +See `references/_shared/standard-instructions.md`. ## Output Format -Return a concise status or report that names the input, selected runtime or evidence source, actions planned or performed, artifacts written, blockers, and the next validation or user-decision step. When a schema or template is referenced below, conform to that contract. +See `references/_shared/standard-output-format.md`. Use this after `usd-structure-assessment` and before unscoped `deduplicateGeometry` when a stage appears monolithic or assembly repetition is @@ -28,6 +22,14 @@ Produce a read-only candidate report for repeated subtrees that could be rewritten as shared prototype/reference assets. This is hierarchy-level analysis, not mesh-level deduplication, and it must not modify the stage. +**Share, don't scatter.** Candidates feed the bounded recursive descent +(`workflow.md` Phase 2g): the report runs again on each extracted asset to find +deeper (component/subcomponent) repetition to a bounded depth. The win is always +a SHARED prototype with `instanceable=true` references, never N unshared per-node +payloads. Flag structurally identical subtrees (hash-confirmed) so the rewrite +shares one prototype; a repack or unshared split is not the optimization win and +fails the Phase-6 gate. + ## Prerequisites - Run after `usd-structure-assessment` when possible. @@ -101,7 +103,8 @@ must distinguish candidates. For a precise behavior spec, read `references/instance-candidate-finder-spec.md` only when implementing or debugging the analyzer. For the follow-on rewrite behavior, read -`skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/hierarchy-dedupe-rewrite-tool-spec.md`. +`skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/restructure-mode.md` +§ Dedupe Plan. ## Output @@ -125,9 +128,14 @@ For top candidates: 2. Choose an edit target with `usd-edit-target-planner`. 3. Use `restructure-decision` and `apply-restructure` to rewrite repeated hierarchy as references/payloads to shared prototype assets. -4. Run `so-run-operations` on the new explicit prototypes or sub-assets. +4. Run `usd-optimize-run-operations` on the new explicit prototypes or sub-assets. 5. Run mesh-level `deduplicateGeometry` only inside remaining unique prototypes or scoped sub-assets. Do not claim savings as achieved until a rewrite is performed and after-profile metrics confirm it. + +Coverage note: candidate quality depends on full-tree hashing. Shallow +subtree-hash shortcuts miss depth-3+ duplicates (a shallow heuristic covers +only a small fraction of the full-tree pass's coverage on a large CAD stage) — see the finder spec's +"Coverage limit" section. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/references/instance-candidate-finder-spec.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/references/instance-candidate-finder-spec.md index c767ce74..a698bfaf 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/references/instance-candidate-finder-spec.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/references/instance-candidate-finder-spec.md @@ -1,9 +1,6 @@ - - - # Instance-Candidate Finder — Behavioral Specification -Status: draft (revision 3 - pairs the read-only finder with a rewrite-tool spec) +Status: draft (revision 4 - adds the kind-trust preflight, issue #172) Audience: a coding agent (or human) re-implementing the tool from scratch Style: behavior-only. Do not infer function names, class layout, or module structure from this document. Any implementation that satisfies every clause @@ -20,8 +17,10 @@ turned into a shared prototype, based on outgoing references from inside the subtree. The tool **does not modify the stage**. The actual de-duplication step -(rewriting the stage to use shared prototypes) is a separate tool described in -`skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/hierarchy-dedupe-rewrite-tool-spec.md`. +(rewriting the stage to use shared prototypes) is driven per descent region by the +native `deduplicateHierarchies` op, described in +`skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/apply-restructure/references/restructure-mode.md` +§ Dedupe Plan. Treat the finder output as the input packet for a USD authoring rewrite that creates prototype assets or internal prototype prims and then rewrites @@ -84,7 +83,7 @@ mandatory defaults are: | Knob | Default | Rationale | | --- | --- | --- | | `ROOT` | `"/"` | Whole stage; user almost always narrows it. | -| `HASH_LEVEL` | `3` | Values matter for real dedup; samples don't usually distinguish identical assets. | +| `HASH_LEVEL` | `2` | Structure (types + names + attr names/types, no values) finds repeated NAMED subtrees cheaply for the broad Phase-2b sweep. Escalate to `3` to fold in values and CONFIRM / split near-duplicates (the value digest is byte-based, so level 3 is an affordable confirmation pass, not a whole-stage cost); `4` splits on samples / relationship targets. | | `MIN_SUBTREE_PRIMS` | `3` | Single-prim "groups" are noise. | | `MIN_DUPLICATE_COUNT` | `2` | The minimum that "duplicate" can mean. | | `TOP_N` | `25` | Fits in one screen of console output. | @@ -201,6 +200,144 @@ substitution function must be: ## 6. Duplicate detection +### 6.0 Identity first — the hash confirms reuse, it does not pick the grain + +This finder is a **read-only reuse-confirmation** pass, not a boundary finder. +Run it on the **identity-marked candidate units** the agent has already +identified — `kind`-tagged `component`/`subcomponent` scopes, meaningfully named +scopes (`assetInfo` / display name / variant set), or the semantic real-world +unit — *not* on raw subtrees chosen by the hash. The hash then **confirms** which +of those meaningful units actually repeat and **partitions value-variants** +(§6.3); it must never be the thing that *chooses* the grain. Letting the hash +choose the grain is exactly the failure mode that over-shares at the mesh level +(on a large data-center assembly asset this produced orders of magnitude more +mesh arcs than the handful of named subcomponents that actually repeat). + +The one exception is a **structural fallback** for assets with no authored +identity at all: where `kind`, names, and semantics are silent, the repetition +pattern may *propose* the **coarsest repeating subtree** as a grain — recorded as +`grain_source = structural_fallback` — while still stopping at that coarsest unit +and **never descending the grain to leaves**. With identity present, +`grain_source = identity`. + +The deterministic disposition step (externalization cutoff, value-variant +partition, non-overlapping frontier, two-axis disposition, arc-count contrast) +is shipped as a co-located script — `select_frontier.py` (alongside this finder in +`scripts/`) — which consumes +this finder's grouped, identity-marked candidates and emits the frontier targets +that drop into the apply-restructure manifest. The finder hashes; the decision +core decides; the agent authors. + +That handoff is executable, not just conceptual. Running the finder with +`--emit-candidates` prints the `candidates[]` packet in exactly the schema +`select_frontier.py` reads, so the two tools pipe directly: + +``` +python3 instance_candidate_finder.py --emit-candidates \ + | python3 select_frontier.py - +``` + +One reported group becomes one candidate. Because the candidate hash already +folds in attribute values at `HASH_LEVEL >= 3`, genuine value-variants land in +SEPARATE groups (one prototype per variant), so each candidate carries +`structure_hash == value_hash`; lower the `HASH_LEVEL` to merge near-variants +into one structural family. `identity_signal` is set from the AUTHORED USD +`kind` on each group's root — absent any authored identity the candidate is +emitted as the explicit `structural_fallback` grain (the §6.0 exception), never +a hash-invented strong identity. The agent may refine `identity_signal` to +`naming` / `semantic` on the emitted packet before the pipe. + +There is no separate "reuse analyzer" beyond this finder: the identity-first +reuse analysis is just this finder run with `ROOT` set to each identity-marked +candidate boundary, re-run as the descent re-enters each level (and *resuming* +from the level an already-instanced / BIM-CAD input already sits at — see the +recursive descent and resume-from-existing rules in +`skills/omniverse-usd-performance-tuning/references/workflow.md` Phase 2). + +### 6.0.1 Kind-trust preflight — sample meshes-per-kind before trusting `kind` + +`kind` is trustworthy only when it reflects source lifecycle / ownership +boundaries; CAD exporters often don't encode that, so assetization ideally +begins upstream — this preflight is the downstream mitigation. On a monolithic +CAD import an exporter may tag ~every mesh `kind=component` (field case: 81% +of components held exactly one mesh), and trusting that label lands the +frontier on non-boundaries: suspiciously few prototypes and no merge signal, +because the real reuse unit was the parent prim. + +Before `kind` may set `identity_signal`, sample meshes-per-kind **stage-wide** +during the §4 traversal: for every walked prim with an authored kind in +{`component`, `subcomponent`, `group`}, record its subtree Mesh count. The +sample is the whole traversal universe, never the candidate groups (groups +hold only repeated subtrees — a biased sample). + +**Fine-grain-authoring exclusion.** A single-mesh `subcomponent` nested under +a multi-mesh kind-bearing ancestor is the *well-authored* fine-grain pattern +(individually addressable parts for BOM / service selection under a real +multi-mesh component), so it is EXCLUDED from the sample before the stats are +computed; the excluded count is reported for audit +(`excluded_fine_grain_subcomponents`). This cannot mask the junk-CAD +signature, which tags single-mesh `component`s with no multi-mesh kind +structure above them — model-hierarchy convention keeps the two patterns +disjoint (components do not nest inside components). + +`kind` is **untrusted** for the whole run when: + +- the fraction of sampled prims whose subtree holds <= 1 mesh is >= the named + threshold knob (`KIND_TRUST_MAX_SINGLE_MESH_FRACTION`, default **0.80**), OR +- the median meshes-per-kind is <= 1. + +When `kind` is untrusted it does not partition geometry, and the tool must +fall to the structural grain **exactly as if identity were absent** (the §6.0 +fallback): candidates are emitted with `grain_source = structural_fallback` +(never `identity_signal = kind`), tagged `kind_untrusted: true` plus the +sampled stats (single-mesh fraction, median, sample size) so the +sampled-and-rejected kind stays auditable, and the boundary is **re-derived +structurally**: + +- **Walk-up.** Each occurrence walks up to the nearest ancestor whose subtree + holds > 1 mesh (the multi-mesh parent). Re-derived boundaries that genuinely + repeat are re-grouped by candidate hash; hash-singletons are grouped by + normalized sibling name-base, reusing the one sibling-name suffix-stripping + normalization (usd-structure-assessment §2.4) — never a second normalizer. +- **No-collateral rule.** The walk terminates immediately at any node with + > 1 subtree mesh, so a component that is ITSELF multi-mesh re-derives to + itself: it keeps its boundary and only loses the `kind` label as the + identity signal, gaining `structural_fallback` at the SAME prim. +- **Internal-motion stop.** The walk must never cross (or land on) a prim + whose subtree needs independent per-instance motion — instancing makes + descendants read-only. Both signals are tallied during the §4 traversal (no + extra pass) and both use the same at-root vs strictly-below rule: motion + authored ON the landing target itself never blocks (it rides the instance + prim's own writable transform — the ideal cut), motion STRICTLY BELOW it + does. + - **Physics — `RigidBodyAPI` strictly below** (stop recorded as + `walkup_stopped_by: articulation`). Per the UsdPhysics schema, + `RigidBodyAPI` engulfs its subtree (everything below moves rigidly with + it), so a body strictly below a boundary is an independent mover — a + jointed link or a free simulated part — whose transform would freeze + inside the prototype. Keying on bodies makes joint-prim location + irrelevant: joint prims are not Xformables and bind their bodies via + `body0`/`body1` relationships wherever they are authored. An explicit + `ArticulationRootAPI` on the landing target also stops the walk. When + UsdPhysics is unavailable the physics leg is skipped gracefully and + noted in the diagnostics. + - **Animation — time-varying xformOps strictly below** (stop recorded as + `walkup_stopped_by: animation`). A prim whose authored xformOp + attributes are time-varying (samples or value clips — + `ValueMightBeTimeVarying`, the cheap conservative check) is an + independent mover in the animation sense. Landing above it would + collapse per-copy motion into the shared prototype — and the level-2/3 + hashes cannot see that samples DIFFER across copies (only `HASH_LEVEL 4` + folds samples in), so a group whose subtrees carry time-varying + attributes must be confirmed at level 4 before any rewrite. This leg is + pure Usd and needs no UsdPhysics. + 1-mesh links of a robot arm therefore never re-derive to the arm root, and + an animated slide inside a repeated conveyor keeps the conveyor from + becoming the shared boundary. + +A healthy stage — components bounding multi-mesh parts — is untouched: the +preflight never demotes trusted kind, and the whole pass stays read-only. + ### 6.1 Full hash Computed once per prim, post-order (children-first), and memoized so each prim's subtree is hashed exactly once. The full hash of `ROOT` is computed @@ -646,6 +783,16 @@ any framework. 20. **Out-of-range config rejection.** Setting `HASH_LEVEL = 5` or `MIN_DUPLICATE_COUNT = 1` causes the tool to print one error line and produce no other output. +21. **Kind-trust preflight (§6.0.1).** A stage where >= 80% of + `kind=component` prims contain <= 1 mesh emits candidates with + `grain_source = structural_fallback` re-derived at the multi-mesh parent + (or sibling name-base group), tagged `kind_untrusted` with the sampled + stats — NOT `identity_signal = kind` at the 1-mesh grain. A control stage + whose components bound multi-mesh parts keeps `identity_signal = kind` + unchanged; in a demoted stage a genuinely multi-mesh component re-derives + to itself (no collateral); and a 1-mesh link under a prim with + `UsdPhysics.ArticulationRootAPI` (or joint children) stays below that + prim, recording `walkup_stopped_by = articulation`. ## 14. Non-goals @@ -669,6 +816,17 @@ any framework. ## Changelog +- **rev 4** — Adds the §6.0.1 kind-trust preflight (issue #172): stage-wide + meshes-per-kind sampling; the untrust rule (single-mesh fraction >= 0.80 OR + median meshes-per-kind <= 1, named threshold knob); demotion to the + structural-fallback grain with structural boundary re-derivation (nearest + multi-mesh parent / sibling name-base group); the no-collateral rule + (multi-mesh components re-derive to themselves); the articulation stop + (never cross `UsdPhysics.ArticulationRootAPI` / joint-bearing prims); and + §13 acceptance test 21. +- **rev 3** — Pairs the read-only finder with the rewrite-tool spec and the + co-located `select_frontier.py` decision core (§6.0 identity-first wiring, + `--emit-candidates`). - **rev 2** — Incorporates feedback from a clean-room re-implementation. Fixes §8/§11 ordering contradiction; tightens §5 Level 4 to include sample values; tightens §7.2 INTERNAL classification to require @@ -683,3 +841,12 @@ any framework. attribute author-order invariance, `INCLUDE_ATTRIBUTE_CONNECTIONS` monotonicity, unreadable attribute, and out-of-range config rejection. - **rev 1** — Initial draft. + +## Coverage limit (field-measured) + +Shallow subtree hashing misses depth-3+ duplicates. On a large data-center CAD +stage (hundreds of MB, hundreds of thousands of prims), a shallow heuristic +surfaced only a small fraction of the dedupe-candidate coverage that the +full-tree (Merkle) pass in the shipped finder reached. Treat any non-full-tree +shortcut as a triage signal only; candidate-quality claims must come from the +full-tree pass. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/scripts/instance_candidate_finder.py b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/scripts/instance_candidate_finder.py new file mode 100644 index 00000000..446c0b81 --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/scripts/instance_candidate_finder.py @@ -0,0 +1,1123 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""Instance-candidate finder — read-only duplicate-subtree analyzer. + +Implements `instance-candidate-finder-spec.md` (rev 4). Scans a USD +sub-hierarchy, reports sub-hierarchies that recur and could be made +`instanceable`, and classifies how cleanly each group could become a shared +prototype. It NEVER modifies the stage. + +Pasteable into the Kit Script Editor: edit the KNOBS block and run. It also +runs standalone for testing — set the stage via the ``DTP_STAGE`` env var or +``argv[1]`` (a USD file path). The core functions (`analyze`, `render_report`, +`validate_knobs`) take an explicit stage + knobs so they are unit-testable +without Kit. + +Wiring to the decision core: pass ``--emit-candidates`` to print the +``candidates[]`` packet (JSON) that the co-located ``select_frontier.py`` consumes, +so the finder pipes straight into the frontier disposition step:: + + python3 instance_candidate_finder.py --emit-candidates \ + | python3 select_frontier.py - + +The finder confirms reuse (hash + group); ``to_frontier_candidates`` maps each +group to an identity-marked candidate (``kind`` -> identity_signal, else the +explicit ``structural_fallback`` grain); select_frontier decides dispositions. +""" +from __future__ import annotations + +import hashlib +import json +import os +import re +import sys + +# ============================== KNOBS ===================================== +# All values are literal assignments, trivially editable before paste-and-run. +ROOT = "/" +# Default 2 (structure: types + names + attribute names/types, NO values) for the +# broad Phase-2b sweep — it finds repeated NAMED subtrees cheaply without reading +# geometry. Escalate to 3 (folds in attribute VALUES) to CONFIRM a group and split +# near-duplicates; to 4 to split further on time samples / relationship targets. +# Value digesting is byte-based (see _digest_value_token), so level 3 is now +# affordable as a confirmation pass rather than a default whole-stage cost. +HASH_LEVEL = 2 +MIN_SUBTREE_PRIMS = 3 +MIN_DUPLICATE_COUNT = 2 +TOP_N = 25 +SHOW_PATHS_PER_GROUP = 8 +SKIP_EXISTING_INSTANCES = True +COLLAPSE_NESTED = True +CHECK_INSTANCEABILITY = True +MAX_FINDINGS_PER_GROUP = 6 +INCLUDE_ATTRIBUTE_CONNECTIONS = False +# Kind-trust preflight (issue #172). Stage-wide meshes-per-kind sample taken +# during the walk over ALL prims with an authored kind in KIND_TRUST_KINDS +# (never over candidate groups only — those are a biased sample of repeated +# subtrees). Kind is UNTRUSTED for the whole stage when the fraction of +# kind-tagged prims whose subtree holds <= 1 Mesh reaches this threshold, OR +# the median meshes-per-kind is <= 1. Untrusted kind is demoted: candidates +# fall to the structural-fallback grain and boundaries are re-derived at the +# nearest multi-mesh parent / sibling name-base group (monolithic CAD imports +# commonly tag ~every mesh kind=component, which makes kind a non-boundary). +KIND_TRUST_MAX_SINGLE_MESH_FRACTION = 0.80 +# ========================================================================== + +_DIGEST_REPR_BYTES = 256 +_DIGEST_ARRAY_LEN = 16 + +#: Kinds sampled by the kind-trust preflight: the "part-ish" kinds an exporter +#: over-applies. `assembly` legitimately aggregates and is not sampled. +KIND_TRUST_KINDS = ("component", "subcomponent", "group") + +#: One normalizer for all sibling name-base grouping in this tool — the §2.4 +#: sibling-name normalization from usd-structure-assessment (strip trailing +#: numeric suffixes / generated copy suffixes: Station_01, Station-2, +#: Station.003, Station001 -> Station). Do not add a second normalizer. +_NAME_BASE_SUFFIX_RE = re.compile(r"(?:[_\-.]?\d+)+$") + + +def _name_base(name: str) -> str: + base = _NAME_BASE_SUFFIX_RE.sub("", name) + return base or name + + +# numpy gives a C-speed raw-byte view of Vt/array values; without it we fall back +# to repr (correct, just slower). Imported once, guarded. +try: + import numpy as _np +except Exception: # pragma: no cover - numpy is normally present in a USD runtime + _np = None + + +def _sha(data: bytes) -> str: + return hashlib.sha256(data).hexdigest() + + +def _array_bytes(value): + """Content-stable raw bytes for a NUMERIC array value, or None when the value + is not one we can safely byte-digest. + + This avoids the O(n) Python ``repr()`` that made ``HASH_LEVEL >= 3`` an + O(all-geometry) pass on mesh-heavy stages: ``repr`` stringifies every element + in Python, while ``.tobytes()`` copies the buffer at C speed. Equality is + preserved exactly — equal arrays produce equal bytes, differing arrays differ — + so duplicate grouping is unchanged, only faster. String/token/object arrays + return None (their object-pointer bytes are NOT content, so they MUST keep the + repr path); such arrays are short, so repr stays cheap there. + """ + if _np is None: + return None + try: + arr = _np.asarray(value) + except Exception: + return None + if arr.dtype.kind not in ("f", "i", "u", "b", "c"): + return None + return arr.tobytes() + + +def _digest_value_token(value) -> str: + """§5.1 long-value digesting. Returns a deterministic token for a value. + + Large array values are digested by their raw bytes (C-speed) when numeric; + everything else keeps the ``repr`` digest. The repr path is the fallback, so + identical values still produce identical tokens — the byte path is a speed + optimization, not a semantic change. + """ + if value is None: + return "" + # Array-typed values of length >= 16 are digested by their bytes (numeric) or + # their repr (fallback). + try: + length = len(value) + is_sized = True + except TypeError: + is_sized = False + length = 0 + if is_sized and length >= _DIGEST_ARRAY_LEN: + b = _array_bytes(value) + if b is not None: + return "" % _sha(b) + return "" % _sha(repr(value).encode("utf-8", "replace")) + r = repr(value) + if len(r.encode("utf-8", "replace")) > _DIGEST_REPR_BYTES: + return "" % _sha(r.encode("utf-8", "replace")) + return r + + +def _attr_value_token(attr) -> str: + """Default value token for an attribute; if .Get() raises.""" + try: + return _digest_value_token(attr.Get()) + except Exception: + return "" + + +def _attr_sample_token(attr, t) -> str: + try: + return _digest_value_token(attr.Get(t)) + except Exception: + return "" + + +def _is_xformop(name: str) -> bool: + return name == "xformOpOrder" or name.startswith("xformOp:") + + +class _Walker: + """Encapsulates traversal + hashing for one (stage, knobs) analysis.""" + + def __init__(self, stage, hash_level, skip_existing_instances): + from pxr import Usd # local import: keep module importable without pxr + + self._Usd = Usd + self.stage = stage + self.level = hash_level + self.skip = skip_existing_instances + self.full = {} # path -> full hash + self.cand = {} # path -> candidate hash + self.size = {} # path -> subtree size + self.mesh = {} # path -> Mesh-typed prim count in subtree (own_meshes) + # Kind-trust preflight sample (issue #172): (path, kind, subtree mesh + # count) of EVERY fully-walked prim whose authored kind is in + # KIND_TRUST_KINDS. This is the STAGE-WIDE population, not the candidate + # groups (which only hold repeated subtrees and would bias the + # single-mesh fraction). kind_by_path supports the fine-grain-authoring + # exclusion (nearest kind-bearing ancestor lookup) in + # _filter_kind_trust_sample. + self.kind_samples = [] + self.kind_by_path = {} + # Internal-motion signals for the boundary walk-up, bubbled like mesh + # counts, each with the set of prims carrying the signal directly (so + # the walk-up can distinguish AT-the-boundary from STRICTLY-below). + # PHYSICS: subtree RigidBodyAPI tally. Per the UsdPhysics schema, + # RigidBodyAPI engulfs its subtree (everything below moves rigidly + # with it), so a body AT a candidate boundary is the ideal instancing + # cut, while a body STRICTLY BELOW the boundary is an independent + # mover whose transform would freeze inside the prototype — jointed or + # free. Keying on bodies makes joint-prim location irrelevant (joints + # bind bodies via body0/body1 relationships wherever they live). + # ANIMATION: subtree tally of prims with time-varying xformOp + # attributes (authored time samples / clips). Same at-root vs + # strictly-below rule: animation ON the boundary rides the instance + # prim's writable transform; animation strictly below would collapse + # into the shared prototype (and level-2/3 hashes cannot see that the + # samples differ across copies). Works without UsdPhysics. + self.bodies = {} + self.body_self = set() + self.anim = {} + self.anim_self = set() + self._physics = _usd_physics() + self._proxy_pred = Usd.TraverseInstanceProxies(Usd.PrimDefaultPredicate) + + def _authored_kind(self, prim) -> str: + try: + return self._Usd.ModelAPI(prim).GetKind() or "" + except Exception: + return "" + + # -- eligibility / children ------------------------------------------ + def _eligible(self, prim): + return ( + prim.IsActive() + and not prim.IsAbstract() + and prim.GetSpecifier() != self._Usd.SdfSpecifierClass + if hasattr(self._Usd, "SdfSpecifierClass") + else (prim.IsActive() and not prim.IsAbstract()) + ) + + def _children(self, prim): + from pxr import Usd, Sdf + + if self.skip: + kids = prim.GetChildren() # default predicate: active, defined, !abstract + else: + kids = prim.GetFilteredChildren(self._proxy_pred) + out = [] + for c in kids: + if not c.IsActive() or c.IsAbstract(): + continue + if c.GetSpecifier() == Sdf.SpecifierClass: + continue + out.append(c) + return out + + # -- per-prim self tokens -------------------------------------------- + def _self_tokens(self, prim, include_name, include_xformops): + toks = ["T:" + str(prim.GetTypeName())] + if include_name: + toks.append("N:" + prim.GetName()) + if self.level >= 2: + attrs = [a for a in prim.GetAttributes() if a.HasAuthoredValue()] + attrs.sort(key=lambda a: a.GetName()) # I8 author-order invariance + for a in attrs: + name = a.GetName() + if not include_xformops and _is_xformop(name): + continue + toks.append("A:%s:%s" % (name, a.GetTypeName())) + if self.level >= 3: + toks.append("V:%s:%s" % (name, _attr_value_token(a))) + if self.level >= 4: + try: + times = sorted(a.GetTimeSamples()) + except Exception: + times = [] + for t in times: + toks.append("S:%s:%r:%s" % (name, t, _attr_sample_token(a, t))) + if self.level >= 4: + rels = sorted(prim.GetAuthoredRelationships(), key=lambda r: r.GetName()) + for r in rels: + tgts = r.GetTargets() + if not tgts: + continue + toks.append("R:%s:%s" % (r.GetName(), ",".join(str(t) for t in tgts))) + return toks + + def _instance_tokens(self, prim): + # Opaque-leaf identity: prototype path + prim type. Used identically in + # full and candidate hashes (name + local opinions ignored). + proto = prim.GetPrototype() if hasattr(prim, "GetPrototype") else None + proto_id = str(proto.GetPath()) if proto else "?" + return ["INST:%s:%s" % (proto_id, prim.GetTypeName())] + + # -- recursion ------------------------------------------------------- + def visit(self, prim): + path = prim.GetPath().pathString + if self.skip and prim.IsInstance(): + toks = self._instance_tokens(prim) + h = _sha(("\x00".join(toks)).encode("utf-8", "replace")) + self.full[path] = h + self.cand[path] = h + self.size[path] = 1 + self.mesh[path] = 0 # opaque instance leaf: not an own authored mesh + self.bodies[path] = 0 # subtree unwalked: body count unknown + self.anim[path] = 0 # subtree unwalked: animation unknown + return + kids = self._children(prim) + for c in kids: + self.visit(c) + child_full = [self.full[c.GetPath().pathString] for c in kids] + size = 1 + sum(self.size[c.GetPath().pathString] for c in kids) + child_tok = ["C:" + h for h in child_full] + full_toks = self._self_tokens(prim, True, True) + child_tok + cand_toks = self._self_tokens(prim, False, False) + child_tok + self.full[path] = _sha(("\x00".join(full_toks)).encode("utf-8", "replace")) + self.cand[path] = _sha(("\x00".join(cand_toks)).encode("utf-8", "replace")) + self.size[path] = size + # Mesh-typed prim count in this subtree — additive bookkeeping for the + # frontier adapter's own_meshes; does not affect any hash. + self.mesh[path] = (1 if str(prim.GetTypeName()) == "Mesh" else 0) + sum( + self.mesh[c.GetPath().pathString] for c in kids + ) + # Subtree rigid-body tally (0 when UsdPhysics is unavailable, matching + # kind_trust.articulation_check='unavailable'). + own_body = 0 + if self._physics is not None: + try: + if prim.HasAPI(self._physics.RigidBodyAPI): + own_body = 1 + self.body_self.add(path) + except Exception: + own_body = 0 + self.bodies[path] = own_body + sum( + self.bodies[c.GetPath().pathString] for c in kids + ) + # Subtree transform-animation tally (pure Usd — no UsdPhysics needed): + # a prim counts when any authored xformOp attribute is time-varying + # (samples or value clips). ValueMightBeTimeVarying is the cheap, + # conservative check designed for exactly this question. + own_anim = 0 + try: + for a in prim.GetAttributes(): + if (_is_xformop(a.GetName()) and a.HasAuthoredValue() + and a.ValueMightBeTimeVarying()): + own_anim = 1 + self.anim_self.add(path) + break + except Exception: + own_anim = 0 + self.anim[path] = own_anim + sum( + self.anim[c.GetPath().pathString] for c in kids + ) + # Kind-trust sample: tally the subtree mesh count for every walked prim + # carrying an authored part-ish kind. Opaque instance leaves (early + # return above) are excluded — their subtree is not walked, so their + # mesh count is unknown, and they are already shared anyway. + k = self._authored_kind(prim) + if k in KIND_TRUST_KINDS: + self.kind_samples.append((path, k, self.mesh[path])) + self.kind_by_path[path] = k + return + + +def _classify_target(target_prim_path, root_path): + """INTERNAL if target prim is at/below root; else EXTERNAL. Returns (kind, value).""" + tp = target_prim_path + if tp == root_path or tp.startswith(root_path + "/") or root_path == "/": + if root_path == "/" : + rel = tp + else: + rel = tp[len(root_path):] or "." + # only INTERNAL when genuinely under root; '/' root makes everything internal-ish + if root_path == "/": + return ("INTERNAL", rel) + return ("INTERNAL", rel) + return ("EXTERNAL", tp) + + +def _collect_refs(stage, walker, root_prim, include_connections): + """Collect outgoing refs inside root subtree, keyed by relative property key. + + Returns dict: key -> list of (kind, value, is_material) tuples preserving + target order (kind/value computed per target, joined into a per-key seq). + Actually returns key -> (seq, is_material) where seq is the ordered list of + (kind, value) for that key's targets on THIS copy. + """ + from pxr import Sdf, UsdShade + + root_path = root_prim.GetPath().pathString + result = {} + + def rel_key(prim, prop_name): + ppath = prim.GetPath().pathString + if ppath == root_path: + rel = "" + else: + rel = ppath[len(root_path):] if root_path != "/" else ppath + return rel + "." + prop_name + + def visit(prim): + if walker.skip and prim.IsInstance() and prim.GetPath().pathString != root_path: + return + for r in prim.GetAuthoredRelationships(): + tgts = r.GetTargets() + if not tgts: + continue + seq = [] + for t in tgts: + kind, val = _classify_target(t.GetPrimPath().pathString, root_path) + seq.append((kind, val)) + result[rel_key(prim, r.GetName())] = (seq, r.GetName() == "material:binding") + if include_connections: + for a in prim.GetAttributes(): + if not a.HasAuthoredValue() and not a.HasAuthoredConnections(): + continue + conns = a.GetConnections() + if not conns: + continue + seq = [] + for t in conns: + kind, val = _classify_target(t.GetPrimPath().pathString, root_path) + # preserve property suffix verbatim for evidence + suffix = "." + t.name if hasattr(t, "name") and t.name else "" + seq.append((kind, val + suffix)) + result[rel_key(prim, a.GetName())] = (seq, False) + for c in walker._children(prim): + visit(c) + + visit(root_prim) + return result + + +def _instanceability(stage, walker, copies, include_connections, max_findings): + """Classify a group's instanceability. copies = list of prim paths.""" + per_copy = [] + for path in copies: + prim = stage.GetPrimAtPath(path) + per_copy.append(_collect_refs(stage, walker, prim, include_connections)) + all_keys = set() + for c in per_copy: + all_keys.update(c.keys()) + + key_class = {} # key -> (classification, evidence, is_material) + for key in all_keys: + present = [c.get(key) for c in per_copy] + authored_on_all = all(p is not None for p in present) + is_material = any(p[1] for p in present if p is not None) + if not authored_on_all: + n = sum(1 for p in present if p is not None) + key_class[key] = ("INCONSISTENT", + "%d of %d copies authored" % (n, len(per_copy)), is_material) + continue + seqs = [tuple(p[0]) for p in present] + kinds = set(k for seq in seqs for (k, _v) in seq) + identical = len(set(seqs)) == 1 + if kinds == {"INTERNAL"} and identical: + ev = ",".join(v for (_k, v) in seqs[0]) + key_class[key] = ("INTERNAL", ev, is_material) + elif kinds == {"EXTERNAL"} and identical: + ev = ",".join(v for (_k, v) in seqs[0]) + key_class[key] = ("CONSISTENT_EXTERNAL", ev, is_material) + else: + distinct = len(set(seqs)) + examples = [] + for seq in seqs[:2]: + examples.append(";".join("%s:%s" % (k, v) for (k, v) in seq)) + key_class[key] = ("INCONSISTENT", + "%d distinct target seqs; e.g. %s" % (distinct, " | ".join(examples)), + is_material) + + classes = [c for (c, _e, _m) in key_class.values()] + if all(c == "INTERNAL" for c in classes): # also true when no keys + verdict = "GREEN" + elif any(c == "INCONSISTENT" for c in classes): + verdict = "RED" + else: + verdict = "YELLOW" + + # Findings, prioritized: INCONSISTENT, material CONSISTENT_EXTERNAL, other + # CONSISTENT_EXTERNAL, INTERNAL. Ascending key within each bucket. + def bucket(item): + key, (cls, _ev, ismat) = item + if cls == "INCONSISTENT": + return 0 + if cls == "CONSISTENT_EXTERNAL" and ismat: + return 1 + if cls == "CONSISTENT_EXTERNAL": + return 2 + return 3 + + ordered = sorted(key_class.items(), key=lambda it: (bucket(it), it[0])) + findings = [] + for key, (cls, ev, ismat) in ordered: + label = cls + if cls == "CONSISTENT_EXTERNAL" and ismat: + label = "CONSISTENT_EXTERNAL (material — inline candidate)" + findings.append("%s : %s : %s" % (key, label, ev)) + trailer = None + if len(findings) > max_findings: + trailer = "... and %d more findings" % (len(findings) - max_findings) + findings = findings[:max_findings] + return verdict, findings, trailer + + +def _kind_trust_stats(kind_mesh_counts, max_single_mesh_fraction): + """Kind-trust preflight (issue #172): stage-wide meshes-per-kind stats. + + Input is the walker's stage-wide sample (subtree mesh count per authored + part-ish kind). Kind is UNTRUSTED when ``single_mesh_fraction >= + max_single_mesh_fraction`` OR ``median_meshes_per_kind <= 1`` — i.e. when + kind does not partition geometry into multi-mesh parts and the real reuse + unit is almost certainly a parent prim. An empty sample (no authored + part-ish kinds) leaves kind trivially trusted: there is nothing to demote. + """ + counts = sorted(kind_mesh_counts) + sampled = len(counts) + if not sampled: + return { + "sampled_kind_prims": 0, + "single_mesh_fraction": 0.0, + "median_meshes_per_kind": None, + "max_single_mesh_fraction": max_single_mesh_fraction, + "kind_trusted": True, + } + single = sum(1 for c in counts if c <= 1) + fraction = single / float(sampled) + mid = sampled // 2 + if sampled % 2: + median = float(counts[mid]) + else: + median = (counts[mid - 1] + counts[mid]) / 2.0 + trusted = not (fraction >= max_single_mesh_fraction or median <= 1) + return { + "sampled_kind_prims": sampled, + "single_mesh_fraction": round(fraction, 4), + "median_meshes_per_kind": median, + "max_single_mesh_fraction": max_single_mesh_fraction, + "kind_trusted": trusted, + } + + +def _filter_kind_trust_sample(kind_samples, kind_by_path, mesh_by_path): + """Drop intentional fine-grain authoring from the kind-trust sample. + + A single-mesh ``subcomponent`` nested under a multi-mesh kind-bearing + ancestor is the WELL-AUTHORED fine-grain pattern (individually addressable + parts for BOM / service selection under a real multi-mesh component), not + the junk-CAD signature — which tags single-mesh ``component``s with no + multi-mesh kind structure above them. Counting the former would falsely + demote kind stage-wide on well-authored assets. Model-hierarchy convention + keeps the two disjoint (components do not nest inside components), so this + exclusion cannot mask the junk pattern. + + Returns ``(counts, excluded)``: the filtered mesh-count list for + ``_kind_trust_stats`` and the number of excluded fine-grain subcomponents + (reported for audit). + """ + counts = [] + excluded = 0 + for path, kind, count in kind_samples: + if kind == "subcomponent" and count <= 1: + anc = path + nearest = None + while True: + anc = anc.rsplit("/", 1)[0] + if not anc or anc == "/": + break + if anc in kind_by_path: + nearest = anc + break + if nearest is not None and mesh_by_path.get(nearest, 0) > 1: + excluded += 1 + continue + counts.append(count) + return counts, excluded + + +def _usd_physics(): + """UsdPhysics, or None when unavailable (the articulation guard is then + skipped gracefully and noted in the kind_trust diagnostics).""" + try: + from pxr import UsdPhysics + return UsdPhysics + except Exception: + return None + + +def _articulation_boundary(prim, usd_physics, bodies_below=0): + """True when landing the boundary walk-up ON ``prim`` would freeze internal + physics motion — instancing makes descendants read-only, so nothing inside + the prototype may need to move independently per instance. + + PRIMARY signal — ``bodies_below``: RigidBodyAPI prims STRICTLY below + ``prim``. Per the UsdPhysics schema, RigidBodyAPI engulfs its subtree, so a + body strictly below the boundary is an independent mover (a jointed link OR + a free simulated part) whose transform would freeze inside the prototype. + A body AT the boundary itself is fine — that is the ideal instancing cut + (VFI factory-structuring: instance at the rigid-body level), because the + body's motion is expressed on the instance prim's own writable transform. + Keying on bodies also makes joint-prim LOCATION irrelevant: joints bind + their bodies via body0/body1 relationships wherever the joint prim lives + (joint prims are not Xformables; there is no placement convention). + + EXPLICIT signal — ``ArticulationRootAPI`` on the prim: the author declared + a jointed mechanism here. + + Transform ANIMATION (time samples / clips) is the non-physics analog and + is checked separately in the walk-up — it needs no UsdPhysics.""" + if usd_physics is None or prim is None or not prim.IsValid(): + return False + if bodies_below > 0: + return True + try: + return bool(prim.HasAPI(usd_physics.ArticulationRootAPI)) + except Exception: + return False + + +def _rederive_boundary_path(stage, walker, path, root_path, usd_physics): + """Walk UP from a demoted kind-labeled candidate root to the nearest + multi-mesh ancestor. Returns ``(boundary_path, stopped_by)`` with + ``stopped_by`` in ``{None, "animation", "articulation", "root"}``. + + NO-COLLATERAL RULE: the walk terminates immediately at any node whose + subtree holds > 1 mesh — so a component that is ITSELF multi-mesh + re-derives to itself (it keeps its boundary and only loses the 'kind' + label as the identity signal, gaining structural_fallback at the SAME + prim). ARTICULATION STOP: the walk never crosses (or lands on) a prim + carrying an articulation/edit boundary — it stops BELOW it, so 1-mesh + links of a robot arm are never re-derived to the arm root. + """ + current = path + stopped_by = None + while walker.mesh.get(current, 0) <= 1: + parent = current.rsplit("/", 1)[0] or "/" + if parent == current or parent == root_path or parent not in walker.mesh: + stopped_by = "root" + break + # Animation strictly below the landing target: an animated prim inside + # the prototype would collapse per-copy motion (and the level-2/3 + # hashes cannot see that samples differ across copies). Animation ON + # the target itself is fine — it rides the instance prim's writable + # transform. Pure Usd: works with or without UsdPhysics. + anim_below = walker.anim.get(parent, 0) - ( + 1 if parent in walker.anim_self else 0) + if anim_below > 0: + stopped_by = "animation" + break + bodies_below = walker.bodies.get(parent, 0) - ( + 1 if parent in walker.body_self else 0) + if _articulation_boundary(stage.GetPrimAtPath(parent), usd_physics, + bodies_below): + stopped_by = "articulation" + break + current = parent + return current, stopped_by + + +def _rederive_group(stage, walker, group, root_path, usd_physics): + """Structural boundary re-derivation for one demoted kind-labeled group. + + Each occurrence walks up to its re-derived boundary + (`_rederive_boundary_path`). Distinct boundaries are then re-grouped: + first by candidate hash (the existing reuse confirmation — boundaries that + genuinely repeat), then hash-singletons by sibling name-base using the one + §2.4 normalizer (`_name_base`). Returns ``(rederived_groups, stopped_by)`` + where each entry carries the re-derived paths and the walker's stats at + that boundary. + """ + boundaries = set() + stopped_by = None + for p in group["paths"]: + b, stop = _rederive_boundary_path(stage, walker, p, root_path, usd_physics) + boundaries.add(b) + # Propagate internal-motion stop reasons ("articulation"/"animation"); + # "root" is the ordinary end-of-walk and is not a finding. + if stop in ("articulation", "animation"): + stopped_by = stop + by_hash = {} + for b in sorted(boundaries): + by_hash.setdefault(walker.cand.get(b), []).append(b) + parts = [] + singles = [] + for _h, paths in by_hash.items(): + if len(paths) >= 2: + parts.append((sorted(paths), "structure_hash")) + else: + singles.append(paths[0]) + by_base = {} + for b in singles: + parent, _, name = b.rpartition("/") + by_base.setdefault((parent or "/", _name_base(name)), []).append(b) + for _key, paths in by_base.items(): + parts.append((sorted(paths), "name_base" if len(paths) >= 2 else "self")) + out = [] + for paths, basis in parts: + rep = paths[0] + out.append({ + "paths": paths, + "copies": len(paths), + "hash": walker.cand.get(rep), + "subtree_prims": walker.size.get(rep, 0), + "subtree_meshes": walker.mesh.get(rep, 0), + "group_by": basis, + }) + out.sort(key=lambda d: d["paths"][0]) + return out, stopped_by + + +def analyze(stage, *, root=ROOT, hash_level=HASH_LEVEL, + min_subtree_prims=MIN_SUBTREE_PRIMS, + min_duplicate_count=MIN_DUPLICATE_COUNT, top_n=TOP_N, + show_paths_per_group=SHOW_PATHS_PER_GROUP, + skip_existing_instances=SKIP_EXISTING_INSTANCES, + collapse_nested=COLLAPSE_NESTED, + check_instanceability=CHECK_INSTANCEABILITY, + max_findings_per_group=MAX_FINDINGS_PER_GROUP, + include_attribute_connections=INCLUDE_ATTRIBUTE_CONNECTIONS, + kind_trust_max_single_mesh_fraction=KIND_TRUST_MAX_SINGLE_MESH_FRACTION): + """Read-only analysis. Returns a structured report dict (see render_report).""" + from pxr import Usd + + root_prim = stage.GetPrimAtPath(root) + if not root_prim or not root_prim.IsValid(): + return {"error": "ROOT not found: %s" % root} + + walker = _Walker(stage, hash_level, skip_existing_instances) + walker.visit(root_prim) + prims_hashed = len(walker.full) + + root_path = root_prim.GetPath().pathString + # group eligible candidate roots by candidate hash + groups = {} + for path, ch in walker.cand.items(): + if path == root_path: + continue + prim = stage.GetPrimAtPath(path) + if skip_existing_instances and prim.IsInstance(): + continue + if walker.size[path] < min_subtree_prims: + continue + groups.setdefault(ch, []).append(path) + + reported = [] + for ch, paths in groups.items(): + if len(paths) < min_duplicate_count: + continue + size = walker.size[paths[0]] + savings = size * (len(paths) - 1) + reported.append({"hash": ch, "paths": sorted(paths), "subtree_prims": size, + "copies": len(paths), "savings": savings}) + + reported.sort(key=lambda g: (-g["savings"], -g["subtree_prims"], g["hash"])) + + if collapse_nested: + kept = [] + kept_paths = set() + for g in reported: + if all(any(p == k or p.startswith(k + "/") for k in kept_paths) for p in g["paths"]): + continue + kept.append(g) + kept_paths.update(g["paths"]) + reported = kept + + if check_instanceability: + for g in reported: + v, f, tr = _instanceability(stage, walker, g["paths"], + include_attribute_connections, max_findings_per_group) + g["verdict"] = v + g["findings"] = f + g["findings_trailer"] = tr + + # Per-group facts the frontier adapter (to_frontier_candidates) needs. These + # are additive: render_report ignores them and the §13 acceptance tests do + # not key off them. ``subtree_meshes`` feeds own_meshes; ``kind`` is the + # AUTHORED USD kind on the representative root, which sets the candidate's + # identity_signal so select_frontier.py stays identity-first (the hash only + # confirms reuse; it never invents strong identity). + for g in reported: + rep = g["paths"][0] + g["subtree_meshes"] = walker.mesh.get(rep, 0) + kind = "" + prim = stage.GetPrimAtPath(rep) + if prim and prim.IsValid(): + try: + kind = Usd.ModelAPI(prim).GetKind() or "" + except Exception: + kind = "" + g["kind"] = kind + + # Kind-trust preflight (issue #172): decide once, stage-wide, whether the + # authored kind is a reliable boundary. When it is not, annotate every + # kind-labeled group as demoted and re-derive its boundary structurally + # (nearest multi-mesh parent / sibling name-base group). Read-only: the + # re-derivation only reads the walker's memoized stats and the stage. + usd_physics = _usd_physics() + trust_counts, excluded_fine_grain = _filter_kind_trust_sample( + walker.kind_samples, walker.kind_by_path, walker.mesh) + kind_trust = _kind_trust_stats(trust_counts, + kind_trust_max_single_mesh_fraction) + kind_trust["excluded_fine_grain_subcomponents"] = excluded_fine_grain + kind_trust["articulation_check"] = ( + "enabled" if usd_physics is not None else "unavailable") + if not kind_trust["kind_trusted"]: + for g in reported: + if not g["kind"]: + continue + g["kind_untrusted"] = True + rederived, stopped_by = _rederive_group( + stage, walker, g, root_path, usd_physics) + g["rederived"] = rederived + if stopped_by: + g["walkup_stopped_by"] = stopped_by + + total_savings = _eliminated_union_size(reported, walker) + clean_savings = blocked_savings = None + if check_instanceability: + clean_savings = _eliminated_union_size( + [g for g in reported if g["verdict"] != "RED"], walker) + blocked_savings = total_savings - clean_savings + + return { + "root": root_path, "hash_level": hash_level, "prims_hashed": prims_hashed, + "min_subtree_prims": min_subtree_prims, "min_duplicate_count": min_duplicate_count, + "groups": reported, "total_groups": len(reported), + "total_savings": total_savings, "clean_savings": clean_savings, + "blocked_savings": blocked_savings, "check_instanceability": check_instanceability, + "top_n": top_n, "show_paths_per_group": show_paths_per_group, + "kind_trust": kind_trust, + } + + +def _eliminated_union_size(groups, walker): + """Unique prims removed if every group collapses to one representative. + + Per-group ``savings`` counts each group in isolation; when a smaller + repeated subtree lives inside a larger repeated subtree, both groups count + the same prims, and a plain sum can exceed the stage's own prim count + (a naive sum can report more "savings" than the stage actually has prims). Union the eliminated copy + subtrees (every path but each group's representative), drop roots nested + under an already-counted root, then sum subtree sizes. + """ + roots = sorted({p for g in groups for p in g["paths"][1:]}) + total = 0 + last = None + for p in roots: + if last is not None and (p == last or p.startswith(last + "/")): + continue + total += walker.size.get(p, 0) + last = p + return total + + +def validate_knobs(root, hash_level, min_subtree_prims, min_duplicate_count, top_n, + show_paths_per_group, max_findings_per_group): + if not isinstance(hash_level, int) or not (1 <= hash_level <= 4): + return "HASH_LEVEL out of range (must be int 1..4): %r" % (hash_level,) + if not isinstance(min_subtree_prims, int) or min_subtree_prims < 1: + return "MIN_SUBTREE_PRIMS out of range (must be int >= 1): %r" % (min_subtree_prims,) + if not isinstance(min_duplicate_count, int) or min_duplicate_count < 2: + return "MIN_DUPLICATE_COUNT out of range (must be int >= 2): %r" % (min_duplicate_count,) + if not isinstance(top_n, int) or top_n < 1: + return "TOP_N out of range (must be int >= 1): %r" % (top_n,) + if not isinstance(show_paths_per_group, int) or show_paths_per_group < 1: + return "SHOW_PATHS_PER_GROUP out of range (must be int >= 1): %r" % (show_paths_per_group,) + if not isinstance(max_findings_per_group, int) or max_findings_per_group < 1: + return "MAX_FINDINGS_PER_GROUP out of range (must be int >= 1): %r" % (max_findings_per_group,) + if not isinstance(root, str) or not root: + return "ROOT must be a non-empty USD path string" + return None + + +def render_report(report) -> str: + if "error" in report: + return report["error"] + L = [] + L.append("Instance-candidate finder — root=%s HASH_LEVEL=%d" % (report["root"], report["hash_level"])) + L.append("Hashed %d prims; grouping by candidate hash." % report["prims_hashed"]) + L.append("Duplicate groups: %d (MIN_SUBTREE_PRIMS=%d, MIN_DUPLICATE_COUNT=%d, HASH_LEVEL=%d)" + % (report["total_groups"], report["min_subtree_prims"], + report["min_duplicate_count"], report["hash_level"])) + kt = report.get("kind_trust") + if kt and not kt.get("kind_trusted", True): + L.append("KIND-TRUST PREFLIGHT: authored kind does NOT partition geometry " + "(single-mesh fraction %.0f%%, median meshes/kind %s, sampled %d) — " + "kind-derived identity is demoted to structural_fallback and " + "boundaries are re-derived structurally." + % (100.0 * (kt.get("single_mesh_fraction") or 0.0), + kt.get("median_meshes_per_kind"), + kt.get("sampled_kind_prims") or 0)) + for i, g in enumerate(report["groups"][:report["top_n"]]): + L.append("") + L.append("[%d] hash=%s subtree_prims=%d copies=%d est_savings=%d" + % (i + 1, g["hash"][:16], g["subtree_prims"], g["copies"], g["savings"])) + if report["check_instanceability"]: + L.append(" verdict: %s" % g["verdict"]) + for fnd in g.get("findings", []): + L.append(" - %s" % fnd) + if g.get("findings_trailer"): + L.append(" %s" % g["findings_trailer"]) + shown = g["paths"][:report["show_paths_per_group"]] + for p in shown: + L.append(" %s" % p) + extra = len(g["paths"]) - len(shown) + if extra > 0: + L.append(" ... and %d more" % extra) + L.append("") + L.append("Total potential prim savings (unique prims; nested-group overlap excluded): %d" + % report["total_savings"]) + if report["check_instanceability"]: + L.append("Clean savings (GREEN+YELLOW, unique prims): %d" % report["clean_savings"]) + L.append("Blocked savings (RED-only remainder): %d (re-run at HASH_LEVEL=4 to split RED groups)" + % report["blocked_savings"]) + L.append("") + L.append("Caveats:") + L.append(" - Advisory only; this tool does not modify the stage.") + L.append(" - Outgoing references outside a candidate subtree may prevent clean instancing.") + L.append(" - Material bindings outside a subtree are common; matching local material") + L.append(" networks should usually be inlined during the rewrite.") + L.append(" - Default HASH_LEVEL=2 (structure) finds the families; raise to 3 to CONFIRM a") + L.append(" group and split value-variants, lower to merge near-duplicates into one family.") + if report["check_instanceability"]: + L.append(" - GREEN: cleanly instanceable. YELLOW: instanceable after reviewing/inlining") + L.append(" external deps. RED: not one prototype as-formed; split (HASH_LEVEL=4) or skip.") + return "\n".join(L) + + +def to_frontier_candidates(report) -> dict: + """Map ``analyze()`` groups onto the co-located ``select_frontier.py`` input. + + This is the executable wiring between the finder (which **confirms reuse** + by hashing) and the decision core (which **decides dispositions**). It is a + pure function — no ``pxr``, no stage — so it stays unit-testable without USD; + everything it needs (``subtree_meshes``, authored ``kind``, occurrence paths) + was attached by ``analyze()`` while it had the stage. + + One finder group becomes one candidate. At the default ``HASH_LEVEL == 2`` the + hash is STRUCTURAL only (no values), so a group may pool genuine value-variants + under one structural family — the cheap broad-sweep view. Escalate to + ``HASH_LEVEL >= 3`` to CONFIRM: the candidate hash then includes attribute + values, so value-variants split into SEPARATE groups (one prototype per + variant) — no within-group sub-partition needed, and ``structure_hash == + value_hash`` per candidate. (``structure_hash`` and ``value_hash`` are reported + equal here because one hash is emitted per run; the level chosen decides what + that hash folds in.) Re-run lower to collapse near-variants, higher to split + them (§5 / §8.2 footer guidance). + + Identity stays first: ``identity_signal`` comes from the AUTHORED USD + ``kind`` on the group's root. With no authored identity the candidate is + emitted as the explicit ``structural_fallback`` grain (the one fallback the + spec §6.0 allows) — the hash never manufactures a strong identity. The agent + may refine ``identity_signal`` (e.g. to ``naming`` / ``semantic``) on the + emitted candidates before piping them to select_frontier. + + KIND-TRUST PREFLIGHT (issue #172): when ``analyze()`` measured stage-wide + that authored kind does not partition geometry (``report["kind_trust"] + ["kind_trusted"] is False`` — e.g. a monolithic CAD import where ~every + kind=component subtree holds one mesh), a kind-labeled group is NOT emitted + with ``identity_signal='kind'``. It is demoted to the no-identity ladder + (``identity_signal='none'``, ``grain_source='structural_fallback'``) and + its boundary is the structurally re-derived one attached by ``analyze()`` + (nearest multi-mesh parent / sibling name-base group), tagged + ``kind_untrusted: True`` with the sampled stats so the rejection is + auditable. Reports without a ``kind_trust`` block (synthetic inputs) keep + the trusted behavior unchanged. + """ + if "error" in report: + return {"error": report["error"]} + kind_trust = report.get("kind_trust") or {} + kind_demoted = bool(kind_trust) and not kind_trust.get("kind_trusted", True) + kind_trust_stats = { + k: kind_trust.get(k) + for k in ("single_mesh_fraction", "median_meshes_per_kind", + "sampled_kind_prims") + } if kind_trust else {} + candidates = [] + seen_rederived = set() + for g in report.get("groups", []): + paths = list(g.get("paths", [])) + if not paths: + continue + kind = g.get("kind") or "" + if kind and kind_demoted: + # Demoted kind: emit at the re-derived boundary, never as 'kind' + # identity. Two source groups under the same parents re-derive to + # the same boundary set; emit that boundary once. + for part in (g.get("rederived") or + [{"paths": paths, "copies": g["copies"], "hash": g["hash"], + "subtree_prims": g["subtree_prims"], + "subtree_meshes": g.get("subtree_meshes", 0), + "group_by": "self"}]): + key = tuple(part["paths"]) + if key in seen_rederived: + continue + seen_rederived.add(key) + boundary_moved = list(part["paths"]) != paths + cand = _base_candidate( + part["paths"], part["hash"], part["copies"], + part["subtree_prims"], part["subtree_meshes"], + # Verdict was computed for the ORIGINAL grain; it does not + # transfer to a moved boundary. + None if boundary_moved else g.get("verdict"), + ) + cand["identity_signal"] = "none" + cand["grain_source"] = "structural_fallback" + cand["structural_fallback"] = True + cand["kind_untrusted"] = True + cand["kind_untrusted_source_kind"] = kind + cand["kind_trust"] = dict(kind_trust_stats) + cand["rederive_group_by"] = part.get("group_by") + if boundary_moved: + cand["rederived_from"] = paths + if g.get("walkup_stopped_by"): + cand["walkup_stopped_by"] = g["walkup_stopped_by"] + candidates.append(cand) + continue + if kind: + signal, grain = "kind", "identity" + else: + signal, grain = "none", "structural_fallback" + cand = _base_candidate(paths, g["hash"], g["copies"], g["subtree_prims"], + g.get("subtree_meshes", 0), g.get("verdict")) + cand["identity_signal"] = signal + cand["grain_source"] = grain + if signal == "none": + cand["structural_fallback"] = True + candidates.append(cand) + out = {"candidates": candidates} + if kind_trust: + out["kind_trust"] = kind_trust + return out + + +def _base_candidate(paths, group_hash, copies, own_prims, own_meshes, verdict): + """Shared candidate skeleton for ``to_frontier_candidates`` (identity + fields are filled in by the caller).""" + return { + "id": paths[0], + "path": paths[0], + "target_class": "prototype", + "structure_hash": group_hash, + "value_hash": group_hash, + "copy_count": copies, + "occurrences": list(paths), + "parents": sorted({(p.rsplit("/", 1)[0] or "/") for p in paths}), + "own_prims": own_prims, + "own_meshes": own_meshes, + "mesh_count": own_meshes, + "reduction_route": "none", + # Advisory only: select_frontier decides disposition by identity + + # cutoff; a RED group still needs external-ref review before the + # rewrite tool authors a prototype. Carried for the audit/report. + "instanceability_verdict": verdict, + } + + +def _resolve_stage(): + from pxr import Usd + # Prefer the Kit USD context when running inside Omniverse. + try: + import omni.usd # type: ignore + st = omni.usd.get_context().get_stage() + if st: + return st + except Exception: + pass + # First non-flag argv arg is the stage path (so --emit-candidates etc. do + # not get mistaken for a USD file path; the value after --output is that + # flag's argument, not a stage path). + positional = [] + skip_next = False + for a in sys.argv[1:]: + if skip_next: + skip_next = False + continue + if a == "--output": + skip_next = True + continue + if a.startswith("--"): + continue + positional.append(a) + path = os.environ.get("DTP_STAGE") or (positional[0] if positional else None) + if path: + return Usd.Stage.Open(path) + return None + + +def main(): + err = validate_knobs(ROOT, HASH_LEVEL, MIN_SUBTREE_PRIMS, MIN_DUPLICATE_COUNT, + TOP_N, SHOW_PATHS_PER_GROUP, MAX_FINDINGS_PER_GROUP) + if err: + print(err) + return + stage = _resolve_stage() + if stage is None: + print("No stage: open a stage in Kit, or set DTP_STAGE / pass a USD path as argv[1].") + return + report = analyze( + stage, root=ROOT, hash_level=HASH_LEVEL, min_subtree_prims=MIN_SUBTREE_PRIMS, + min_duplicate_count=MIN_DUPLICATE_COUNT, top_n=TOP_N, + show_paths_per_group=SHOW_PATHS_PER_GROUP, + skip_existing_instances=SKIP_EXISTING_INSTANCES, collapse_nested=COLLAPSE_NESTED, + check_instanceability=CHECK_INSTANCEABILITY, + max_findings_per_group=MAX_FINDINGS_PER_GROUP, + include_attribute_connections=INCLUDE_ATTRIBUTE_CONNECTIONS, + kind_trust_max_single_mesh_fraction=KIND_TRUST_MAX_SINGLE_MESH_FRACTION) + # --output : write the full structured report (analysis groups plus + # the select_frontier candidate packet) to disk, per the runtime-artifact + # token-budget policy — keep raw artifacts on disk, read summaries. + argv = sys.argv[1:] + if "--output" in argv: + i = argv.index("--output") + if i + 1 >= len(argv): + print("--output requires a file path") + return + out_path = argv[i + 1] + payload = dict(report) + payload["candidates"] = to_frontier_candidates(report).get("candidates", []) + with open(out_path, "w", encoding="utf-8") as f: + json.dump(payload, f, indent=2, sort_keys=True) + print("Report JSON written: %s" % out_path) + # --emit-candidates: print the select_frontier.py candidate packet (JSON) so + # the finder pipes straight into the decision core: + # python3 instance_candidate_finder.py --emit-candidates \ + # | python3 select_frontier.py - + if "--emit-candidates" in argv: + print(json.dumps(to_frontier_candidates(report), indent=2, sort_keys=True)) + return + print(render_report(report)) + + +if __name__ == "__main__": + main() diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/scripts/select_frontier.py b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/scripts/select_frontier.py new file mode 100644 index 00000000..690ccaea --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/scripts/select_frontier.py @@ -0,0 +1,296 @@ +#!/usr/bin/env python3 +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""Reuse / descent frontier decision core (shipped as deterministic code). + +What this IS +------------ +The small, deterministic, identity-first **decision core** of the reuse +analyzer. Given the agent's identity-marked candidate units (the named / +``kind`` / semantic scopes where authoring stops, each with a value-hash and its +occurrence sites), it: + +* partitions each structural group by full value-hash — **one prototype per + genuine value-variant** (e.g. 17 identical copies + 1 outlier -> ``[17, 1]``); +* applies the band-resolved **externalization cutoff** (copy_count + own size) + to pick a two-axis disposition (externalize_shared / internal_share / + keep_local) and, for sub-MINP anonymous repeats, suggests an intent-gated + reduction_route (point_instance) or marks ``kept_inline_for_merge``; +* records **non-double-counted** savings and the **arc-count contrast** (arcs if + shared at the frontier vs at mesh level — the load-bearing too-deep signal); +* measures remaining reuse (distinct vs total units) and pivots to the disk tier + when reuse is low; +* emits ``phase4_targets[]`` + a ``frontier`` block that drop straight into the + apply-restructure manifest and pass ``validate_manifest_structure``. + +What this is NOT +---------------- +It does **not** walk USD, hash subtrees, or author anything. The pxr-based +hashing engine is the agent-pasted finder (instance-candidate-finder-spec.md); +the nested-library authoring stays agent-driven per the rewrite-tool spec. This +core just turns identity-marked candidates into a checked frontier so the agent +cannot silently over-share at the mesh level. **Identity defines the grain; +the hash only confirms reuse** — a candidate with no identity signal is refused +a shared disposition unless it is the explicit structural-fallback grain. + +Usage: + python3 select_frontier.py # or - for stdin +Exit 0 when a valid frontier is produced, 1 on an identity violation. +""" +from __future__ import annotations + +import argparse +import json +import sys +from pathlib import Path +from typing import Any + +#: Evidence-seeded band defaults (overridable per target extent via input "band"). +#: Evidence-seeded from a reference data-center assembly run; see units-and-tolerances.md for per-band resolution. +DEFAULT_BAND = { + "minp": 20, # min prims with occurrence >= 2 for nested-library membership + "externalize_copy_count": 4, # >= 4 copies across distinct parents + "externalize_own_prims": 32, # OR meaningful own size + "externalize_own_meshes": 16, +} + +STRONG_IDENTITY = frozenset({"kind", "naming", "semantic"}) + + +def _occurrences(c: dict) -> int: + occ = c.get("occurrences") + if isinstance(occ, list) and occ: + return len(occ) + cc = c.get("copy_count") + return int(cc) if isinstance(cc, int) and not isinstance(cc, bool) else 1 + + +def _share_scope(c: dict) -> str: + parents = c.get("parents") + if isinstance(parents, list): + distinct = len({p for p in parents if p}) + if distinct >= 2: + return "cross_component" + if distinct == 1: + return "internal_parent" + return c.get("share_scope", "none") + + +def _meets_externalize_size(c: dict, band: dict) -> bool: + own_prims = c.get("own_prims") or 0 + own_meshes = c.get("own_meshes") or 0 + return own_prims >= band["externalize_own_prims"] or own_meshes >= band["externalize_own_meshes"] + + +def select_frontier(payload: dict) -> dict: + """Pure function: candidates JSON -> {frontier, phase4_targets, diagnostics}. + + Raises ValueError on an identity violation (anonymous shared grain, or an + identity-destroying route forced onto a strong-identity unit without an + explicit intent confirmation) — the same rules the manifest contract checks, + enforced at the source so a bad frontier is never authored in the first place. + """ + band = dict(DEFAULT_BAND) + band.update(payload.get("band") or {}) + candidates = payload.get("candidates") or [] + if not isinstance(candidates, list): + raise ValueError("'candidates' must be a list") + + # Partition each structural group by value-hash: one prototype per genuine + # value-variant. Variant count drives the [N, 1] outlier handling downstream. + variant_counts: dict[str, set] = {} + for c in candidates: + sh = c.get("structure_hash") + if sh is not None: + variant_counts.setdefault(sh, set()).add(c.get("value_hash")) + + targets: list[dict] = [] + diagnostics: list[str] = [] + total_units = 0 + distinct_prototypes = 0 + + for c in candidates: + cid = c.get("id") or c.get("path") or "" + # Kind-trust defensive guard (issue #172). The real rejection lives + # upstream in the finder's preflight; this only catches a candidate + # that still ARRIVES claiming strong 'kind' identity while flagged + # kind_untrusted (kind measured stage-wide as not partitioning + # geometry, ~1 mesh per component). Coerce it onto the existing + # anonymous-grain / structural-fallback path — never let unreliable + # kind count as strong identity. + if c.get("identity_signal") == "kind" and c.get("kind_untrusted"): + c = dict(c) + c["identity_signal"] = "none" + c["grain_source"] = "structural_fallback" + diagnostics.append( + f"{cid}: identity_signal 'kind' arrived with kind_untrusted=true — " + "coerced to identity_signal 'none' / grain_source 'structural_fallback' " + "(stage-wide meshes-per-kind preflight rejected kind as a boundary)" + ) + copies = _occurrences(c) + total_units += copies + distinct_prototypes += 1 # one prototype authored per value-variant candidate + signal = c.get("identity_signal", "none") + grain_source = c.get("grain_source") or ("structural_fallback" if signal == "none" and c.get("structural_fallback") else "identity") + own_prims = c.get("own_prims") or 0 + own_meshes = c.get("own_meshes") or 0 + scope = _share_scope(c) + below_minp = own_prims < band["minp"] + + # --- Axis A: identity disposition ----------------------------------- + passes_cutoff = ( + copies >= band["externalize_copy_count"] + and _meets_externalize_size(c, band) + and scope == "cross_component" + ) + if passes_cutoff: + disposition = "externalize_shared" + elif copies >= 2 and scope == "internal_parent" and not below_minp: + disposition = "internal_share" + else: + disposition = "keep_local" + + # --- Axis B: reduction route ---------------------------------------- + route = c.get("reduction_route", "none") + kept_inline = False + below_cutoff = not passes_cutoff and disposition != "internal_share" + if route == "none" and below_minp and copies >= band["externalize_copy_count"] and signal in ("none", "structural_fallback"): + # Sub-MINP anonymous high-count repeats: either point-instance them + # (intent-gated) or keep them inline for a later within-prototype + # merge. Default to kept_inline_for_merge to preserve merge-ability. + if c.get("intent_confirmed"): + route = "point_instance" + else: + kept_inline = True + disposition = "keep_local" + below_cutoff = True + + # --- Identity guards (refuse a bad grain at the source) ------------- + is_shared = disposition in ("externalize_shared", "internal_share") + is_destroying = route in ("point_instance", "merge") + if is_shared and signal == "none" and grain_source != "structural_fallback": + raise ValueError( + f"{cid}: cannot assign shared disposition {disposition!r} to an " + "anonymous unit (identity_signal 'none') — identity defines the " + "grain; the hash only confirms reuse. Mark the structural-fallback " + "grain explicitly (grain_source=structural_fallback) or land on a " + "named/kind/semantic unit." + ) + if is_destroying and signal in STRONG_IDENTITY and not c.get("intent_confirmed"): + raise ValueError( + f"{cid}: identity-destroying reduction_route {route!r} on a " + f"strong-identity unit (identity_signal {signal!r}) requires an " + "explicit intent confirmation (intent_confirmed=true); a named / " + "kind / semantic part must stay addressable by default." + ) + + non_dc_savings = own_prims * max(copies - 1, 0) + target = { + "path": c.get("path") or c.get("target_path") or f"/_proto/{cid}", + "target_class": c.get("target_class", "prototype"), + "mesh_count": int(c.get("mesh_count", own_meshes)), + "identity_disposition": disposition, + "identity_signal": signal if (is_shared or is_destroying) else c.get("identity_signal", signal), + "grain_source": grain_source, + "reduction_route": route, + "copy_count": copies, + "own_prims": own_prims, + "own_meshes": own_meshes, + "non_double_counted_savings": non_dc_savings, + "below_externalization_cutoff": below_cutoff, + "kept_inline_for_merge": kept_inline, + "share_scope": scope, + # Arc-count contrast: arcs if shared at the frontier (one per copy) + # vs arcs at the mesh level (every mesh in every copy). The ratio is + # the primary too-deep guard and must appear in the report. + "arc_estimate": { + "frontier": copies, + "mesh_level": own_meshes * copies, + }, + "decision_reason": { + "identity_signal": signal, + "stop_condition": "below_floor" if below_minp else "min_meaningful_unit", + }, + } + if c.get("value_variant_id") is not None: + target["value_variant_id"] = c["value_variant_id"] + if c.get("structure_hash") in variant_counts: + target["value_variant_count"] = len(variant_counts[c["structure_hash"]]) + if c.get("nested_parent_proto"): + target["nested_parent_proto"] = c["nested_parent_proto"] + if c.get("package_group"): + target["package_group"] = c["package_group"] + if c.get("descent_level"): + target["descent_level"] = c["descent_level"] + if c.get("kind_untrusted"): + # Audit passthrough (#172): the sampled-and-rejected kind stays + # visible on the manifest target. + target["kind_untrusted"] = True + targets.append(target) + + shared = [t for t in targets if t["identity_disposition"] in ("externalize_shared", "internal_share")] + measured_ratio = (distinct_prototypes / total_units) if total_units else 1.0 + # Low measured reuse (mostly-unique parametric assets): pivot to the disk + # tier rather than forcing more sharing. Heuristic: < 5% of units collapse. + units_saved = total_units - distinct_prototypes + low_reuse = bool(shared) and units_saved <= max(1, total_units * 0.05) + + # Audit rollups: count the frontier targets by the three decision axes so the + # report can show how much rests on strong identity, what dispositions were + # chosen, and where authoring stopped — without re-walking phase4_targets[]. + by_identity_signal: dict[str, int] = {} + by_disposition: dict[str, int] = {} + by_stop_condition: dict[str, int] = {} + for t in targets: + by_identity_signal[t["identity_signal"]] = by_identity_signal.get(t["identity_signal"], 0) + 1 + by_disposition[t["identity_disposition"]] = by_disposition.get(t["identity_disposition"], 0) + 1 + sc = t["decision_reason"]["stop_condition"] + by_stop_condition[sc] = by_stop_condition.get(sc, 0) + 1 + + frontier = { + "reuse_measured": True, + "distinct_prototypes": distinct_prototypes, + "total_units": total_units, + "low_reuse_disk_tier_pivot": low_reuse, + "by_identity_signal": by_identity_signal, + "by_disposition": by_disposition, + "by_stop_condition": by_stop_condition, + "frontier_estimate_basis": payload.get("frontier_estimate_basis", "exact"), + } + if payload.get("descent_entry_level"): + frontier["descent_entry_level"] = payload["descent_entry_level"] + if payload.get("kind_trust"): + # Audit passthrough (#172): stage-wide meshes-per-kind preflight stats, + # as emitted by the finder's --emit-candidates packet. + frontier["kind_trust"] = payload["kind_trust"] + if low_reuse: + diagnostics.append( + "measured reuse is low (mostly-unique units) — pivot to the disk tier " + "(unused-primvar removal, fit_primitive, decimation) instead of forcing sharing" + ) + + out: dict[str, Any] = {"frontier": frontier, "phase4_targets": targets} + if diagnostics: + out["diagnostics"] = diagnostics + return out + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("input", type=str, help="candidates JSON path, or - for stdin") + args = parser.parse_args(argv) + + raw = sys.stdin.read() if args.input == "-" else Path(args.input).read_text(encoding="utf-8") + payload = json.loads(raw) + try: + result = select_frontier(payload) + except ValueError as exc: + print(f"frontier identity violation: {exc}", file=sys.stderr) + return 1 + json.dump(result, sys.stdout, indent=2, sort_keys=True) + sys.stdout.write("\n") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-mesh-fragmentation-candidates/README.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-mesh-fragmentation-candidates/README.md new file mode 100644 index 00000000..032d317f --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-mesh-fragmentation-candidates/README.md @@ -0,0 +1,140 @@ +# USD Mesh-Fragmentation Candidates + +## When to Use + +Use when a named unit holds a flat fan of anonymous, same-material `Mesh` prims — +the CAD/BIM/EDA converter "face-explosion" pattern — and that fan could be +re-stitched into one mesh per material. This is the cheap entry point for a +within-prototype mesh merge. + +## Instructions + +See `references/_shared/standard-instructions.md`. + +## Output Format + +See `references/_shared/standard-output-format.md`. + +Use this after `usd-structure-assessment` and before a within-prototype `merge` +when a stage shows converter face-explosion. + +## Purpose + +Produce a read-only suggestion report for parents whose children look like a +converter face-explosion — a flat fan of anonymous, same-material `Mesh` prims +under a named or `kind`-tagged unit — and suggest merging that fan up to the +named boundary, grouped by material. This is hierarchy-level analysis that +surfaces and routes only; it must not modify the stage. + +**Surface, don't gate.** Merge is identity-destroying and intent/archetype-gated, +so this reference only surfaces candidates and routes them; the user (or the +archetype default) confirms. It does no vertex-coincidence computation and +applies no numeric merge threshold — the merge op welds anyway. + +## Prerequisites + +- Run after `usd-structure-assessment` when possible. +- The Phase-2c `perf_small_mesh` validator finding (the tininess signal and entry + point); pass its members as the small-mesh paths. +- Know the scan root, or use the composed stage root when the user gives no + narrower scope. + +## Limitations + +- Suggestions are advisory; no savings are achieved until a merge rewrite and + after-profile confirm them. +- `SUGGEST_MIN_FAN` and `*_HINT` knobs are surfacing/ranking heuristics, not merge + gates — they decide what to show and in what order, never whether a shown fan + may merge. +- This is not a geometric engine: no weld-ratio computation, no merge threshold. +- It surfaces and routes; it makes no identity-dissolution decision. + +## Troubleshooting + +- If a fan is likely but nothing is surfaced, confirm `perf_small_mesh` ran and + that children are genuinely anonymous (`Mesh_N`, numeric/uuid tokens) — reference + designators (`U302`) and semantic names are NOT anonymous. +- If suggestions are noisy, raise `SUGGEST_MIN_FAN` or tighten the + mesh:material-ratio hint. +- If a surfaced fan overlaps an instance candidate, do not drop it — annotate it + (`composes_with_instance_candidate: true`); the two compose (see Handoff). + +## Examples + +- "This control cabinet's boards exploded into thousands of `Mesh_N` leaves — can + they be merged per material?" +- "Find converter face-explosion fans before planning a within-prototype merge." + +## When To Run + +Run when the qualitative pattern holds — *meaningless children under a meaningful +unit*: + +- a flat fan (mesh children dominate the direct children, low nesting); +- anonymously named children (`Mesh_N`, numeric/uuid tokens); +- under a parent that carries identity (`kind` ∈ {assembly, group, component, + subcomponent}, or a semantic name); and +- a high mesh:material ratio (many meshes, few distinct materials — + re-stitchable into one mesh per material). + +Skip when children carry their own identity (reference designators, semantic +names), when the fan spans many distinct materials, or when no `perf_small_mesh` +signal is present. + +## Method + +1. Open the composed stage read-only. +2. For each candidate parent, read cheap structural signals only: direct child + count and type uniformity, anonymous child naming, the parent's `kind`/name, + and the distinct bound materials across the fan (a binding-relationship target + read — no geometry, no points). +3. Surface a parent when the qualitative pattern above holds; rank by fan size and + mesh:material ratio. +4. For each surfaced parent, name the merge boundary (the named/`kind` ancestor to + preserve), the `identity_signal` that keeps it addressable, the + `identity_disposition` (`weak` — the anonymous fan), and the per-material + grouping (`merge_groups = distinct_materials`, `geomsubset_fallback` when > 1). +5. Route small geometry: `perf_small_mesh` members inside a surfaced fan are real + faces → merge (re-stitch); the rest are negligible → `removeSmallGeometry` + (delete). Do not route a fan to delete and do not merge a scattered tiny mesh. + +## Division of Labor with Hierarchy-Dedupe Candidates + +The two target different things and must never claim the same prims twice: + +- `usd-hierarchy-dedupe-candidates` finds repeated subtrees to make `instanceable` + (reference reuse, identity preserved); +- this reference finds fragmented same-material fans to merge (re-pack, identity + destroyed). + +**Precedence:** a fan that is also a repeated subtree is instanced at the +component first, then its faces merged INSIDE the prototype (merge once, benefit +N instances). On overlap, the suggestion is annotated +(`composes_with_instance_candidate: true`), not dropped — the two compose. + +## Output + +Report: + +- Root scanned and the `perf_small_mesh` entry signal. +- Surfaced parents with merge boundary, identity signal/disposition, per-material + grouping, and the human-readable suggestion. +- `routed_small_geometry` dispositions (merge vs `removeSmallGeometry`). +- Any `composes_with_instance_candidate` annotations. +- Caveats that the report is advisory and no stage edits were made. + +## Handoff + +For confirmed suggestions: + +1. Choose an edit target with `usd-edit-target-planner` (merge runs within each + prototype opened as its own root layer). +2. Use `restructure-decision` to confirm the intent-gated merge before mutation. +3. The confirmed `(scope × material)` group feeds the merge rewrite, which owns + execution and the eligibility guard. + +For the precise analyzer behavior, read +`references/mesh-fragmentation-finder-spec.md` only when implementing or debugging +the suggester. The merge win is reported on the draw-call axis, never as a disk +win; do not claim savings as achieved until a rewrite is performed and +after-profile metrics confirm it. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-mesh-fragmentation-candidates/references/mesh-fragmentation-finder-spec.md b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-mesh-fragmentation-candidates/references/mesh-fragmentation-finder-spec.md new file mode 100644 index 00000000..d2b8b207 --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-mesh-fragmentation-candidates/references/mesh-fragmentation-finder-spec.md @@ -0,0 +1,79 @@ +# Mesh-Fragmentation Suggester — Behavioral Specification + +Status: draft (rev 1) +Audience: a coding agent running or extending `mesh_fragmentation_finder.py`. +Style: behavior-only. + +## 1. Purpose + +Surface parents whose children look like a CAD/BIM/EDA converter +**face-explosion** — a flat fan of anonymous, same-material `Mesh` prims under a +named/`kind`-tagged unit — and **suggest** merging that fan up to the named +boundary, grouped by material. It is the cheap entry point for the +`reduction_route = merge` landing (`mesh-merge-rewrite-spec.md`). + +It is **read-only** and **decides nothing**. Merge is intent/archetype-gated, so +the suggester only surfaces and routes; the user (or the archetype default) +confirms. It is **not** a geometric engine: it does **no** vertex-coincidence +computation and applies **no** numeric merge threshold (OQ12 — proving the weld is +an O(all-points) pass and pointless for detection, since the merge op welds +anyway). + +## 2. Inputs (cheap or already computed) + +- The Phase-2c **`perf_small_mesh`** validator finding — the tininess signal and + the entry point (free; the validator already ran). Passed as + `small_mesh_paths`. +- Cheap structural reads per candidate parent (`scan_stage`, pxr): direct child + count + type uniformity, anonymous child naming (`Mesh_N`), the parent's + `kind`/name, and the distinct bound materials across the fan (a + binding-relationship target read — **no geometry, no points**). +- Optionally `instanced_paths` — the subtrees the instance-candidate finder + already claims (§5). + +## 3. The signals (surface, don't gate) + +A parent is surfaced when the **qualitative pattern** holds — *meaningless +children under a meaningful unit*: + +- a **flat fan** (mesh children dominate the direct children — low nesting); +- **anonymously named** children (`Mesh_N`, numeric/uuid tokens) — reference + designators (`U302`) and semantic names are NOT anonymous; +- under a parent that **carries identity** (`kind` ∈ {assembly, group, component, + subcomponent}, or a semantic name); and +- a **high mesh:material ratio** (many meshes, few distinct materials — re- + stitchable into one mesh per material). + +The `SUGGEST_MIN_FAN`, `*_HINT` knobs are **surfacing/ranking heuristics, not +merge gates**: they decide what to *show* and in what order, never whether a shown +fan may merge. The merge decision is the user's archetype-gated confirmation. + +## 4. Output + +For each surfaced parent, one suggestion: the **merge boundary** (the named/`kind` +ancestor to preserve), the `identity_signal` that keeps it addressable, the +`identity_disposition` (`weak` — the anonymous fan), the per-material grouping +(`merge_groups = distinct_materials`, `geomsubset_fallback` when > 1), and the +human-readable suggestion. Plus `routed_small_geometry`: the **one real decision** +— `perf_small_mesh` members inside a surfaced fan are real faces → **merge +(re-stitch)**; the rest are negligible → **removeSmallGeometry (delete)**. It does +not route a fan to delete and does not merge a scattered tiny mesh. + +The confirmed group feeds `mesh-merge-rewrite-spec.md` (which owns the +(scope × material) execution and the eligibility guard). + +## 5. Division of labor with the instance-candidate finder + +See the candidate reference's [Division of Labor with Hierarchy-Dedupe Candidates](../README.md#division-of-labor-with-hierarchy-dedupe-candidates) +for the canonical rule (the two never claim the same prims; a fan that is *also* a +repeated subtree is instanced at the component first, then its faces merged INSIDE +the prototype). Implementation note: when `instanced_paths` overlaps a surfaced +fan, **annotate** the suggestion (`composes_with_instance_candidate: true`) rather +than dropping it — mirroring the decision-order-≠-execution-order rule in +`mesh-merge-rewrite-spec.md` §6. + +## 6. Non-goals + +- No merge execution (that is `mesh-merge-rewrite-spec.md`). +- No vertex-coincidence / weld-ratio computation, no numeric merge threshold. +- No identity dissolution decision — it surfaces and routes; the user confirms. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-mesh-fragmentation-candidates/scripts/mesh_fragmentation_finder.py b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-mesh-fragmentation-candidates/scripts/mesh_fragmentation_finder.py new file mode 100644 index 00000000..4ac77ce9 --- /dev/null +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-mesh-fragmentation-candidates/scripts/mesh_fragmentation_finder.py @@ -0,0 +1,323 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +"""Mesh-fragmentation suggester — read-only converter-fan detector. + +Implements `mesh-fragmentation-finder-spec.md`. It is the cheap entry point for +the `reduction_route = merge` landing: it **surfaces** parents whose children look +like a CAD/BIM/EDA converter face-explosion (a flat fan of anonymous same-material +`Mesh` prims under a named/`kind`-tagged unit) and **suggests** merging that fan up +to the named boundary, grouped by material. It NEVER modifies the stage and it +NEVER decides the merge — merge is intent/archetype-gated, so the user (or the +archetype default) confirms. + +This is deliberately **not** a geometric engine like the instance-candidate +finder. It does **no** vertex-coincidence computation and applies **no** numeric +merge threshold (see OQ12 — proving the weld is O(all-points) and pointless for +detection, since the merge op welds anyway). Its inputs are cheap or already +computed: + + * the Phase-2c ``perf_small_mesh`` validator finding (free — the validator + already ran), the tininess signal and the entry point; and + * cheap structural reads per candidate parent: direct child count + type + uniformity, anonymous child naming (``Mesh_N``) under a named/``kind`` parent, + and the mesh:material ratio (distinct bound materials across the fan). + +The core decision function ``suggest_merges`` takes explicit, pre-computed parent +summaries so it is unit-testable without Kit. The thin ``scan_stage`` builds those +summaries from a live ``pxr`` stage with cheap reads only (no geometry, no points). + +Wiring: ``--emit-suggestions`` prints the ``suggestions[]`` packet (JSON). Each +suggestion names the **merge boundary** (the named/``kind`` ancestor to preserve), +the per-material grouping, and the identity disposition the user must confirm, and +routes the ``perf_small_mesh`` population to **merge (re-stitch)** vs +**removeSmallGeometry (delete)** — the one real decision the signals make. The +``mesh-merge-rewrite-spec.md`` route consumes the confirmed group. + + python3 mesh_fragmentation_finder.py --emit-suggestions \ + --small-mesh-paths small.json +""" +from __future__ import annotations + +import json +import os +import re +import sys + +# ============================== KNOBS ===================================== +# Surfacing heuristics, NOT merge gates. They decide what to SHOW; the merge +# decision is the user's archetype-gated confirmation. All literal for paste-edit. +# +# SUGGEST_MIN_FAN — what counts as a "fan" worth surfacing. A handful of children +# is not a converter explosion; this is the display floor, not a threshold that +# gates whether a surfaced fan may merge. +SUGGEST_MIN_FAN = 12 +# MESH_MATERIAL_RATIO_HINT — a fan of many meshes binding few distinct materials +# is the converter-explosion signature (re-stitchable into one mesh per +# material). Used to surface/rank, not to gate. +MESH_MATERIAL_RATIO_HINT = 4.0 +# ANON_CHILD_FRACTION_HINT — fraction of the fan that must be anonymously named +# (Mesh_N / Xform wrapper) for the "meaningless children under a meaningful +# unit" pattern to hold. +ANON_CHILD_FRACTION_HINT = 0.75 +# MESH_CHILD_FRACTION_HINT — fraction of direct children that are the mesh fan +# (low nesting / flat). A deep tree is not a flat fan. +MESH_CHILD_FRACTION_HINT = 0.75 +TOP_N = 25 +# ========================================================================== + +# Anonymous = converter-default naming: a generic-noun stem (Mesh, Mesh_12, mesh3, +# Xform_4, node_7), a purely numeric index (7, 0042), or a long hex/uuid-ish token. +# Reference designators (U302, R14, C7) and semantic names are deliberately NOT +# anonymous — a letter-prefixed alphanumeric carries identity, and merging it away +# would dissolve the reference-designator identity a service/BOM twin relies on. +_ANON_RE = re.compile( + r"^(mesh|xform|node|prim|group|shape|object|obj|geom|part)[_-]?\d*$" + r"|^\d+$" + r"|^[0-9a-fA-F]{12,}$", + re.IGNORECASE, +) + +_STRONG_IDENTITY_KINDS = ("assembly", "group", "component", "subcomponent") + + +def is_anonymous_name(name: str) -> bool: + """True when a prim name looks converter-generated (no human/semantic identity). + + Conservative: anything that is not clearly a default/numeric token is treated + as named (identity-bearing), so the suggester errs toward NOT surfacing — it + never proposes dissolving something that might carry identity. + """ + if not name: + return False + return bool(_ANON_RE.match(name.strip())) + + +def _parent_has_identity(summary: dict) -> bool: + """The boundary must carry real identity: a strong `kind`, or a non-anonymous + (semantic) name. This is what stays addressable after the merge.""" + kind = (summary.get("parent_kind") or "").strip().lower() + if kind in _STRONG_IDENTITY_KINDS: + return True + if summary.get("parent_named") is True: + return True + name = summary.get("parent_name") + if name and not is_anonymous_name(name): + return True + return False + + +def _matches_fragmentation_pattern(s: dict) -> bool: + """The qualitative converter-explosion pattern — meaningless children under a + meaningful unit. No magnitude threshold gates the *merge*; these signals only + decide what to surface.""" + child_count = int(s.get("child_count") or 0) + mesh_count = int(s.get("child_mesh_count") or 0) + if mesh_count < SUGGEST_MIN_FAN: + return False + # Flat fan: the mesh children dominate (little nesting). + if child_count and (mesh_count / child_count) < MESH_CHILD_FRACTION_HINT: + return False + # Anonymous children under an identity-bearing parent. + anon_frac = s.get("anonymous_child_fraction") + if anon_frac is None or anon_frac < ANON_CHILD_FRACTION_HINT: + return False + if not _parent_has_identity(s): + return False + # High mesh:material ratio — re-stitchable into one mesh per material. + distinct_materials = max(int(s.get("distinct_materials") or 1), 1) + if (mesh_count / distinct_materials) < MESH_MATERIAL_RATIO_HINT: + return False + return True + + +def _identity_signal(s: dict) -> str: + kind = (s.get("parent_kind") or "").strip().lower() + if kind in _STRONG_IDENTITY_KINDS: + return "kind" + name = s.get("parent_name") + if s.get("parent_named") is True or (name and not is_anonymous_name(name)): + return "naming" + return "none" + + +def suggest_merges(parent_summaries, *, small_mesh_paths=None, instanced_paths=None, + knobs=None) -> dict: + """Pure function: parent summaries -> {suggestions, routed_small_geometry, + diagnostics}. No stage access, no geometry — unit-testable without Kit. + + ``parent_summaries`` — one dict per candidate parent with cheap reads: + path, parent_kind, parent_name/parent_named, child_count, + child_mesh_count, anonymous_child_fraction, distinct_materials. + ``small_mesh_paths`` — ancestor-or-exact paths flagged ``perf_small_mesh`` by + the validator (the tininess signal / entry point). + ``instanced_paths`` — paths the instance-candidate finder already claims as + repeated subtrees (division of labor; see the spec). A fan that is ALSO a + repeated subtree is instanced at the component, then merged INSIDE the + prototype — so it is annotated, not double-claimed here. + """ + small = set(small_mesh_paths or []) + instanced = set(instanced_paths or []) + suggestions = [] + routed_delete = [] + + def _under(path, paths): + return any(path == p or path.startswith(p.rstrip("/") + "/") or p.startswith(path.rstrip("/") + "/") + for p in paths) + + for s in parent_summaries: + path = s.get("path") + if not path: + continue + if not _matches_fragmentation_pattern(s): + continue + mesh_count = int(s.get("child_mesh_count") or 0) + distinct_materials = max(int(s.get("distinct_materials") or 1), 1) + from_validator = _under(path, small) if small else False + composes_with_instance = _under(path, instanced) if instanced else False + suggestions.append({ + "merge_boundary": path, # preserved; never merge above it + "identity_signal": _identity_signal(s), # what keeps the boundary addressable + "identity_disposition": "weak", # the anonymous fan; user confirms + "reduction_route": "merge", + "fan_size": mesh_count, + "distinct_materials": distinct_materials, + "merge_groups": distinct_materials, # (scope × material): one mesh per material + "geomsubset_fallback": distinct_materials > 1, + "mesh_material_ratio": round(mesh_count / distinct_materials, 2), + "from_perf_small_mesh": from_validator, + "composes_with_instance_candidate": composes_with_instance, + "small_geometry_route": "merge", # re-stitch real faces, do NOT delete + "suggestion": ( + "Looks like a converter face-explosion: %d anonymous same-typed meshes " + "(%d material group(s)) under a named/kind unit. Merge up to '%s', grouped " + "by material%s? Identity-destroying (weak-identity fan) — confirm per archetype." + % (mesh_count, distinct_materials, path, + " (one mesh + a GeomSubset per material)" if distinct_materials > 1 else "") + ), + "note": ( + "Instance at this component FIRST, then merge the fan INSIDE the prototype." + if composes_with_instance else + "Render archetype may merge to the named boundary; service/BOM/simulation " + "keeps component identity and merges only sub-component shards." + ), + }) + + # perf_small_mesh members NOT part of any surfaced fragmentation fan are the + # delete candidates (the validator's catalogued removeSmallGeometry remedy): + # genuinely negligible tiny meshes, not re-stitchable faces. + surfaced = {x["merge_boundary"] for x in suggestions} + for p in sorted(small): + if not any(p == b or p.startswith(b.rstrip("/") + "/") for b in surfaced): + routed_delete.append(p) + + suggestions.sort(key=lambda x: x["fan_size"], reverse=True) + return { + "suggestions": suggestions[: (knobs or {}).get("top_n", TOP_N)], + "routed_small_geometry": { + "merge_restitch_boundaries": sorted(surfaced), + "remove_small_geometry_candidates": routed_delete, + "note": ( + "perf_small_mesh population split: meshes inside a surfaced fan are real " + "faces -> route to merge (re-stitch); the rest are negligible -> " + "removeSmallGeometry (delete). The one decision the signals make." + ), + }, + "diagnostics": { + "parents_examined": len(parent_summaries), + "fans_surfaced": len(suggestions), + }, + } + + +# -------------------------------------------------------------------------- +# Thin pxr scan (cheap reads only — no geometry / no points / no coincidence). +# -------------------------------------------------------------------------- + +def scan_stage(stage, knobs=None) -> list: + """Build parent summaries from a live USD stage with CHEAP reads only: + direct child counts, type uniformity, anonymous naming, and the distinct bound + materials across the fan (a binding-relationship target path read — no + geometry, no points). Requires ``pxr``; the decision core does not.""" + from pxr import Usd, UsdGeom, UsdShade # noqa: F401 (import-gated) + + summaries = [] + for prim in stage.Traverse(): + children = list(prim.GetChildren()) + if not children: + continue + mesh_children = [c for c in children if c.GetTypeName() == "Mesh"] + # Xform->single-Mesh wrapper pairs count as mesh-fan members too. + for c in children: + if c.GetTypeName() == "Xform": + gc = list(c.GetChildren()) + if len(gc) == 1 and gc[0].GetTypeName() == "Mesh": + mesh_children.append(gc[0]) + if not mesh_children: + continue + anon = sum(1 for c in mesh_children if is_anonymous_name(c.GetName())) + # Distinct bound materials across the fan (cheap rel-target reads). + mats = set() + for c in mesh_children: + try: + binding = UsdShade.MaterialBindingAPI(c) + rel = binding.GetDirectBindingRel() + tgts = rel.GetTargets() if rel else [] + mats.add(str(tgts[0]) if tgts else "") + except Exception: + mats.add("") + kind = "" + try: + kind = Usd.ModelAPI(prim).GetKind() or "" + except Exception: + kind = "" + summaries.append({ + "path": str(prim.GetPath()), + "parent_kind": kind, + "parent_name": prim.GetName(), + "child_count": len(children), + "child_mesh_count": len(mesh_children), + "anonymous_child_fraction": (anon / len(mesh_children)) if mesh_children else 0.0, + "distinct_materials": len([m for m in mats if m not in ("", "")]) or len(mats), + }) + return summaries + + +def render_report(result: dict) -> str: + L = ["Mesh-fragmentation suggester — %d parent(s) examined, %d fan(s) surfaced." + % (result["diagnostics"]["parents_examined"], result["diagnostics"]["fans_surfaced"])] + for s in result["suggestions"]: + L.append(" - %s [fan=%d, materials=%d, ratio=%.1f%s%s]" + % (s["merge_boundary"], s["fan_size"], s["distinct_materials"], + s["mesh_material_ratio"], + ", from perf_small_mesh" if s["from_perf_small_mesh"] else "", + ", composes-with-instance" if s["composes_with_instance_candidate"] else "")) + L.append(" %s" % s["suggestion"]) + rsg = result["routed_small_geometry"] + if rsg["remove_small_geometry_candidates"]: + L.append(" removeSmallGeometry (delete) candidates: %d" + % len(rsg["remove_small_geometry_candidates"])) + return "\n".join(L) + + +def _main(argv) -> int: + emit = "--emit-suggestions" in argv + args = [a for a in argv[1:] if not a.startswith("--")] + small_paths = [] + if "--small-mesh-paths" in argv: + i = argv.index("--small-mesh-paths") + if i + 1 < len(argv): + small_paths = json.loads(open(argv[i + 1]).read()) + args = [a for a in args if a != argv[i + 1]] + stage_path = args[0] if args else os.environ.get("DTP_STAGE") + if not stage_path: + sys.stderr.write("usage: mesh_fragmentation_finder.py [--emit-suggestions]\n") + return 2 + from pxr import Usd + stage = Usd.Stage.Open(stage_path) + result = suggest_merges(scan_stage(stage), small_mesh_paths=small_paths) + print(json.dumps(result, indent=2) if emit else render_report(result)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(_main(sys.argv)) diff --git a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/scripts/usd-structure-assessment-report.schema.json b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/scripts/usd-structure-assessment-report.schema.json index 93eab3a2..2a455a21 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/scripts/usd-structure-assessment-report.schema.json +++ b/skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/scripts/usd-structure-assessment-report.schema.json @@ -266,7 +266,7 @@ }, "validation_scope": { "type": "object", - "description": "Feeds directly into so-run-validators. Strict: these arrays are the handoff contract.", + "description": "Feeds directly into usd-optimize-run-validators. Strict: these arrays are the handoff contract.", "required": [ "per_asset", "cross_component_pairs", @@ -282,8 +282,40 @@ }, "cross_component_pairs": { "type": "array", + "description": "Enclosing/enclosed boundary pairs that scope the Tier-3 occlusion/overlap probe, referenced by boundary_id (see asset_boundary_suggestions.boundaries[] and usd-structure-assessment README §2.1 for how pairs are nominated and gated).", "items": { - "type": "string" + "type": "object", + "required": [ + "enclosing_boundary_id", + "enclosed_boundary_id" + ], + "additionalProperties": false, + "properties": { + "enclosing_boundary_id": { + "type": "string", + "description": "boundary_id of the enclosing boundary (spatial_role: enclosing)." + }, + "enclosed_boundary_id": { + "type": "string", + "description": "boundary_id of the enclosed boundary (spatial_role: enclosed)." + }, + "enclosure_opaque": { + "type": "boolean", + "description": "Optional opacity hint, not a required assertion. true = opaque enclosure (probe); false = transparent (skip — internals are visible); absent = unknown, in which case the pair is still probed and opacity is resolved during the Tier-3 material/geometry probe. SA must not assert this boolean when opacity is not determinable from material-binding metadata alone — omit it instead." + }, + "probe": { + "type": "string", + "enum": ["spatial_occluded", "spatial_overlapping", "spatial_coinciding"], + "description": "Which Tier-3 spatial concept this pair scopes. Defaults to spatial_occluded." + }, + "bbox_confirmed": { + "type": "boolean", + "description": "Optional informational confirmation that authored-extent overlap corroborated the nomination. Never gates whether the probe runs; absence does not retract the nomination." + }, + "notes": { + "type": "string" + } + } } }, "skip": { @@ -307,29 +339,59 @@ "type": "object", "additionalProperties": true }, - "layer_health": { - "type": "object", - "additionalProperties": true - }, - "scale_assessment": { - "type": "object", - "additionalProperties": true - }, "asset_boundary_suggestions": { "type": "object", - "additionalProperties": true - }, - "flagged_assets": { - "type": "array", - "items": { - "type": "object", - "additionalProperties": true + "description": "Candidate asset/sub-asset boundaries for restructuring AND the boundary records occlusion nomination keys off. candidate_levels[] stay permissive; boundaries[] carries the nominated enclosing/enclosed product boundaries cross_component_pairs references by id. See usd-structure-assessment README §2.1 for the nomination model.", + "additionalProperties": true, + "properties": { + "boundaries": { + "type": "array", + "description": "Nominated boundaries (candidate_source 'hash' for repeated modules, 'semantics' for unique one-off enclosed products). Nomination is the primary occlusion signal; a hash nomination does NOT by itself create a pair — pairing requires an enclosing+enclosed spatial_role established from semantics/hierarchy (see README §2.1).", + "items": { + "type": "object", + "required": ["boundary_id", "prim_path", "candidate_source"], + "additionalProperties": true, + "allOf": [ + { + "if": { + "properties": { "candidate_source": { "const": "semantics" } }, + "required": ["candidate_source"] + }, + "then": { "required": ["semantic_label"] } + } + ], + "properties": { + "boundary_id": { + "type": "string", + "description": "Stable id referenced by cross_component_pairs[].enclosing_boundary_id / enclosed_boundary_id." + }, + "prim_path": { + "type": "string", + "description": "USD prim path of the nominated boundary root." + }, + "candidate_source": { + "type": "string", + "enum": ["hash", "semantics"], + "description": "'hash' = subtree-hash dedupe group (duplicate-count >= 2). 'semantics' = kind/naming/discipline-container signal for a one-off enclosed product (requires semantic_label)." + }, + "spatial_role": { + "type": "string", + "enum": ["enclosing", "enclosed", "standalone"], + "description": "Containment role. Required on any boundary referenced by a cross_component_pair: 'enclosing' = shell/housing, 'enclosed' = interior product. 'standalone' = no containment relationship." + }, + "enclosure_opaque": { + "type": "boolean", + "description": "Optional opacity hint for an enclosing boundary (true=opaque, false=transparent, absent=unknown). Omit when opacity is not determinable from material-binding metadata alone; the Tier-3 probe resolves unknown opacity." + }, + "semantic_label": { + "type": "string", + "description": "The kind/name/discipline signal that drove a candidate_source: semantics nomination (e.g. 'Engine', 'pump_housing', 'HVAC'). Required when candidate_source is 'semantics'." + } + } + } + } } }, - "variants_and_payloads": { - "type": "object", - "additionalProperties": true - }, "kind_hierarchy": { "type": "object", "additionalProperties": true @@ -344,12 +406,6 @@ "type": "object", "additionalProperties": true } - }, - "recommended_next_actions": { - "type": "array", - "items": { - "type": "string" - } } } } diff --git a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/README.md b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/README.md index d5d35645..6a8d22f8 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/README.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/README.md @@ -1,25 +1,25 @@ # USD Validation Runner (master router) - - - ## When to Use -Use this reference for validation-only requests or when the performance workflow -reaches Phase 2c, Phase 4d, Phase 6b, or an iteration that needs validation -evidence. +Use this reference when the performance workflow reaches Phase 2c (Tier 1 +whole-stage), Phase 4 (per-target Tier 2/3 + 4d re-verify), Phase 6b, or an +iteration that needs validation evidence. Validators always run as phases of the +one optimize+validate pipeline; there is no validate-and-stop entry. ## Instructions -1. Identify whether the request is validation-only or a validation phase inside - the optimization workflow. +1. Confirm which validation phase of the optimization workflow this is (Phase + 2c, Phase 4, Phase 6b, or an iteration); validators run inside the pipeline, + not as a standalone validation-only request. 2. Use structure assessment and profile evidence before selecting validators. - Do not instantiate a validator engine, import Scene Optimizer validators, or + Do not instantiate a validator engine, import Usd Optimize validators, or enumerate/run rules until a selected validation plan exists. 3. Select the smallest validation stack that can change the user-visible decision or operation plan. -4. Ask before any full Asset Validator sweep, Tier 3 expensive probe, or - expanded iteration scope. +4. Ask before any full usd-validation-nvidia sweep, full-stage (un-scoped) Tier 3 + probe, or expanded iteration scope. Scoped Tier 3 probes run without approval + (see the Tier 3 coverage rule and Hard Rule 4). 5. Route execution to the owning validation reference or skill and preserve evidence paths for later reporting. @@ -28,22 +28,22 @@ evidence. This runner is the single owner for validation scoping, full-sweep approval, large-stage thresholds, masked-stage spot-check policy, and selected-probe planning. Downstream validator references such as -`references/validate-usd-asset-validator.md` consume the scope note and own +`references/validate-usd-validation-nvidia.md` consume the scope note and own runtime invocation details only. ## Pre-flight Checklist Before running validators, confirm: -- [ ] The workflow has SA `summary_counts`, `phase_recommendation`, - `validation_scope`, and `flagged_assets` unless this is a direct - validation-only request. +- [ ] The workflow has SA `summary_counts`, `phase_recommendation`, and + `validation_scope` (always available, since validation runs as a pipeline + phase downstream of structural assessment). - [ ] The stage is classified for validation planning as small or large using the thresholds below. - [ ] The plan names selected rules and probes, why they were selected, why a full sweep was skipped or approved, and artifact paths. - [ ] Expensive checks and full sweeps have explicit user approval when needed. -- [ ] Findings will be routed to `so-interpret-validators` for op-chain +- [ ] Findings will be routed to `usd-optimize-interpret-validators` for op-chain construction; do not map findings to ops yourself. ## Output Format @@ -52,7 +52,8 @@ Return a scoped validation plan or validation summary naming the selected validator stack, selected rules and probes, skipped expensive checks, approval gates, artifact paths, and findings that affect the optimization plan. -For Phase 2c, also write a compact scope note matching +For Phase 2c (whole-stage Tier 1) and for each Phase 4 target (per-target Tier +2/3), write a compact scope note matching `scripts/validation-scope-note.schema.json`. Validators are named by **canonical concept**, not runtime class name: @@ -93,13 +94,12 @@ skill attempts runtime probing or stage open. ## Prerequisites - Target stage or asset paths and resolver context. -- Available validator runtime (Omni Asset Validator inside Kit, project-managed - AV install, or installed Scene Optimizer APIs). +- Available validator runtime (Omni usd-validation-nvidia inside Kit, project-managed + AV install, or installed Usd Optimize APIs). - Artifact directory for logs, CSV/JSON findings, and provider summaries. - Baseline, waiver, or failure policy for pre/post processing gates. - For performance-stack scoping: `usd-structure-assessment` report with - `summary_counts`, `phase_recommendation`, `validation_scope`, and - `flagged_assets`. + `summary_counts`, `phase_recommendation`, and `validation_scope`. ## Session-start runtime gate @@ -118,23 +118,33 @@ session, skip the gate and proceed. --- -## Phase 2c Order: Scope Before Code +## Validation placement: 2c (whole-stage) vs Phase 4 (per target) + +Validation is split by granularity, not run all at once: -Phase 2c is **Phase-aware validation scope + selected probes**. It is not a -default validator sweep. +- **Phase 2c — whole-stage, pre-restructure.** Tier 1 cheap whole-stage + stats/probes plus the minimum-openability/structural checks that classify the + stage and feed the 2e restructure decision. This is not a default validator + sweep. +- **Phase 4 — per target, post-restructure.** Tier 2 (per `phase4_targets[]` + entry) and Tier 3 (per flagged cross-component pair) run inside Phase 4's + per-target loop, on the actual restructured artifact, scoped to one + target/pair by construction. This is the primary model for per-target/per-pair + concepts — see **Post-Restructure / Post-Decompose Validation Strategy**. + (A pre-restructure Tier 2/3 diagnosis runs only on explicit user request.) -Required order: +Required order at 2c: 1. Read Phase 1 profile and `usd-structure-assessment` output. 2. Classify the asset as small or large for validation planning. -3. Build the selected validation plan from `summary_counts`, - `phase_recommendation`, `validation_scope`, and `flagged_assets`. +3. Build the Tier 1 + structural plan from `summary_counts`, + `phase_recommendation`, and `validation_scope`. 4. Record the scope note/artifact. -5. Only then run the selected rules or probes. +5. Only then run the selected Tier 1 rules/probes. For monolithic `optimize-as-is`, the original stage remains the optimization -target, but validation still follows this selected-scope policy. A monolithic -target does not authorize a full sweep. +target (Phase 4 target N=1), and its Tier 2/3 validation runs in the Phase 4 +loop like any other target. A monolithic target does not authorize a full sweep. ## Large for Validation Planning @@ -149,7 +159,7 @@ Treat a stage as **large for validation planning** when any condition is true: Large-stage behavior: -- Do not run a default full-stage Asset Validator or Scene Optimizer rule sweep. +- Do not run a default full-stage usd-validation-nvidia or Usd Optimize rule sweep. - Ask before full sweep if the user explicitly wants exhaustive validation. - Prefer minimum-openability, Tier 1 cheap whole-stage stats/probes, targeted rules, Tier 2/3 subprocess runs with timeouts, or masked-stage @@ -185,8 +195,8 @@ target; not a default AV all-rules sweep. ### Tier 2: Targeted Medium Probes -Tier 2 registry concepts, run per flagged asset (or a bounded sample) in -killable subprocesses. +Tier 2 registry concepts, run per `phase4_targets[]` entry (or a bounded sample) +in killable subprocesses, inside the Phase 4 per-target loop. ### Tier 3: Expensive Probes (evidence-gated, mandatory when flagged) @@ -201,13 +211,23 @@ What is approval-gated is *cost*, not *coverage*: - **Scoped probe = default, no approval needed.** Restrict to the flagged paths/pairs with `paths=` / `Usd.Stage.OpenMasked()` and run in a bounded - subprocess with a timeout. This is the normal Tier 3 path. + subprocess with a timeout. This is the normal Tier 3 path — it runs in the + Phase 4 per-target loop, per flagged pair. - **Full-stage probe = approval-gated.** Only run the un-scoped, whole-stage version after the full-sweep approval gate. - **Timeout is a recorded disposition, not a skip.** If the scoped probe times out, record `timeout_recorded` and retry a masked/standalone sample — do not drop the target. +**Analyze ≠ apply.** The scoped probe is *analysis* and is never gated on cost — +it produces a candidate list only. That is the runner's own scoping rule, and it +is all this section owns: scoped probes run without approval. Any destructive +*apply* its findings motivate (e.g. `removePrims` of occluded interiors) is gated +**separately** under the apply-authority model owned by +`usd-optimize-run-operations/references/operation-safety.md` "Apply authority" — see that +section for why the apply (not the probe) needs user intent and how it is +surfaced. So "ask the user" attaches to the apply step, not to the probe. + Every flagged Tier 3 target must end in a coverage-ledger disposition (see **Completion Gate**). "I skipped it because it was expensive" is not a valid outcome; the valid outcomes are probed (clean or with findings), `user_declined` @@ -234,7 +254,7 @@ the structure-assessment and validator reports: | `usd-structure-assessment-report.schema.json` | `phase_recommendation` | Selects the default validation posture: `structuring`, `optimization`, or `already_optimized`. | | `usd-structure-assessment-report.schema.json` | `summary_counts.prim_count`, `summary_counts.mesh_count`, `summary_counts.prototype_count`, `summary_counts.instance_count`, `summary_counts.reference_count`, `summary_counts.payload_count` | Determines large-stage status and whether Tier 2/3 must run per target, sampled, or not at all. | | `usd-structure-assessment-report.schema.json` | `validation_scope.per_asset`, `validation_scope.cross_component_pairs`, `validation_scope.skip` | Defines the concrete target set for Tier 2 and Tier 3. | -| `usd-structure-assessment-report.schema.json` | `flagged_assets`, `findings`, `hierarchy_dedupe.recommended`, `hierarchy_dedupe.top_candidates` | Supplies reasons to include targeted Tier 2 probes or to ask for Tier 3 probes. | +| `usd-structure-assessment-report.schema.json` | `findings`, `hierarchy_dedupe.recommended`, `hierarchy_dedupe.top_candidates` | Supplies reasons to include targeted Tier 2 probes or to ask for Tier 3 probes. | | `validator-concepts.json` | `tier`, `cost_class`, `gpu_bound`, `scope_policy` per canonical concept | Single source of truth for a concept's tier and scope. Read it; do not restate tiers elsewhere. | | `rule-reference.md` | Validator signal → canonical concept → backing op | Interpretation map only (signal to concept to fix op). Carries no tier. | | `validation-report.schema.json` | `validators[].canonical_name`, `validators[].status`, `validators[].issues`, `summary.errorCount`, `coverage_ledger` | The canonical executor's own report — what ran (by canonical concept and resolved `(module, class_name)` identity) and what was found. Use it to narrow later iterations, not to widen scope silently. | @@ -246,15 +266,15 @@ concept to a unique `(module, class_name)` identity at run time. Do not put runtime class names (`IndexedPrimvarChecker`), operation names, display labels, or category names (`Geometry`, `Usd:Performance`) in the plan — class names are not unique across providers and categories are lookup buckets, not approval -scope. The registry's `preferred_provider` decides Scene Optimizer vs Asset -Validator; performance tuning prefers the Scene Optimizer implementation. +scope. The registry's `preferred_provider` decides Usd Optimize vs Asset +Validator; performance tuning prefers the Usd Optimize implementation. ## Phase-Aware Defaults | `phase_recommendation` | Default scope | |---|---| | `structuring` | Minimum-openability + targeted structural blockers only. Do not validate geometry about to be restructured. | -| `optimization` | Minimum-openability + Tier 1 cheap whole-stage stats/probes + Tier 2 on flagged targets or sample. Tier 3 scoped probes mandatory on flagged targets/pairs; full-stage Tier 3 after approval. | +| `optimization` | **2c:** Minimum-openability + Tier 1 cheap whole-stage stats/probes. **Phase 4 (per target):** Tier 2 per `phase4_targets[]` entry; Tier 3 scoped probe mandatory per flagged cross-component pair. No full-stage Tier 2/3 default; whole-stage Tier 3 only on explicit user request. | | `already_optimized` | Minimum-openability + Tier 1 cheap whole-stage stats/probes only; ask before expanding. | | missing | Run structure assessment first. Do not begin with validators. | @@ -268,20 +288,54 @@ add concepts that no row selects, and do not drop a concept a row selects. Tier and scope policy for each concept come from `validator-concepts.json` (the "Target" column states only the selection granularity, not the tier). +**Execution phase follows the "Target" granularity:** **whole-stage** rows +(the "Always" safety gate + the `optimization` whole-stage row) run at Phase 2c +as Tier 1; **per-target / flagged-pair / flagged-subtree** rows run in the Phase +4 per-target loop on the restructured artifact (target N=1 = the monolith when +no restructure happened). The selection function is identical in both phases; +only the artifact it runs against differs. + | SA signal (condition) | Concepts selected | Target | |---|---|---| | Always (any `optimization`/`already_optimized` run) | `composition_missing_ref`, `material_path`, `material_dangling_binding`, `texture_bind`, `texture_normalmap` | whole-stage safety gate | | `phase_recommendation = optimization` | `material_duplicates`, `structure_empty_leaf`, `structure_invisible`, `structure_flat_hierarchy`, `extents_zero`, `perf_small_mesh`, `perf_sparse_mesh`, `perf_rtx_mesh_count`, `perf_redundant_timesamples`, `perf_high_vertex_count` | whole stage | | Asset posture is CAD / BIM / MEP / converted (e.g. Revit/HOOPS) | `primitive_fit` | per flagged target — **mandatory**, never dropped | -| `flagged_assets[*]` primvar/UV signal | `primvar_indexability`, `primvar_unused` | per flagged asset | -| `flagged_assets[*]` mesh-hygiene signal (welds/degenerate/winding) | `vertex_weld`, `topology_zero_area_faces`, `normals_winding` | per flagged asset | +| Any `optimization` run — cheap, lossless/self-gating primvar cleanup (no flag required) | `primvar_indexability`, `primvar_unused` | per target or sample | +| Any `optimization` run — geometry-intrinsic mesh hygiene (no flag required) | `vertex_weld`, `topology_zero_area_faces`, `normals_winding` | per target, executed at Phase 4 per `phase4_targets[]` | | `hierarchy_dedupe.recommended` or duplicate-geometry signal | `geom_duplicates` (+ `geom_duplicates_fuzzy` if near-duplicates) | flagged subtree | -| `validation_scope.cross_component_pairs[*]` with `enclosure_opaque: true` | `spatial_occluded` | flagged pair — **mandatory** scoped probe | +| `validation_scope.cross_component_pairs[*]` not explicitly transparent (`enclosure_opaque` true or unset) | `spatial_occluded` | flagged pair — **mandatory** scoped probe | | `validation_scope.cross_component_pairs[*]` (routing/overlap) | `spatial_overlapping`, `spatial_coinciding` | flagged pair — **mandatory** scoped probe | | Target is simulation-ready (physics/Boolean/3D-print), not visualization | `topology_manifold`, `normals_validity` | flagged target | -If `validation_scope.skip` lists a target, it is excluded from all rows. If no -asset is flagged, only the "Always" + whole-stage rows fire; ask before adding more. +If `validation_scope.skip` lists a target, it is excluded from all rows. With +**zero** flagged assets, the "Always" + whole-stage rows, the flag-independent +per-target rows (cheap primvar cleanup, mesh hygiene), and the CAD/converted +`primitive_fit` row all still fire; only the evidence-gated rows (Tier-3 spatial +pairs, duplicate-geometry, sim-ready) stay empty when their signal is absent. Ask +before adding concepts no row selects. + +**Why the primvar/mesh-hygiene rows are not flag-gated.** +`primvar_unused`/`primvar_indexability` (lossless, self-gating UV/primvar cleanup) +and the mesh-hygiene trio (`vertex_weld`, `topology_zero_area_faces`, +`normals_winding`) are geometry-intrinsic, not spatial. SA is structural-only and +reads no geometry arrays, so it cannot pre-flag a primvar/mesh-hygiene issue at +all; gating their *selection* on any SA structural flag would make them +unreachable on extent-only CAD — detection would silently never run. Selection is +therefore +evidence-independent (always, on any `optimization` run); the registry +`cost_class: cheap` / `per_target_or_sample` policy still governs cost and +granularity, and the *apply* step (lossless auto-apply for primvars; +`meshCleanup` confirmation-gated) still governs whether a fix is written. The op +being lossless is irrelevant if the concept is never selected to recommend it. + +`validation_scope.cross_component_pairs[*]` items are boundary-ID reference +objects resolved through `asset_boundary_suggestions.boundaries[]`; SA owns how +pairs are nominated (`candidate_source` hash OR semantics) and when `spatial_role` +/ `enclosure_opaque` are set — see `usd-structure-assessment` §2.1. A pair is +probed unless it is *explicitly* transparent (`enclosure_opaque: false`); `true` +or unset (unknown) both schedule the mandatory Tier-3 probe, which resolves +opacity. `bbox_confirmed` is informational confirmation only — it never gates +whether the probe runs. ## Iteration Subtraction @@ -303,20 +357,20 @@ silently disagree with an earlier one by re-expanding scope. ## Scoping Rules 1. Structure assessment is the first filter. Use `summary_counts`, - duplicate-hierarchy candidates, `validation_scope`, and `flagged_assets` to + duplicate-hierarchy candidates, and `validation_scope` to decide which validators can change the optimization plan. 2. **Which concepts to run is decided by Deterministic Selection above; tier and scope policy come from `validator-concepts.json`.** This section does not re-derive selection or tiering. 3. Do not start performance work with a full default AV sweep. -4. Keep SO analysis in the validation workflow. Importing SO validators makes +4. Keep SO analysis in the validation workflow. Importing Usd Optimize validators makes rules discoverable; it does not authorize running all of them. 5. For cross-component validators, use `Usd.Stage.OpenMasked()` covering only the flagged pair and dependency closures, or validate standalone target files. 6. Do not run noisy/slow concepts globally in Phase 2c. Any registry concept that is `gpu_bound`, `cost_class: expensive`, or `stage_dependent` is scoped to flagged targets/pairs only — never a full-stage default. -7. Category-scoped AV is still a scoped whole-stage traversal for that category. +7. Category-scoped usd-validation-nvidia is still a scoped whole-stage traversal for that category. On large stages, ask before full sweep and prefer masked spot checks or bounded parallel subprocesses with timeouts. 8. Prefer summaries over issue dumps. Apply @@ -358,8 +412,8 @@ class_name)` via `references/validator-concepts.json`, enables exactly those rule classes (never `init_rules=True`), and opens the stage scoped. It is fail-closed by contract: unknown concept, ambiguous identity, unregistered rule, or missing runtime all raise — there is no bare-name lookup and no CLI fallback. -This is what disambiguates the Scene Optimizer `IndexedPrimvarChecker` (fast -triage) from the Asset Validator one (full audit) that share a class name. +This is what disambiguates the Usd Optimize `IndexedPrimvarChecker` (fast +triage) from the usd-validation-nvidia one (full audit) that share a class name. ```python from usd_validation_executor import ( @@ -449,6 +503,9 @@ tags, mesh coverage percentage, and evidence scope. ## Post-Restructure / Post-Decompose Validation Strategy +This is the **primary model** for Tier 2/3 (per-target/per-pair) validation, not +an exception: it runs inside the Phase 4 per-target loop after restructure. + After `apply-restructure` or `decompose-for-selective-loading` produces an assembly root plus payload/prototype files, do not open the full composed stage with all payloads loaded for a blanket validator sweep. @@ -467,9 +524,9 @@ with all payloads loaded for a blanket validator sweep. Each target re-enters this runner independently; approval gates and spot-check thresholds apply per target, not to the original composed stage. -## Asset Validator Load Rules +## usd-validation-nvidia Load Rules -The Asset Validator's `ComplianceChecker` opens a new stage from the input's +The usd-validation-nvidia's `ComplianceChecker` opens a new stage from the input's root layer with default `LoadAll` semantics. Caller `StageLoadRules` such as `LoadNone` are discarded. `StagePopulationMask` is preserved, so `Usd.Stage.OpenMasked()` is the reliable scoping mechanism. @@ -478,7 +535,7 @@ Do not rely on `LoadNone` or `stage.Load(specific_path)` for validation scoping. Use `OpenMasked` or validate standalone payload/prototype files. For small/medium stages, use the standard selected validation plan via -`so-run-validators`, but keep the same tier execution model: Tier 1 may batch; +`usd-optimize-run-validators`, but keep the same tier execution model: Tier 1 may batch; Tier 2 and Tier 3 use bounded subprocesses. ## Validation Plan Shape @@ -493,11 +550,19 @@ Checks**. | Intent | Stacks | |---|---| -| Validate this USD before mutation | Pre-mutation USD stack: minimum-openability plus targeted Asset Validator coverage when needed. | +| Validate this USD before mutation | Pre-mutation USD stack: minimum-openability plus targeted usd-validation-nvidia coverage when needed. | | Broad performance ask | `usd-structure-assessment` first, then selected performance stack per this runner. Add pre-mutation USD stack only when validity affects mutation safety. | | Run perf validators only | Performance stack only, selected from SA evidence or the user's explicit target list. | -| Validate optimized output | Same or narrower stacks than Phase 2c for fair comparison unless the user approves expansion. | -| Formal conformance/exhaustive validation | Ask before full sweep, then route through the selected AV/runtime with explicit timeout and artifacts. | +| Validate optimized output | Phase 4 re-verify per target (4d) + the Phase 2c Tier 1 whole-stage re-run in Phase 6b for a fair stage-level comparison; same-or-narrower unless the user approves expansion. | +| Formal conformance/exhaustive validation | Ask before full sweep, then route through the selected usd-validation-nvidia/runtime with explicit timeout and artifacts. | + +Doc ownership for each stack (read the owning doc before writing commands): + +- Pre-mutation USD stack -> `references/validate-usd-validation-nvidia.md`. +- Performance stack (Usd Optimize validator execution) -> `references/usd-optimize-run-validators/README.md`. +- Turning validator findings into operations -> `references/usd-optimize-interpret-validators/README.md`. +- Concept selection / tiers / scope notes -> this README plus + `references/validator-concepts.json` (registry; tiers live only there). ## Required Gates @@ -526,7 +591,7 @@ phase scoping so Phase 6 and Phase 7 can reproduce or narrow it. 1. Never run all validators on all assets by default. 2. Never use `ValidationEngine()` or `ValidationEngine(init_rules=True)` after - SO validator registration unless exhaustive validation was approved. + Usd Optimize validator registration unless exhaustive validation was approved. 3. Never run Tier 3 without structural evidence from the assessment. 4. When SA flags a Tier 3 target, the **scoped** probe is mandatory and needs no approval; ask only before the **full-stage** version. Silent omission of a @@ -546,16 +611,16 @@ phase scoping so Phase 6 and Phase 7 can reproduce or narrow it. - If `omni_asset_validate` is unavailable, record it as missing rather than fabricating a pass. -- If Scene Optimizer validator imports fail, do not report SO-specific results. +- If Usd Optimize validator imports fail, do not report SO-specific results. - If the bundled `validator-venv` is slow or lacks dependencies, prefer a Kit or - project-managed Asset Validator environment. + project-managed usd-validation-nvidia environment. - Named validator unavailable: record the gap and choose the nearest supported source only when it answers the same scoped question. ## References -- `references/validate-usd-asset-validator.md` - Asset Validator runtime +- `references/validate-usd-validation-nvidia.md` - usd-validation-nvidia runtime invocation details. -- `skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-run-validators/references/infrastructure.md` - SO validator infrastructure. +- `skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-run-validators/references/infrastructure.md` - Usd Optimize validator infrastructure. - `skills/omniverse-usd-performance-tuning/references/workflow.md` - canonical 7-phase flow context for where validation sits. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/README.md b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-interpret-validators/README.md similarity index 71% rename from skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/README.md rename to skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-interpret-validators/README.md index 476ef703..df0f227b 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/README.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-interpret-validators/README.md @@ -1,22 +1,18 @@ - - - -# so-interpret-validators - Local Recommendation Policy and Upstream Handoff +# usd-optimize-interpret-validators - Local Recommendation Policy and Upstream Handoff This local reference preserves the digitaltwin workflow milestone. Scene Optimizer mechanics for this step are owned by upstream `usd-optimize`. -- Public repository: [https://github.com/NVIDIA-omniverse/usd-optimize/](https://github.com/NVIDIA-omniverse/usd-optimize/) +- Public repository: [https://github.com/NVIDIA-Omniverse/usd-optimize/](https://github.com/NVIDIA-Omniverse/usd-optimize/) - Package path: `.agents/skills/interpret-validators/SKILL.md` -- Upstream web URL: [https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/skills/interpret-validators/SKILL.md](https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/skills/interpret-validators/SKILL.md) +- Upstream web URL: [https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/.agents/skills/interpret-validators/SKILL.md](https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/.agents/skills/interpret-validators/SKILL.md) Resolve the upstream guide without cloning the source repo: -1. `$SCENE_OPTIMIZER_PACKAGE_ROOT/.agents/skills/interpret-validators/SKILL.md` -2. `$SO_HOME/.agents/skills/interpret-validators/SKILL.md` +1. `$USD_OPTIMIZE_ROOT/.agents/skills/interpret-validators/SKILL.md` +2. `$USD_OPTIMIZE_ROOT/.agents/skills/interpret-validators/SKILL.md` -If no package root is available, download and extract the published -`scene_optimizer_core_...release.zip` package for the target platform (direct +If no package root is available, download and extract the prebuilt Usd Optimize release package (current asset name + download: `references/upstreams/usd-optimize.md`) (direct archive URLs are in `references/upstreams/usd-optimize.md`), or use the package path/URL supplied by the user. If the user supplies an extracted package root directly, resolve this same package path under that root. If @@ -25,7 +21,7 @@ reads. Do not clone the source repo just to read upstream SO guidance. ## Local Responsibilities -- Preserve logical milestone name `so-interpret-validators`. +- Preserve logical milestone name `usd-optimize-interpret-validators`. - Use `usd-validation-runner/README.md` for tiering, phase-aware subsets, selected-validator execution policy, and approval gates. - Use `rule-reference.md` only for local recommendation routing; upstream owns generic artifact interpretation mechanics. @@ -35,10 +31,11 @@ reads. Do not clone the source repo just to read upstream SO guidance. Before producing the curated op chain, re-read and confirm: -- [ ] **SA containment findings** — if SA flagged pairs with - `reason: containment` AND `enclosure_opaque: true`, include - `findOccludedMeshes → removePrims` as the FIRST op in the chain. - Skip pairs where enclosure is transparent. +- [ ] **SA containment pairs** — if SA emitted + `validation_scope.cross_component_pairs` that aren't explicitly transparent + (`enclosure_opaque` true or unset; nominated via `candidate_source` hash OR + semantics), include `findOccludedMeshes → removePrims` as the FIRST op in the + chain. Skip only pairs explicitly marked transparent. - [ ] **rule-reference.md** — map every fired validator to its backing op. - [ ] **operation-safety.md** — classify each mapped op as lossless or destructive. - [ ] **All destructive ops go into the plan.** They are presented for per-op diff --git a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/follow-up-queries.md b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-interpret-validators/references/follow-up-queries.md similarity index 82% rename from skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/follow-up-queries.md rename to skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-interpret-validators/references/follow-up-queries.md index 7297935c..48f69149 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/follow-up-queries.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-interpret-validators/references/follow-up-queries.md @@ -1,6 +1,3 @@ - - - # Validator Follow-Up Queries Use the parsed JSON in context. Don't re-run the validator unless asked. @@ -33,33 +30,35 @@ to filter to just failures, or omit `--limit` to get the full list. Look up the rule in the *Rule reference*. Then: 1. **T1** — Print the operation key and recommend running it. Example: - > `` wraps ``. To apply the fix, invoke the `so-run-operations` - > skill (Claude alias: `/so-run-operations --config '[{"operation":"", ...}]'`) + > `` wraps ``. To apply the fix, invoke the `usd-optimize-run-operations` + > skill (Claude alias: `/usd-optimize-run-operations --config '[{"operation":"", ...}]'`) > or call the operation directly via the Python bindings after probing the > selected SO API surface. For the full invocation reference (runtime probe, > chains via `executeConfig`, JSON pipelines via > `standalone.execute_commands_from_json`, and the required > `ExecutionContext` stage attachment), see - > `skills/omniverse-usd-performance-tuning/references/so-run-operations/references/invocation.md`. For output + > `skills/omniverse-usd-performance-tuning/references/usd-optimize-run-operations/references/invocation.md`. For output > Save-vs-Export policy and digitaltwin workspace rules, see > `skills/omniverse-usd-performance-tuning/references/usd-structure-assessment/references/usd-edit-target-planner/references/output-saving.md`. For > generic multi-op pipelines organized by bottleneck, see upstream - > `usd-optimize/.agents/operations/PIPELINES.md`. + > `usd-optimize/docs/choosing-operations.rst` (on 1.0.x packages + > `.agents/operations/PIPELINES.md`; resolution in + > `references/upstreams/usd-optimize.md`). - Read the relevant upstream `usd-optimize/.agents/operations/.md` guide - for starting params before printing them. Don't duplicate the guide content - here. + Read the relevant upstream `usd-optimize/docs/operations/.rst` guide (on + 1.0.x packages `.agents/operations/.md`) for starting params before + printing them. Don't duplicate the guide content here. 2. **T2** — Same as T1 but warn that defaults may not fully resolve the issue; the user should expect to tune parameters using the relevant upstream - `usd-optimize/.agents/operations/.md` guide. + `usd-optimize/docs/operations/.rst` guide. 3. **T3** — Explain that the rule is analysis-only (or the fix is a manual hierarchy/DCC edit). Point at the operation guide and any related fix-mode operations (e.g. `findOccludedMeshes` → use `removePrims` to remove the reported paths; `findFlatHierarchies` → use `flattenHierarchy`). -4. **Base rules** — Many wrap the same operation as a Scene Optimizer +4. **Base rules** — Many wrap the same operation as a Usd Optimize equivalent (see *Rule reference*). For stage-metadata or external-reference rules, suggest the user fix via USD Python API directly and reference the asset-validator suggestion text from the CSV `Suggestion` column. @@ -95,7 +94,7 @@ summarizer's `rules` array by `family == "base"` or `"SO"`). ### "Re-run validation" -Invoke the `so-run-validators` skill on the asset (asset mode only — refuse for +Invoke the `usd-optimize-run-validators` skill on the asset (asset mode only — refuse for direct CSV input since the original asset isn't known). After it finishes, re-run Steps 3 + 4. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/rule-reference.md b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-interpret-validators/references/rule-reference.md similarity index 86% rename from skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/rule-reference.md rename to skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-interpret-validators/references/rule-reference.md index bac1d46b..428dc9a4 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-interpret-validators/references/rule-reference.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-interpret-validators/references/rule-reference.md @@ -1,6 +1,3 @@ - - - # Validator Rule Reference This table maps a reported **validator signal** to its **canonical concept** @@ -18,17 +15,17 @@ closed on anything unknown or ambiguous. Never copy a runtime class name (e.g. `IndexedPrimvarChecker`) or a category (`Geometry`, `Usd:Performance`) into a scope note — class names are not unique across providers. -Scene Optimizer validator mechanics and operation docs live upstream in -[usd-optimize](https://github.com/NVIDIA-omniverse/usd-optimize/) and the -prebuilt Scene Optimizer package. Resolve guidance from an extracted package -root via `$SCENE_OPTIMIZER_PACKAGE_ROOT`, then `$SO_HOME`. If no package root -exists, download/extract the published `scene_optimizer_core_...release.zip` +Usd Optimize validator mechanics and operation docs live upstream in +[usd-optimize](https://github.com/NVIDIA-Omniverse/usd-optimize/) and the +prebuilt Usd Optimize package. Resolve guidance from an extracted package +root via `$USD_OPTIMIZE_ROOT`. If no package root +exists, download/extract the published the prebuilt Usd Optimize release package (current asset name + download: `references/upstreams/usd-optimize.md`) package (direct archive URLs are in `references/upstreams/usd-optimize.md`) or use the package path supplied by the user. To verify a rule's backing operation, inspect upstream `source/core/python/omni/scene/optimizer/validators/.py`. -### Scene Optimizer rules (default) +### Usd Optimize rules (default) | Validator signal | Canonical concept | Backing op | Notes | |------|------|-----------|-------| @@ -57,30 +54,30 @@ operation, inspect upstream | SceneOptimizerZeroAreaFacesChecker | `topology_zero_area_faces` | `meshCleanup` | Removes degenerate faces. | | SceneOptimizerZeroExtentChecker | `extents_zero` | `removeSmallGeometry` | Fix removes zero-extent meshes. Use `computeExtents` first when the cause is stale metadata. | -### Scene Optimizer rules (expensive — only present with `--include-expensive`) +### Usd Optimize rules (expensive — only present with `--include-expensive`) | Validator signal | Canonical concept | Backing op | Notes | |------|------|-----------|-------| -| SceneOptimizerOccludedMeshesChecker | `spatial_occluded` | `findOccludedMeshes` → `removePrims` | **Two-step detect→act.** Analysis identifies fully-occluded prim paths; feed those to `removePrims`. Runs first in the Phase 4 op chain. Scope to SA containment pairs with `enclosure_opaque: true`. Two-stage approval: (1) analysis cost, (2) deletion. | +| SceneOptimizerOccludedMeshesChecker | `spatial_occluded` | `findOccludedMeshes` → `removePrims` | **Two-step detect→act.** Analysis identifies fully-occluded prim paths; feed those to `removePrims`. Runs first in the Phase 4 op chain. Scope to SA `cross_component_pairs` that aren't explicitly transparent (`enclosure_opaque` true or unset; boundary pairs nominated via `candidate_source` hash OR semantics; bbox confirmation-only). Scoped probe runs without approval; only the removePrims deletion is intent-gated. | | SceneOptimizerFindOverlappingMeshesChecker | `spatial_overlapping` | `findOverlappingMeshes` | Analysis-only. Fix: review and remove/merge in DCC. | These expensive concepts are `gpu_bound` and Tier 3 in the registry; they must be scoped to flagged pairs (`paths=` / `OpenMasked`) and run in bounded subprocesses — never full-stage by default on large CAD/BIM/MEP assets. -### Asset Validator (OAV) base rules +### usd-validation-nvidia (OAV) base rules The full list lives in the upstream `omniverse-asset-validator` package; we mirror only the concepts that participate in the performance workflow. Many base -rules map onto a Scene Optimizer operation — surface the equivalent op so the +rules map onto a Usd Optimize operation — surface the equivalent op so the user has an automated fix path even when the rule itself is upstream. -**Geometry rules with SO operation equivalents:** +**Geometry rules with Usd Optimize operation equivalents:** | OAV base rule | Canonical concept | Backing op | Notes | |-----------|------|------------------|------| | `ExtentsChecker` | `extents_general` | `computeExtents` | Broader than SO `ZeroExtentChecker`. | -| `IndexedPrimvarChecker` | `primvar_indexability` (oav impl) | `optimizePrimvars` | **OAV variant is the slow full audit.** Registry tiers the OAV implementation higher than the SO triage one; the executor picks the SO impl for performance tuning. | +| `IndexedPrimvarChecker` | `primvar_indexability` (oav impl) | `optimizePrimvars` | **OAV variant is the slow full audit.** Registry tiers the OAV implementation higher than the Usd Optimize triage one; the executor picks the Usd Optimize impl for performance tuning. | | `WeldChecker` | `vertex_weld` | `meshCleanup` | Welds colocated verts. | | `NormalsValidChecker` | `normals_validity` | `generateNormals` | Targeted check only. | | `ZeroAreaFaceChecker` | `topology_zero_area_faces` | `meshCleanup` | — | @@ -99,7 +96,7 @@ user has an automated fix path even when the rule itself is upstream. | `MaterialPathChecker` | `material_path` | `info:mdl:sourceAsset` pointing at missing files. | | `NormalMapTextureChecker` | `texture_normalmap` | `UsdUVTexture inputs:file` unresolvable. | -For OAV-equivalent fixes, label the op as a Scene Optimizer operation (not the +For OAV-equivalent fixes, label the op as a Usd Optimize operation (not the validator's own `--fix` — this repo's validators don't ship a `--fix` mode). For any signal not in this list, treat it as a **manual fix** and surface the diff --git a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-run-validators/README.md b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-run-validators/README.md similarity index 56% rename from skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-run-validators/README.md rename to skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-run-validators/README.md index 48c5ee81..a093039e 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-run-validators/README.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-run-validators/README.md @@ -1,16 +1,13 @@ - - - -# so-run-validators - Local Validation Policy and Upstream Handoff +# usd-optimize-run-validators - Local Validation Policy and Upstream Handoff This local reference preserves the digitaltwin workflow milestone. Scene Optimizer mechanics for this step are owned by upstream `usd-optimize` and the -prebuilt Scene Optimizer package. +prebuilt Usd Optimize package. ## When to Use -Use when the digitaltwin workflow reaches the `so-run-validators` milestone or -when a user directly asks to run Scene Optimizer validators on a USD asset. +Use when the digitaltwin workflow reaches the `usd-optimize-run-validators` milestone or +when a user directly asks to run Usd Optimize validators on a USD asset. ## Instructions @@ -21,29 +18,28 @@ when a user directly asks to run Scene Optimizer validators on a USD asset. 3. Apply `runtime-artifact-token-budget.md`; never read full validator CSVs or full `run.log` into context. 4. Resolve the upstream validator runner from an extracted package root before - using web docs. Do not clone the source repo just to read SO validator + using web docs. Do not clone the source repo just to read Usd Optimize validator guidance. -5. Preserve logical milestone name `so-run-validators` and pass artifacts to - `so-interpret-validators`. +5. Preserve logical milestone name `usd-optimize-run-validators` and pass artifacts to + `usd-optimize-interpret-validators`. ## Output Format -Return a concise status or report that names the input asset, selected runtime, -artifacts written, blockers, and the next interpretation step. + +See `references/_shared/standard-output-format.md`. ## Upstream Source -- Public repository: [https://github.com/NVIDIA-omniverse/usd-optimize/](https://github.com/NVIDIA-omniverse/usd-optimize/) +- Public repository: [https://github.com/NVIDIA-Omniverse/usd-optimize/](https://github.com/NVIDIA-Omniverse/usd-optimize/) - Package path: `.agents/skills/run-validators/SKILL.md` -- Upstream web URL: [https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/skills/run-validators/SKILL.md](https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/skills/run-validators/SKILL.md) +- Upstream web URL: [https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/.agents/skills/run-validators/SKILL.md](https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/.agents/skills/run-validators/SKILL.md) Resolve the upstream guide without cloning the source repo: -1. `$SCENE_OPTIMIZER_PACKAGE_ROOT/.agents/skills/run-validators/SKILL.md` -2. `$SO_HOME/.agents/skills/run-validators/SKILL.md` +1. `$USD_OPTIMIZE_ROOT/.agents/skills/run-validators/SKILL.md` +2. `$USD_OPTIMIZE_ROOT/.agents/skills/run-validators/SKILL.md` -If no package root is available, download and extract the published -`scene_optimizer_core_...release.zip` package for the target platform, or use +If no package root is available, download and extract the prebuilt Usd Optimize release package (current asset name + download: `references/upstreams/usd-optimize.md`), or use the package archive path, direct archive URL, or extracted package root supplied by the user. Current public direct archive URLs are listed in `references/upstreams/usd-optimize.md`. If the user supplies an extracted @@ -58,4 +54,4 @@ reads. Do not clone the source repo just to read upstream SO guidance. - Validation scoping, selected validators, masked-stage spot-check policy, and expensive-check approval gates. - Runtime artifact token budget for CSV/log/summary handling. -- Digitaltwin milestone routing into `so-interpret-validators`. +- Digitaltwin milestone routing into `usd-optimize-interpret-validators`. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-run-validators/references/infrastructure.md b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-run-validators/references/infrastructure.md similarity index 56% rename from skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-run-validators/references/infrastructure.md rename to skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-run-validators/references/infrastructure.md index d61b5306..a2df5189 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/so-run-validators/references/infrastructure.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/usd-optimize-run-validators/references/infrastructure.md @@ -1,22 +1,18 @@ - - - -# Scene Optimizer Validator Infrastructure - Upstream Handoff +# Usd Optimize Validator Infrastructure - Upstream Handoff This local reference preserves the digitaltwin workflow milestone. Scene Optimizer mechanics for this step are owned by upstream `usd-optimize`. -- Public repository: [https://github.com/NVIDIA-omniverse/usd-optimize/](https://github.com/NVIDIA-omniverse/usd-optimize/) +- Public repository: [https://github.com/NVIDIA-Omniverse/usd-optimize/](https://github.com/NVIDIA-Omniverse/usd-optimize/) - Package path: `.agents/skills/validators/SKILL.md` -- Upstream web URL: [https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/skills/validators/SKILL.md](https://github.com/NVIDIA-omniverse/usd-optimize/blob/main/.agents/skills/validators/SKILL.md) +- Upstream web URL: [https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/.agents/skills/validators/SKILL.md](https://github.com/NVIDIA-Omniverse/usd-optimize/blob/main/.agents/skills/validators/SKILL.md) Resolve the upstream guide without cloning the source repo: -1. `$SCENE_OPTIMIZER_PACKAGE_ROOT/.agents/skills/validators/SKILL.md` -2. `$SO_HOME/.agents/skills/validators/SKILL.md` +1. `$USD_OPTIMIZE_ROOT/.agents/skills/validators/SKILL.md` +2. `$USD_OPTIMIZE_ROOT/.agents/skills/validators/SKILL.md` -If no package root is available, download and extract the published -`scene_optimizer_core_...release.zip` package for the target platform (direct +If no package root is available, download and extract the prebuilt Usd Optimize release package (current asset name + download: `references/upstreams/usd-optimize.md`) (direct archive URLs are in `references/upstreams/usd-optimize.md`), or use the package path/URL supplied by the user. If the user supplies an extracted package root directly, resolve this same package path under that root. If diff --git a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/validate-usd-asset-validator.md b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/validate-usd-validation-nvidia.md similarity index 82% rename from skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/validate-usd-asset-validator.md rename to skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/validate-usd-validation-nvidia.md index 15f843a6..1b238d7f 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/validate-usd-asset-validator.md +++ b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/validate-usd-validation-nvidia.md @@ -1,11 +1,8 @@ - - - -# Validate USD Asset Validator +# Validate USD usd-validation-nvidia ## Purpose -Run the selected NVIDIA Omniverse Asset Validator checks from the +Run the selected NVIDIA Omniverse usd-validation-nvidia checks from the `usd-validation-runner` scope note and summarize findings. This reference owns runtime invocation only; scoping, approval gates, full-sweep policy, masked spot-check policy, and large-stage thresholds live in @@ -30,15 +27,15 @@ spot-check policy, and large-stage thresholds live in explicit exhaustive approval. 5. Store raw outputs on disk and write a compact summary before reading results into context. -6. Feed summarized findings to `so-interpret-validators` and the optimization +6. Feed summarized findings to `usd-optimize-interpret-validators` and the optimization report. ## Runtime Selection | Runtime | Use | Notes | |---|---|---| -| Kit | Setup selected Kit, USD Composer, or a Kit venv; remote `omniverse://` validation; or same-runtime Scene Optimizer validation. | Import `omni.asset_validator.core` inside the selected Kit process. Do not require `uv` or `omni_asset_validate` on `PATH`. | -| Standalone | Setup selected a project-managed `omniverse-asset-validator` environment. | Use the selected Python/CLI. Do not use the Scene Optimizer package's bundled `validator-venv` as the preferred runtime. | +| Kit | Setup selected Kit, USD Composer, or a Kit venv; remote `omniverse://` validation; or same-runtime Usd Optimize validation. | Import `omni.asset_validator.core` inside the selected Kit process. Do not require `uv` or `omni_asset_validate` on `PATH`. | +| Standalone | Setup selected a project-managed `omniverse-asset-validator` environment. | Use the selected Python/CLI. Do not use the Usd Optimize package's bundled `validator-venv` as the preferred runtime. | Report `blocked_missing_dependency` only when setup cannot provide either runtime and the user did not approve installation or selection. @@ -47,7 +44,7 @@ runtime and the user did not approve installation or selection. `omni_asset_validate --help` may be used to confirm a runtime exists. Do **not** use the CLI to select which validators run: CLI `--rule` flags take bare names, -which cannot disambiguate the Scene Optimizer and Asset Validator rules that +which cannot disambiguate the Usd Optimize and usd-validation-nvidia rules that share a class name. Concept selection and execution always go through the canonical executor (`scripts/usd_validation_executor.py`), which resolves by identity. Prefer CSV when JSON output is not advertised by the selected runtime. @@ -82,7 +79,7 @@ relationship closure paths when material rules are selected, and verify the masked stage still exposes relevant mesh-bearing content. Do not rely on `LoadNone` as the validator scoping mechanism. See -`../README.md` → `Asset Validator Load Rules`. +`../README.md` → `usd-validation-nvidia Load Rules`. ## Output Report @@ -106,9 +103,9 @@ command failures. ## Limitations - CLI flags and Python APIs vary by installed runtime/version. -- This reference reports Asset Validator findings only; it does not apply +- This reference reports usd-validation-nvidia findings only; it does not apply `--fix` or repair USD content unless the user explicitly asks for auto-repair. -- Scene Optimizer performance validators run through `so-run-validators` when +- Usd Optimize performance validators run through `usd-optimize-run-validators` when setup verifies `omni.scene.optimizer.core`. - Spot checks are optimization evidence, not formal full conformance coverage. @@ -121,5 +118,5 @@ command failures. ## Next Steps -Pass compact findings to `so-interpret-validators`. Revalidate same-or-narrower +Pass compact findings to `usd-optimize-interpret-validators`. Revalidate same-or-narrower after mutation unless the user approves expansion. diff --git a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/validator-concepts.json b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/validator-concepts.json index 3817c7cb..4d78690c 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/validator-concepts.json +++ b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/references/validator-concepts.json @@ -1,6 +1,6 @@ { "schema_version": "1.0.0", - "$comment": "Canonical validator-concept registry for the USD performance-tuning workflow. Single binding layer between agent-facing concept names and runtime rule identity, tier, scope policy, and backing op. Curated by maintainers, not inferred. Resolution key is (module, class_name); category is informational. Tiers/costs are CPU-only worst-case from gb300_03 evidence (batch-additivity-findings.md); gpu_bound concepts relax on CUDA hosts. Governed by validator-concepts.schema.json (added in PR-2).", + "$comment": "Canonical validator-concept registry for the USD performance-tuning workflow. Single binding layer between agent-facing concept names and runtime rule identity, tier, scope policy, and backing op. Curated by maintainers, not inferred. Resolution key is (module, class_name); category is informational. Tiers/costs are CPU-only worst-case from large-asset evidence (batch-additivity-findings.md); gpu_bound concepts relax on CUDA hosts. Governed by validator-concepts.schema.json.", "concepts": [ { "canonical_name": "primvar_indexability", @@ -241,7 +241,7 @@ "use_for": ["performance_tuning"] } ], - "notes": "2.5 s on gb300 (hash short-circuit) but can be minutes with many similar meshes. Treat as Tier 3 default; promote to Tier 2 only after measuring on target stage." + "notes": "A few seconds on a large reference stage (hash short-circuit) but can be minutes with many similar meshes. Treat as Tier 3 default; promote to Tier 2 only after measuring on target stage." }, { "canonical_name": "geom_duplicates_fuzzy", @@ -360,7 +360,7 @@ "use_for": ["performance_tuning"] } ], - "notes": "~94 s on gb300 — slowest Tier 1. Counts meshes through composition." + "notes": "Around a minute and a half on a large reference stage — slowest Tier 1. Counts meshes through composition." }, { "canonical_name": "perf_small_mesh", @@ -516,7 +516,7 @@ "use_for": ["performance_tuning"] } ], - "notes": "Two-step detect->act: feed occluded paths to removePrims. Scope to SA containment pairs with enclosure_opaque:true. 485 s full-stage on CPU; scope via paths=. Two-stage approval (analysis cost, then deletion)." + "notes": "Two-step detect->act: feed occluded paths to removePrims. Scope to SA validation_scope.cross_component_pairs that aren't explicitly transparent (enclosure_opaque true or unset; boundary pairs nominated via candidate_source hash OR semantics; bbox confirmation-only, not a first-step containment sweep). 485 s full-stage on CPU; scope via paths=. Scoped probe runs without approval; only the removePrims deletion is intent-gated." }, { "canonical_name": "spatial_overlapping", diff --git a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/scripts/usd_validation_executor.py b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/scripts/usd_validation_executor.py index e50bbfe4..3fc28a7a 100644 --- a/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/scripts/usd_validation_executor.py +++ b/skills/omniverse-usd-performance-tuning/references/usd-validation-runner/scripts/usd_validation_executor.py @@ -9,7 +9,7 @@ Why this exists --------------- Bare rule names are not unique. ``IndexedPrimvarChecker`` is registered by both -Scene Optimizer (0.3 s triage) and the Asset Validator (376 s full audit). A +Usd Optimize (0.3 s triage) and the usd-validation-nvidia (376 s full audit). A name-only lookup picks one by registry order, so the same scope note produces different work and wildly different runtimes on different hosts. That is the root cause of "every run finds a different solution and it takes forever." @@ -193,6 +193,52 @@ def get_validation_engine_cls() -> Any: raise ValidationRuntimeUnavailable(_RUNTIME_UNAVAILABLE) from exc +def _shape_registered_rules(reg: Any) -> Any: + """Kit core ``ValidationRulesRegistry`` shape (iterable or callable).""" + try: + registered = reg.registered_rules + except AttributeError: + return None + return registered() if callable(registered) else registered + + +def _shape_rules_by_name(reg: Any) -> Any: + """Older ``name -> rule`` map shape; yields the map's values.""" + try: + mapping = reg.rules_by_name + except AttributeError: + return None + return mapping.values() if isinstance(mapping, dict) else None + + +def _shape_rules(reg: Any) -> Any: + """OAV 1.18.0 ``CategoryRuleRegistry.rules`` shape (iterable/dict/callable).""" + try: + direct = reg.rules + except AttributeError: + return None + if callable(direct): + direct = direct() + if isinstance(direct, dict): + direct = direct.values() + return direct + + +#: Allowlist of the only registry entry points the enumerator may consult, each +#: mapped to an accessor that normalizes that runtime's shape to an iterable of +#: rule objects. Using an explicit static mapping (instead of dynamic +#: ``getattr``) guarantees no externally-influenced name can select an +#: attribute — only these three known, hand-vetted registry shapes are ever +#: read, and each accessor uses direct attribute access. This is a runtime +#: adapter, not a correctness fallback: extend it only with a new entry point +#: that yields rule classes carrying real ``__module__`` / ``__name__`` identity. +_REGISTRY_SHAPE_ACCESSORS: dict[str, Callable[[Any], Any]] = { + "registered_rules": _shape_registered_rules, + "rules_by_name": _shape_rules_by_name, + "rules": _shape_rules, +} + + def iter_registered_rules(rule_registry: Any) -> Iterable[type]: """Yield every registered rule *class* (collision-aware enumeration). @@ -200,33 +246,20 @@ def iter_registered_rules(rule_registry: Any) -> Iterable[type]: to the differing registry shapes across runtimes but never collapses rules to bare names. Fail-closed: if no enumeration entry point is found, raises. """ - # Scene Optimizer registers its rules on import for discovery. + # Usd Optimize registers its rules on import for discovery. try: import omni.scene.optimizer.validators # type: ignore # noqa: F401 except ImportError: # pragma: no cover - environment dependent pass - # Known registry shapes, probed by entry point (never collapsed to bare - # names — matching stays identity-based below): - # - ``registered_rules`` Kit core ValidationRulesRegistry (iterable/callable) - # - ``rules_by_name`` older name->rule map - # - ``rules`` OAV 1.18.0 CategoryRuleRegistry (iterable of classes) - # This is a runtime adapter, not a correctness fallback. Extend here only if - # a new runtime exposes another shape, and only with an entry point that - # yields rule classes carrying real ``__module__`` / ``__name__`` identity. - rules = getattr(rule_registry, "registered_rules", None) - if callable(rules): - rules = rules() - if rules is None: - mapping = getattr(rule_registry, "rules_by_name", None) - rules = mapping.values() if isinstance(mapping, dict) else None - if rules is None: - direct = getattr(rule_registry, "rules", None) - if callable(direct): - direct = direct() - if isinstance(direct, dict): - direct = direct.values() - rules = direct + # Probe the known registry shapes in order via the explicit allowlist above; + # the first accessor to yield a non-None result wins. Matching stays + # identity-based below (never collapsed to bare names). + rules = None + for accessor in _REGISTRY_SHAPE_ACCESSORS.values(): + rules = accessor(rule_registry) + if rules is not None: + break if rules is None: raise ValidationRuntimeUnavailable( "Could not enumerate registered rules from the runtime registry; the " @@ -234,7 +267,10 @@ def iter_registered_rules(rule_registry: Any) -> Iterable[type]: ) for rule in rules: - rule_cls = getattr(rule, "rule", rule) # unwrap registration wrappers + try: + rule_cls = rule.rule # unwrap registration wrappers + except AttributeError: + rule_cls = rule if isinstance(rule_cls, type): yield rule_cls @@ -271,7 +307,7 @@ def open_scoped_stage(stage_path: str, mask_paths: list[str] | None = None) -> A """Open a stage, optionally masked to ``mask_paths`` (+ the default prim). ``Usd.Stage.OpenMasked()`` is the only reliable scoping mechanism for the - Asset Validator (it discards caller ``StageLoadRules`` but preserves the + usd-validation-nvidia (it discards caller ``StageLoadRules`` but preserves the population mask). Rejects an empty masked sample so the caller never reports a misleading "0 findings". """ @@ -513,11 +549,24 @@ def subprocess_concept_runner( import os import sys + # Pin the child command so neither the interpreter nor the script can be + # redirected by external (job) input. The interpreter defaults to the + # current ``sys.executable``; the worker is *always* this executor module's + # own resolved path — it never derives from the job payload. Validate both + # up front so ``[executable, worker]`` passed to ``subprocess.run`` is a + # fixed, vetted command. executable = python_executable or sys.executable - worker = str(Path(__file__).resolve()) + if not isinstance(executable, str) or not executable: + raise ValueError("python_executable must be a non-empty path string") + # The worker is always this executor module's own resolved path; it is never + # job-derived, so the command stays fixed regardless of stdin input. + worker_path = Path(__file__).resolve() + if not worker_path.is_file(): # pragma: no cover - defensive + raise RuntimeError(f"validation worker path does not resolve to a file: {worker_path}") + worker = str(worker_path) def _runner(stage_path, concepts, *, registry=None, mask_paths=None): - job = json.dumps( + request_payload = json.dumps( { "stage_path": stage_path, "concept": concepts[0], @@ -531,7 +580,7 @@ def _runner(stage_path, concepts, *, registry=None, mask_paths=None): ) completed = subprocess.run( [executable, worker], - input=job, + input=request_payload, capture_output=True, text=True, timeout=timeout_seconds, @@ -550,6 +599,54 @@ def _runner(stage_path, concepts, *, registry=None, mask_paths=None): return _runner +#: The exact set of fields the internal worker job may carry. The stdin payload +#: is an internal protocol, but the input is still untrusted, so ``_validate_job`` +#: rejects anything outside this schema before any value is used. +_JOB_ALLOWED_KEYS = frozenset({"stage_path", "concept", "mask_paths", "registry_path"}) + + +def _validate_job(job: Any) -> dict[str, Any]: + """Validate/normalize the untrusted stdin job against the worker schema. + + Fail-closed on shape, unexpected/missing fields, and wrong types. Returns a + normalized dict with exactly the four known keys so the caller can index it + directly. This is the trust boundary for the child process (the job arrives + as JSON on stdin from ``subprocess_concept_runner``). + """ + if not isinstance(job, dict): + raise ValueError(f"job must be a JSON object, got {type(job).__name__}") + unexpected = set(job) - _JOB_ALLOWED_KEYS + if unexpected: + raise ValueError(f"job has unexpected field(s): {sorted(unexpected)}") + + stage_path = job.get("stage_path") + if not isinstance(stage_path, str) or not stage_path: + raise ValueError("job['stage_path'] must be a non-empty string") + + concept = job.get("concept") + if not isinstance(concept, str) or not concept: + raise ValueError("job['concept'] must be a non-empty string") + + mask_paths = job.get("mask_paths", []) + if mask_paths is None: + mask_paths = [] + if not isinstance(mask_paths, list) or not all( + isinstance(p, str) and p for p in mask_paths + ): + raise ValueError("job['mask_paths'] must be a list of non-empty strings") + + registry_path = job.get("registry_path") + if registry_path is not None and (not isinstance(registry_path, str) or not registry_path): + raise ValueError("job['registry_path'] must be a non-empty string or null") + + return { + "stage_path": stage_path, + "concept": concept, + "mask_paths": mask_paths, + "registry_path": registry_path, + } + + def _worker_main() -> int: """Child entrypoint: read one JSON job from stdin, print a JSON result. @@ -557,14 +654,14 @@ def _worker_main() -> int: """ import sys - job = json.loads(sys.stdin.read()) - registry = load_registry(job.get("registry_path")) + job = _validate_job(json.loads(sys.stdin.read())) + registry = load_registry(job["registry_path"]) try: issues = validate_concepts( job["stage_path"], [job["concept"]], registry=registry, - mask_paths=job.get("mask_paths") or None, + mask_paths=job["mask_paths"] or None, ) except ValidationRuntimeUnavailable as exc: print(json.dumps({"status": "blocked_validation_runtime", "detail": str(exc)})) diff --git a/skills/omniverse-usd-performance-tuning/references/workflow.md b/skills/omniverse-usd-performance-tuning/references/workflow.md index 0cc0a47f..3a90227a 100644 --- a/skills/omniverse-usd-performance-tuning/references/workflow.md +++ b/skills/omniverse-usd-performance-tuning/references/workflow.md @@ -1,6 +1,3 @@ - - - # USD Performance Tuning Workflow > Canonical phase choreography for the `omniverse-usd-performance-tuning` @@ -32,11 +29,13 @@ Seven in-flow phases (0-6) plus Phase 7. For broad "optimize this scene" requests, Phase 7 defaults to 3 scoped iterations unless the user opts out, asks for a quick pass, or stop criteria apply. + For structured milestone lists, preserve this broad-optimization subsequence: `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` -> +`restructure-decision` -> `apply-restructure` -> `usd-optimize-run-validators` -> +`usd-optimize-interpret-validators` -> `usd-optimize-run-operations` -> `profile-stage:after` -> `compare-profiles` -> `optimization-report`. Additional analysis skills may appear between these milestones only when they do not reorder the subsequence. @@ -52,8 +51,6 @@ flowchart TD P6["Phase 6 Verify and report"] P7["Phase 7 Default scoped iteration"] P0 --> P1 --> P2 - P2 -->|"already_optimized"| P6 - P2 -->|"exit"| P6 P2 -->|"optimize-as-is"| P3 P2 -->|"extract-as-assets / decompose"| P3 P3 --> P4 --> P5 --> P6 @@ -70,9 +67,10 @@ Do not duplicate the setup chooser here. Phase 0 means: - Run the mandatory session-start gate from `setup-usd-performance-tuning/references/runtime-context-header.md`. -- If preflight is missing or the user changes runtime, invoke - `setup-usd-performance-tuning`. That skill owns Kit vs standalone choice, - install dispatch, version capture, and `setup-preflight.json`. +- If preflight is missing, invoke `setup-usd-performance-tuning`. That skill owns + standalone setup (the sole optimize+validate runtime), version capture, and + `setup-preflight.json`. Kit is not an alternate optimization runtime; it is + retained only as an explicit opt-in render-profiling adjunct (Kit->omniperf). - If the target is `omniverse://`, invoke `omniverse-authentication` before the first remote probe, open, validation, profile, or operation. - Hand the resulting `runtime_context` and `operationsAvailable` list to later @@ -80,26 +78,29 @@ Do not duplicate the setup chooser here. Phase 0 means: Phase 0 must complete before any other phase. The runtime choice changes how Phases 1a (profiling), 2c (validator commands), and 4 (op execution) execute. Other phases are runtime-agnostic. -#### SO unavailable outcomes +#### Usd Optimize unavailable outcomes -If the user explicitly asked to run Scene Optimizer operations and the selected -runtime cannot load Scene Optimizer, stop with `blocked_missing_scene_optimizer`. -If Scene Optimizer is present but a requested op key is absent from -`operationsAvailable`, stop with `blocked_missing_so_operation`. Do not silently -substitute structural-only work for a direct SO execution request. +If the standalone runtime cannot load Usd Optimize when the optimization +pipeline needs it, stop with `blocked_missing_usd_optimize`. If Scene +Optimizer is present but a pipeline step needs an op key absent from +`operationsAvailable`, stop with `blocked_missing_usd_optimize_operation` (the in-pipeline +op-availability cross-check — not a direct-op bypass). Do not silently substitute +a degraded path for an optimization request that requires Usd Optimize. -For broad optimization requests, if setup finds Kit without the SO extension or -standalone Python without a loadable SO library, and the user declines install -dispatch, the flow may continue in structural-only mode: +For broad optimization requests, if the standalone runtime has no loadable SO +library and the user declines install dispatch, the flow may continue in the +runtime-forced `structural_only` degraded mode (this is an honest runtime block +reported via `workflow_mode`, not a user-chosen bypass of the evidence/coverage +gates): - Phase 1 runs as normal (SA + profile-stage quick-or-full). - Phase 2a/2b/2d run as normal. -- Phase 2c runs the **pre-mutation USD stack only** (no SO perf rules - they require SO). -- Phase 2e: `restructure-decision` may still ask. `apply-restructure` needs a USD Python runtime for the hierarchy rewrite path. If USD Python is unavailable, `extract-as-assets` and `decompose-for-selective-loading` are effectively unavailable — offer `deduplicate-internally`, `optimize-as-is`, or `exit` instead. +- Phase 2c runs the **pre-mutation USD stack only** (no Usd Optimize perf rules - they require Usd Optimize). +- Phase 2e: `restructure-decision` may still ask. `apply-restructure` needs a USD Python runtime for the hierarchy rewrite path. - **Phase 3 still works** (instancing-readiness is pure USD); flips can be authored. -- **Phase 4 SKIPPED** (mesh ops require SO). +- **Phase 4 SKIPPED** (mesh ops require Usd Optimize). - **Phase 5 SKIPPED** (no optimized children to remap). -- Phase 6: `profile-stage` AFTER + `usd-validation-runner` re-validation (pre-mutation USD stack only) + `optimization-report` with `workflow_mode: structural_only` (the `verdict` stays in its enum — `neutral` if no metrics changed) and a `notes` entry explaining that SO operations did not run. +- Phase 6: `profile-stage` AFTER + `usd-validation-runner` re-validation (pre-mutation USD stack only) + `optimization-report` with `workflow_mode: structural_only` (the `verdict` stays in its enum — `neutral` if no metrics changed) and a `notes` entry explaining that Usd Optimize operations did not run. This is the path E2E test scenarios commonly hit. @@ -109,19 +110,24 @@ Owner: `profile-stage` (1a) + `usd-structure-assessment` (1b). Both run; **order ``` 1a profile-stage:baseline (runtime metrics) - Kit: full mode - stage open time, VRAM, FPS, frame time (Tracy-backed) - standalone: quick mode - stage open time only (no FPS, no VRAM) + standalone (default): quick mode - stage open time only (no FPS, no VRAM) + opt-in Kit->omniperf profiling adjunct: full mode - VRAM, FPS, frame time + (Tracy-backed), only when the user explicitly requests render-time + profiling. Standalone is the sole optimize+validate runtime; Kit is a + profiling adjunct, never an optimization path (see Phase 0). 1b usd-structure-assessment (structural analysis - one umbrella) Same skill body in both runtimes. Produces ~25 facts including prim/mesh/material counts + phase_recommendation (structuring | optimization | already_optimized) + validation_scope + asset_boundary_suggestions + asset_physical_context. - In Kit, the agent may augment with SO analysis ops (printStats, etc. + In Kit, the agent may augment with Usd Optimize analysis ops (printStats, etc. from references/operations/README.md) for finer-grained stats - this is not a separate phase step. ``` +Structural analysis (SA, hierarchy hashing, and boundary/occlusion nomination) runs on a fully-loaded, fully-composed stage (all payloads loaded) so an enclosed sub-assembly behind a payload is visible rather than silently reading as empty. + Populate the baseline portion of `optimization-report/references/optimization-report-template.md` from 1a + 1b before moving on. When returning structured plans or runtime-test milestone lists, label this phase exactly `profile-stage:baseline`. ### Phase 2 - Composition, discovery, and restructure decision @@ -133,32 +139,61 @@ Five steps (2a-2d) feeding the gate at 2e, plus optional 2f if the user chooses Classify: monolithic-needs-restructure | monolithic-fine-as-is | composed-and-how Identify explicit prototypes/scopes that can be targeted separately. -2b Asset boundary inference (USE: usd-hierarchy-dedupe-candidates + SA §2.7) +2b Asset boundary inference (USE: usd-hierarchy-dedupe-candidates + SA §2.5) Run hierarchy hashing for monolithic stages. Output is double-purpose: - Where to draw asset boundaries if we restructure - Stage-level instancing effectiveness signal SA's asset_boundary_suggestions field already promotes hash-aligned cut points. -2c Phase-aware validation scope + selected probes (USE: usd-validation-runner) +2c Whole-stage validation that informs the restructure decision (USE: usd-validation-runner) Read `usd-validation-runner/README.md` before writing or running - validator code. The runner first builds a selected validation plan from - SA's summary_counts, phase_recommendation, validation_scope, and - flagged_assets; then it runs only the selected rules/probes. + validator code. At 2c the runner runs only **Tier 1** (cheap whole-stage + stats/probes) plus the minimum-openability/structural checks needed to + classify the stage and feed the 2e gate — built from SA's summary_counts, + phase_recommendation, and validation_scope. + Per-target **Tier 2/3** validation does NOT run here: those validators + belong on the post-restructure artifacts (prototypes, sub-assets, residual + assembly root) and run inside the Phase 4 per-target loop, where their + scope is one target/pair by construction. (A pre-restructure Tier 2/3 + diagnosis is available only on explicit user request.) Validators are named by canonical concept (validator-concepts.json) and executed via scripts/usd_validation_executor.py — never by bare class - name or a hand-written script. A flagged Tier 3 target's scoped probe is - mandatory (no approval); only the full-stage version is approval-gated. + name or a hand-written script. Output: a compact scope note/artifact (validation-scope-note.schema.json) - plus a findings corpus that informs 2e and Phase 4 op selection. The - validation-report's coverage_ledger must be complete (every flagged - target resolved) before advancing. + plus the Tier 1 findings corpus that informs 2e. (Tier 2/3 findings and + their coverage_ledger are produced per target in Phase 4.) Large-stage guardrail: if resolved stage size is unknown or >100 MB, composed prim count is >10,000, mesh/prototype count is high, the target is customer-scale CAD/BIM/MEP/factory/plant/city, or the ask is performance optimization rather than formal conformance, do not run a - default full-stage AV/SO sweep. Ask before full sweep. + default full-stage usd-validation-nvidia / Usd Optimize sweep. Ask before full sweep. + + Correctness precondition: include the selected `safety_gate` + concepts with `backing_op: null` (dangling material bindings — including + bindings whose target path sits under a stale/renamed root — missing + refs, kind metadata; registry names: `material_dangling_binding`, + `composition_missing_ref`, `kind_metadata`) in the 2c scope note and run them + here, whole-stage. These are not report-only findings: a correctness + defect POISONS the optimization evidence (observed on a large + data-center assembly asset, where a high volume of dangling bindings made + `material_duplicates` falsely return 0), so an + unresolved safety-gate finding BLOCKS Phase-2e interpretation of the + structural/material evidence until it is waived or repaired. Repair (when + chosen) is one whole-stage bespoke USD-authoring rebind via the + open-reasoning mode (Sdf/pxr, owned by `apply-restructure` — not an SO + op), authored BEFORE structuring so the defect is never replicated into + prototypes/instances; it is intent-gated (surfaced with trigger + + hypothesis, applied on confirmation, written to a new file, source + untouched — detection != mandatory repair). Re-verify the same concepts + after structuring on each externalized node (restructure can introduce + new dangling bindings). This detection sweep is mandatory-early but still + cost-bounded: it does NOT inherit Tier-1's no-timeout exemption — run it + in a killable subprocess under a wall-clock budget, and above the + large-stage threshold degrade to a masked spot-check (>=25% mesh-bearing + coverage) rather than a full traversal, recording a `sampled` / + `timeout_recorded` disposition. 2d Stage-level instancing assessment (USE: dedupe-candidates output from 2b) For composed stages: are existing references actually instanceable? @@ -169,33 +204,207 @@ Five steps (2a-2d) feeding the gate at 2e, plus optional 2f if the user chooses Owner: restructure-decision Inputs: SA classification (2a), boundary signal (2b), validator findings (2c), instancing assessment (2d). - Branches: + Branches (the gate chooses HOW to optimize, never whether to — every + branch proceeds into the optimization pipeline; there is no + no-optimize/diagnose-and-exit choice): - monolithic & restructure recommended & dedupe candidates -> ASK USER: - deduplicate-internally (SO deduplicateHierarchies) - / extract-as-assets (apply-restructure external prototypes) - / optimize-as-is / exit + deduplicate-internally (apply-restructure internal_reference: + direct value-hash nested-library authoring) + / extract-as-assets (apply-restructure external_prototype) + / optimize-as-is - monolithic & restructure recommended & no dedupe -> ASK USER: - decompose-for-selective-loading | optimize-as-is | exit + decompose-for-selective-loading | optimize-as-is - monolithic & fine as-is -> continue (no restructure) - monolithic & fine as-is + payload_count=0 + clear boundaries -> ASK USER: - decompose-for-selective-loading / optimize-as-is / exit + decompose-for-selective-loading / optimize-as-is - composed -> continue (assess existing instancing per Phase 3) - - already_optimized -> jump to Phase 6 verify + - already_optimized -> continue (Phase 3-5 find no + work; report workflow_mode: + no_op, verdict: neutral) -2f If extract-as-assets or decompose-for-selective-loading chosen +2f If extract-as-assets, deduplicate-internally, or decompose-for-selective-loading (USE: apply-restructure mode=restructure) - Orchestrates USD-authored hierarchy rewrite + asset-boundary - materialization (writes prototype USDs to disk, rewrites refs to point - at them). Backend: pxr/Sdf Python. See usd-structure-assessment/references/apply-restructure/README.md - Workflow - mode=restructure. + Orchestrates the USD-authored hierarchy rewrite (pxr/Sdf Python). See + usd-structure-assessment/references/apply-restructure/README.md + Workflow - mode=restructure. The chosen branch sets `dedupe.mode`: + - extract-as-assets / decompose-for-selective-loading → + `external_prototype`: materialize one prototype USD per group to disk + and rewrite refs (payloaded, independently loadable). + - deduplicate-internally → `internal_reference`: author internal shared + prototypes DIRECTLY via the value-hash nested-library rewrite (internal + refs marked instanceable=true); the stage stays a single monolithic + file (no external payloads). + Both branches route through apply-restructure, a direct USD-authored + rewrite. The native `deduplicateHierarchies` op is the per-region + authoring primitive for the instanceable-reference collapse: one + invocation per frontier region, with `paths` scoped to that region and + `maxDepth` chosen per region at the 2g per-level confirm. Never apply one + stage-wide depth (the operations catalog entry and issue #168 carry the + measured depth→grain and placement data). On usd-optimize 1.0.4 the op + authors nested instanceable internal references (verified 2026-06-11: a + 222,513-prim CAD stage collapsed to 21,030 composed prims / 2,663 + prototypes in 46 s, default args), but it emits no restructure-role + manifest, frontier/identity gating, or `kept_inline_for_merge` tagging, + which this phase's contract requires. So Phase 2f drives it through + apply-restructure, whose per-level driver calls the op per descent region + and emits the manifest. Passing `paths` + `maxDepth` to + `deduplicateHierarchies` directly with no manifest is for standalone + approved-chain dedup runs outside this pipeline + (usd-optimize-run-operations), not Phase 2f. See + restructure-decision/README.md "When hierarchy_dedupe.recommended=true". Output: restructured stage ready for Phase 3. - If deduplicate-internally chosen → skip Phase 2f. Stage stays monolithic. - Phase 4 includes SO deduplicateHierarchies in the op chain. +2g CONVERGENCE GATE (confirm per level; converge before Phase 4). + Work in passes, biggest repeated pieces first (think nesting dolls). + A rack holds many near-identical blades; each blade holds many shared + parts. Instance the rack's blades first; THEN look inside the blades and + instance the parts they share — even across blades that were not themselves + identical. Each pass goes one level deeper. A low count after the first pass + is the SIGNAL TO GO DEEPER, not the finish line — and NOT a reason to merge: + merging now fuses geometry the next pass would have shared. + + Run it per level, top-down: + 1. Choose the level to share at — the coarsest named / `kind` unit, + never an individual mesh. Preflight the `kind` label before trusting + it as the stop level: confirm kind actually bounds multi-mesh parts + (the finder samples meshes-per-kind stage-wide). On CAD imports + components often sit at ~1-mesh grain — then `kind` is not a real + boundary; re-derive the stop level structurally (nearest multi-mesh + parent / sibling name-base group; the finder flags `kind_untrusted` + and falls to `structural_fallback`). Only go down to a moving subpart for + IMPORTANT ones (articulated / physics / variant-bearing); for + articulated assets, share at the moving-part (rigid-body / link) + level and reassemble with references — never instance the whole + asset (factory guide Step 4). + 2. Author that level's shared prototypes (`instanceable=true` + references — see SHARE, DON'T SCATTER below). Tag each target in the + manifest `phase4_targets[]` with its level (assembly / component / + subcomponent = USD `kind`) and its asset type (architecture / product + / piping / generic — this picks which geometry ops apply later). + 3. Re-scan one level down (the quick structure-only pass) and SHOW the + user the new repeated groups it finds that are worth sharing (roughly + 20+ prims, appearing 2+ times), with the cost (more layers, parts + less directly selectable). ASK: go deeper, or stop? Always ask before + crossing a named-part boundary or doing anything that destroys + identity (point-instancing / merging). A plain lossless-sharing tail + can be auto-finished if the user opts in. + 4. STOP when the user says stop, or when that re-scan finds nothing new + worth sharing (only leftovers remain: tiny parts left in place for a + later merge, already-split variants, or one-offs). + + DONE = the loop above finished. Record it in the manifest's `frontier` + block: `descent_converged: true` and `final_rescan_new_groups_above_floor: 0`. + Do NOT start Phase 4 geometry ops (decimation, within-prototype merge) + until then. Reducing an unfinished structure wastes work on geometry that + more sharing would have removed; merging before those tiny leftover parts + are reserved fuses geometry that was about to be shared, so triangles and + disk GROW instead of shrink and the Phase 6 gate rejects the result. + + Don't over-split: each pass adds layers, so how deep you go caps the layer + COUNT. Exploding a factory asset into five-figure layer counts is a + failure, even with packaging deferred. + + SHARE, DON'T SCATTER (hard rule): externalizing MUST use shared prototypes + with `instanceable=true` references — NOT N separate per-node payloads + presented as the win. Separate payloads are valid only when the goal is + selective loading / authoring separation, and then the report must call out + the load-time / layer-count tradeoff instead of presenting the split as the + optimization. A USDC repack or an unshared split is NOT a win — the Phase 6 + gate fails closed on it (see footprint contract + optimization-report). + Depth caps layer count; sharing caps load time and memory. ``` +#### The structure model the descent is serving (read before deciding a frontier) + +The descent's job is not "make the number smaller." It is to land an asset whose +**named parts stay findable, selectable, and serviceable**, with zero broken +bindings — the cleanest structure a careful USD author would recognize, not the +smallest prim count. Five ideas govern every boundary call; they are the decision +context behind the mechanical rules above. + +1. **Three axes move independently — never conflate them.** *Correctness* (same + geometry present, materials bind, bounds intact) is non-negotiable and gates + first. *Scene-graph weight* (prims to compose / walk) is what sharing reduces — + a runtime/memory win. *Disk size* is mostly distinct geometry + primvar bytes. + The trap: collapsing duplicates into instances makes the scene graph lighter but + frees **~no disk**, because the crate already byte-dedupes identical arrays + within a layer (OpenUSD content-reuse guidance: *"a USD file with 1000 identical + meshes might only be marginally larger than a file with a single copy"*). So a + drop in *summed* points/prims across the stage is a **reuse** result, not a + geometry or disk result — report it as scene-graph, never as a disk win. What + *does* move disk is changing stored bytes: removing genuinely-unused data (an + unused UV set is often the single largest lever), primvar indexing, layer + consolidation, and lossy reduction. A lossless disk win is **not** suspect; + silent loss is caught by the preservation gate, not by the disk number. + +2. **Find boundaries by identity first; let reuse only confirm.** Recover the real + units in priority order — authored `kind` (`assembly`→`group`→`component`→ + `subcomponent`), then meaningful naming (`assetInfo` / display name / variant + set; `Mesh_017` or a bare transform `Xform` is plumbing), then semantic + real-world recognizability (does a domain expert name this as one serviced / + catalogued / swapped piece?). Only then hierarchy-hash the **already-meaningful** + candidates to learn which repeat and how exactly. Hashing **confirms reuse; it + does not define the grain.** Letting the hash choose the grain is exactly the + failure that over-shares at the mesh level and dissolves every part's identity. + Where authored identity is entirely absent, structure may *propose* the + **coarsest repeating subtree** as a fallback grain (flag `grain_source = + structural_fallback`) — still never the individual mesh. Identity-first also + means *validating* the signal: authored `kind` is DEMOTED to that same + structural fallback — not only when absent — when it fails the meshes-per-kind + kind-trust check (~1 mesh per component, the CAD-exporter tagging artifact); + an unreliable label is treated exactly like a missing one, and the demotion + is flagged `kind_untrusted` so it stays auditable. + +3. **Share at the coarsest unit that captures the reuse — the named subcomponent, + never the mesh.** Mesh-level sharing produces enormous anonymous arc counts + (orders of magnitude more arcs than sharing at the subcomponent level, for + comparable prim reduction) and throws away addressability. Reuse recovery may then justify descending to finer + *named* subcomponents (the variant-outlier and unique-container cases), but never + into meshes. + +4. **Author nested, not flat.** Define small parts once; have parent prototypes + **reference** child prototypes rather than inlining copies. Flat/outermost + extraction just moves the duplication into the new files and makes the package + *bigger*; a bottom-up nested library is what keeps the multi-file premium + recoverable. + +5. **Repair correctness first, and read the structure you already have.** Fix + content defects (dangling bindings) before structuring — instancing a broken + part replicates the breakage, and a defect *poisons the optimization evidence* + (a stale-root rebind can flip a falsely-`0` `material_duplicates`). And many + inputs arrive *already partway down* the hierarchy (already-instanced or BIM/CAD + exports with authored prototypes and `kind`): **resume the descent from the level + the asset is already at**, treat existing prototypes as the candidate set there + (collapsing byte-identical-but-separately-authored prototypes), and **measure the + remaining reuse before promising any consolidation win**. When measured reuse is + low (parametric MEP-style geometry where each run differs), the value pivots to + the **disk tier** (unused-primvar removal, primitive-fit, decimation) rather than + forced sharing. + +The identity × reuse disposition matrix that informs the per-unit calls +(externalize / internal-share / keep-local, and the reduction routes) lives in +`usd-structure-assessment/references/instancing-readiness/references/instancing-tradeoffs.md`. + +**The descent is a bounded loop, and the manifest enforces it (not just prose).** +The frontier scan is an upfront whole-stage pass bounded the **same way the +correctness sweep is** — wall-clock budget, killable subprocess, masked spot-check +above a size threshold; when it degrades it records `frontier_estimate_basis = +spot_check` and still produces a bounded, completed plan (no hang). The loop +**stops at the minimum meaningful named unit** and descends past it only for a +**variant-outlier** (share the identical majority, recurse into the differing +branches) or a **unique container of shared children**; it records the **arc count +against the distinct data reused** (not arcs alone) as the too-deep signal, and it +**resumes from the level the asset is already at** (`descent_level` / +`frontier.descent_entry_level`). The deterministic disposition step is shipped as +`usd-structure-assessment/references/usd-hierarchy-dedupe-candidates/scripts/select_frontier.py`; its output drops into `phase4_targets[]` and is +checked by `validate_manifest_structure`, which **fails** a descent that lands a +shared frontier on **anonymous meshes** (`identity_signal: none`), an +**identity-destroying route** (`point_instance` / `merge`) on a **strong-identity** +unit, or a **consolidation claim without measured reuse** — so a bad descent fails a +contract rather than slipping through. + ### Phase 3 - Stage-level scene-graph instancing Owner: `instancing-readiness` (per-candidate gate); `usd-edit-target-planner` (where to author the flips, includes absorbed variant/payload gates). @@ -220,7 +429,14 @@ Owner: `instancing-readiness` (per-candidate gate); `usd-edit-target-planner` (w ### Phase 4 - Per-sub-asset mesh-level optimization -Owner: `so-interpret-validators` (build op chain from Phase 2c findings; T3 never auto-included) -> `so-run-operations` (single-asset driver; agent orchestrates per-target invocation per the "Agent-orchestrated batch mode" section in that skill body; adaptive concurrency by resource budget; prototype-first ordering). +Owner: `usd-validation-runner` (per-target Tier 2/3 validation on each restructured artifact) -> `usd-optimize-interpret-validators` (build op chain from that target's findings) -> `usd-optimize-run-operations` (single-asset driver; agent orchestrates per-target invocation per the "Agent-orchestrated batch mode" section in that skill body; adaptive concurrency by resource budget; prototype-first ordering). + +Phase 4 is the per-target **validate → interpret → operate → re-verify** loop. +Tier 2/3 validation runs here — scoped to one `phase4_targets[]` entry (or one +flagged cross-component pair) at a time — not as a pre-restructure whole-stage +sweep. This is the primary validation model for per-target/per-pair concepts; +see the "Post-Restructure / Post-Decompose Validation Strategy" in +`usd-validation-runner/README.md`. ``` 4a Enumerate optimization targets (1..N): @@ -246,38 +462,104 @@ Owner: `so-interpret-validators` (build op chain from Phase 2c findings; T3 neve disk and log headroom). - Run a pilot batch, inspect resource pressure and failures, then increase/decrease concurrency for the next batch. - - Pause and offer a remainder script only when observed runtime/resource - budget says continuing automatically is unsafe. - -4c Per-target op chain (built from Phase 2c findings via so-interpret-validators): + - Run targets through `usd-optimize-run-operations/scripts/run_batch.py`; the scheduler owns + subprocess spawning, per-target/per-op timeout, dependency ordering, + status.json, and `--resume`. + - Pause only when observed runtime/resource budget says continuing + automatically is unsafe; resume from status.json rather than inventing + a one-off continuation mechanism. + +4c Per-target validate → op chain (Tier 2/3 validation + usd-optimize-interpret-validators): Honor prototype-first ordering: prototypes BEFORE non-prototype targets - so changes propagate. Then run the same evidence-selected mesh op chain - on every non-prototype mesh target, including an `assembly_root` target - when it retained local meshes. Stage-level cleanup comes later; it does - not replace mesh operations for geometry left in the assembly. - **Internal geometry removal runs FIRST** when SA flagged containment - pairs with opaque enclosures: - findOccludedMeshes (analysis) → removePrims (user-confirmed deletion) - Then select remaining operations from so-interpret-validators findings. - Use so-run-operations/references/config-from-evidence.md for + so changes propagate. For every mesh target — each prototype, then each + non-prototype target, including an `assembly_root` target when it retained + local meshes: + 1. Run that target's selected Tier 2/3 validators scoped to the target + (per usd-validation-runner). Open the target file standalone, or + `OpenMasked` over the relevant subtrees for a flagged cross-component + pair; Tier 3 runs per flagged pair. Record the per-target + coverage_ledger. + 2. Build the evidence-selected op chain from THIS target's findings via + usd-optimize-interpret-validators, then split it by apply authority. Each op's + BASE class is the machine-readable `apply_authority` field in + `references/operations/operations.json` (`auto` / + `auto-within-tolerance` / `intent-gated`); read it from the catalog + rather than restating a per-op list here. The meaning of each class, + the inline-elicited vs purpose/identity-gated split within + intent-gated, and the **target-conditional** functional-tolerance + downgrade (which the static field deliberately does not encode) are + owned by usd-optimize-run-operations/references/operation-safety.md "Apply + authority: auto vs intent-gated routing". Apply that split by + iteration: + - **auto (lossless)** ops run now, per target, no prompt. + - **intent-gated** ops are NOT applied in this iteration. Collect + their candidates and carry them to the Phase 7 iteration-2 opt-in + menu. Exception: the inline-elicited intent-gated ops may be + offered in-plan via their fidelity/intent prompt. + Stage-level cleanup comes later; it does not replace mesh operations for + geometry left in the assembly. + **Internal-geometry removal is intent-gated** (the agent cannot know whether + the twin needs its internals): the scoped findOccludedMeshes probe runs here + in Phase 4 like any other scoped Tier 3 probe — no approval — producing the + occluded-prim candidate list and its quantified impact; only the removePrims + deletion is intent-gated, carried to the Phase 7 iteration-2 opt-in menu and + run FIRST among that target's applies when opted into. + Use usd-optimize-run-operations/references/config-from-evidence.md for evidence-to-config routing and - so-run-operations/references/operation-safety.md for confirmation + usd-optimize-run-operations/references/operation-safety.md for confirmation policy before mutation. Prefer meshCleanup for vertex welding; reach for standalone mergeVertices only when the user explicitly needs that upstream-documented behavior — the op mechanics and the meshCleanup.mergeVertices parameter live upstream, resolved via `references/upstreams/usd-optimize.md`. + **Within-prototype mesh merge (`merge` / Merge Static Meshes) is a + first-class step here, not a "someday" option.** When a `phase4_targets[]` + entry carries a `merge` disposition (the sub-MINP weak/none-identity inline + leaves the descent kept local rather than sharing — e.g. loose bolts, + brackets, fasteners under one prototype), run `merge` INSIDE that prototype + (merge once, benefit N instances), never across an instance boundary. + Order it right AFTER occluded-geometry removal and AHEAD of the + `meshCleanup → deduplicateGeometry → computeExtents` tail, as + `merge → vertex-weld-where-contiguous → computeExtents`. It is **intent-gated** + (it destroys per-part addressability) and **bounded-loss**: like other + intent-gated ops it is collected for the Phase 7 opt-in menu unless + inline-elicited. Its payoff is a **prim-count / scene-graph reduction** + (cheaper stage-open + composition/traversal + per-prim memory, plus fewer + draw calls) — it is NOT a disk win (bytes ~= sum; the crate already + byte-dedups). Apply the merge-eligibility guard (weak/none identity only; + bounds-coherence ceiling) and the full op-chain from + `usd-structure-assessment/references/apply-restructure/references/mesh-merge-rewrite-spec.md` + §9 before fusing. **Group the fan by the `(scope × material) key`:** within + the merge boundary (the nearest named/`kind` ancestor, preserved), fuse the + same-material meshes into one `Mesh` per material; when materials must + coexist in one prim, fuse into one `Mesh` with a per-material + `UsdGeomSubset` (familyName `materialBind`) so every binding survives — and + stop merging when the per-subset overhead approaches the per-mesh overhead it + replaced. The detailed grouping/execution mechanic and the archetype-gated + merge depth live in + `usd-structure-assessment/references/apply-restructure/references/mesh-merge-rewrite-spec.md`; + the cheap suggester that surfaces these fans is + `usd-structure-assessment/references/usd-mesh-fragmentation-candidates/`. + Emit `merge_applied`, `rendered_mesh_merged_count`, + `prototype_rendered_mesh_delta_pct`, `merge_identity_class`, + `merge_bounds_coherence`, and the merge silent-loss invariant + `rendered_triangle_count` (a re-pack preserves every face; mesh count and + point count legitimately change, renderable triangles must not) into the + optimization report so the merge earns scene-graph credit and is guarded + (preservation + bounds) by the report gates. Honor the ordering invariants in the "Operation ordering invariants" section below (merge caveats: never if instanced/streaming). Save each optimized output to a NEW path (don't overwrite source). -4d Per-target cheap re-verify - Re-run cheap validators on each optimized output to catch obvious - regressions before stage assembly. Defers full re-validation to Phase 6. - After restructure/decompose, follow the "Post-Restructure / - Post-Decompose Validation Strategy" in usd-validation-runner/README.md - — do not re-compose and sweep. +4d Per-target re-verify (captures this target's before/after) + Re-run the target's selected validators on its optimized output to catch + regressions before stage assembly, and record the per-target before/after + in the coverage_ledger. This is the post-restructure norm: validate each + target/pair independently; never re-compose and sweep (see the + "Post-Restructure / Post-Decompose Validation Strategy" in + usd-validation-runner/README.md). Phase 6 keeps only the Tier 1 + whole-stage before/after for the fair stage-level comparison. 4e Target completion gate (machine-checked; mirrors the validation coverage_ledger): @@ -290,7 +572,7 @@ Owner: `so-interpret-validators` (build op chain from Phase 2c findings; T3 neve non-restructured optimize-as-is target (N=1). `target_coverage.complete` is true only when every entry is resolved (the first three dispositions); a `blocked` or absent target keeps it - false and the report is not final. A diagnosis-only / optimize-as-is run + false and the report is not final. A no_op / optimize-as-is run with no Phase-4 work is valid with `entries: []` and `complete: true`. The report author cannot self-attest coverage of a target that was never enumerated, so the gate reconciles against the manifest(s). Reconciliation @@ -310,25 +592,32 @@ Owner: `so-interpret-validators` (build op chain from Phase 2c findings; T3 neve retained-mesh `assembly_root` left un-optimized. A `monolith`-only run needs no manifest. -Runtime branch: - Kit: ops run via selected SO Python API inside Kit - standalone: ops run via selected SO Python API or standalone wrapper - All Python scripts follow so-run-operations/references/invocation.md; do not - pass plain pxr.Usd.Stage objects directly to Scene Optimizer operation APIs. +Runtime: + standalone only: ops run via the selected SO Python API or standalone wrapper. + (Standalone is the sole optimize+validate runtime; the opt-in Kit->omniperf + path is render profiling only and never runs operations.) + All Python scripts follow usd-optimize-run-operations/references/invocation.md; do not + pass plain pxr.Usd.Stage objects directly to Usd Optimize operation APIs. ``` ### Phase 4.5 - Layer cleanup after destructive in-place ops Follow `usd-structure-assessment/references/usd-edit-target-planner/references/output-saving.md`. -After destructive SO edits, write cleaned layers with -`Sdf.Layer.Export()`, then update the new root's -sublayers/references to point at those cleaned paths. +After destructive SO edits, write cleaned layers with a **compacting +`Sdf.Layer.Export()` + atomic replace**, then update the new root's +sublayers/references to point at those cleaned paths. `Export` recompresses and +**garbage-collects** the layer, dropping arrays orphaned by dedup/cleanup; +**do not use `layer.Save()`** here — `Save()` appends without GC-ing +dedup-orphaned arrays and silently grows the file even as content shrinks. Do **not** use `stage.Export()` here unless the user explicitly wants a flattened deliverable. This cleanup step re-emits individual layers. The disk-size deltas reported in Phase 6 are only meaningful after this -cleanup pass. +cleanup pass, and must be attributed against a **repack-normalized baseline** +(the input losslessly re-crated to the same encoding, zero dedupe) so the free +crate re-encode is split out from the structural win — never present a repack as +the optimization. See `optimization-report/README.md § Footprint attribution`. ### Phase 5 - Stage-level reference replacement and cleanup @@ -357,8 +646,10 @@ Owner: `apply-restructure` (mode=ref_remap). Same skill as Phase 2f - both phase ``` 6a profile-stage:after (same mode as baseline) -6b Re-validate via usd-validation-runner (using the same scoping that ran in - Phase 2c so the comparison is fair). +6b Re-validate via usd-validation-runner: re-run the Tier 1 whole-stage + stats/probes that ran in Phase 2c so the stage-level comparison is fair. + Per-target Tier 2/3 before/after was already captured in Phase 4 (4d); do + not re-compose and sweep to reproduce it. 6c compare-profiles (verdict: improved | neutral | regressed | mixed) If regressed > 5%: warn @@ -369,8 +660,18 @@ Owner: `apply-restructure` (mode=ref_remap). Same skill as Phase 2f - both phase Populate against the optimization-report schema (`scripts/optimization-report.schema.json` within that reference). Match optimization-report/references/optimization-report-template.md. Include baseline metrics (Phase 1a/1b), after metrics (Phase 6a), all operations performed - (Phase 4 + Phase 5), all validator findings (Phase 2c + Phase 6b), + (Phase 4 + Phase 5), all validator findings (Phase 2c + Phase 4 + Phase 6b), output_path = optimized stage root from 5d. + On ANY run that makes a reuse / instancing / dedupe claim, also populate + the `structural_summary` core scene-graph fields the report gates read: + `reuse_measured` (true ONLY when the collapsed reuse was + MEASURED — distinct vs total prototypes/units — never estimated), + `authored_prim_delta_pct` (the primary scene-graph metric, negative = + reduction), `unique_prototype_count`, and `instance_ratio`. These are the + documented producer fields for scene-graph credit; emit them alongside + the Phase 4c merge sub-fields. Report scoring awards NO scene-graph + credit for an unmeasured (`reuse_measured` != true) or unemitted reuse + claim, so a real dedupe that omits these scores zero on that axis. ``` When returning structured plans or runtime-test milestone lists, label Phase 6a @@ -381,26 +682,51 @@ exactly `profile-stage:after`. ``` 7a Compute "untapped options" - the diff between what was done and what could have been done. Examples: - - Lossy operations (decimateMeshes, mergeVertices) skipped this pass - - Tier 3 cross-component perf validators not run - - Aggressive merge held back due to instancing concerns + - Intent-gated ops collected but not applied in Phase 4 (which ops are + intent-gated: operation-safety.md "Apply authority") + - Inline-elicited lossy ops offered but skipped + - Within-prototype `merge` collected in Phase 4 (intent-gated) but not + yet opted into, or held back due to instancing concerns - Restructure declined at Phase 2e - - Phase 4 adaptive batching paused remaining sub-assets due to resource - budget; remainder script generated + - Phase 4 scheduler paused remaining sub-assets due to resource budget; + resume state recorded in status.json + These are NOT a report footnote: present the intent-gated ones as a + **batched per-asset opt-in menu** (operation-safety.md "Apply authority"), + each with win AND loss quantified per asset (see that section for the menu + format). The user picks per asset. 7b Default to 3 optimization iterations for broad "optimize this scene" - requests unless the user opts out, asks for a quick pass, or the request is - diagnosis-only. Each iteration writes an interim report/update before the - next begins. - -7c Iteration 1 follows the normal Phase 0-6 flow. Iterations 2 and 3 are - lighter scoped passes: reuse prior SA/profile/validation evidence, start - from the previous report's untapped options, and run only targeted/delta - probes needed to choose the next operation set. - -7d Loop back to the relevant phase (typically Phase 2c with adjusted selected - probes, or Phase 4 with new ops in the chain). Keep baseline metrics from - the FIRST pass (don't re-baseline). + requests unless the user opts out, asks for a quick pass, or the run reaches + a `no_op` / runtime-forced `structural_only` terminal state. Each iteration + writes an interim report/update before the next begins. + +7c Iteration 1 follows the normal Phase 0-6 flow but applies **auto (lossless) + ops only** — unattended-friendly safe wins, no prompts; this is the primary + reported win, gated behind the whole-stage correctness precondition. + **Default mild bounded-loss pass:** by default at least one Phase-7 iteration + applies the **`auto-within-tolerance`** ops — every `bounded-loss` op with a + deviation parameter at the *conservative* per-target scale band — for + **visually-toleranced** targets (`large-spatial` / `encapsulated` / + `generic`), with a one-line notice (not a prompt). This guards against + under-optimization (the over-tessellated mesh a pure opt-in menu lets sail + through). It does NOT apply to targets carrying a functional-precision signal + (articulated / physics / sim-ready / metrology / variant-bearing), where the + same ops stay intent-gated. Iteration 2 presents the **intent-gated opt-in + menu** (7a) — above-band bounded-loss and identity-losing ops — and applies + only what the user selects, per asset; it **reuses the scoped probe evidence + already gathered in Phase 4** and runs only the selected destructive apply — + detection is not re-deferred to here. (If a candidate type's detection + genuinely was not run earlier, its scoped probe runs now, before the apply.) + The three apply-authority classes (auto / auto-within-tolerance / + intent-gated) and the functional-tolerance gate are owned by + operation-safety.md "Apply authority"; the per-target bands by + usd-optimize-run-operations/references/units-and-tolerances.md. Later iterations are + lighter scoped passes: reuse prior SA/profile/validation evidence and run only + targeted/delta probes needed to choose the next op set. + +7d Loop back to the relevant phase (typically Phase 4 with new per-target + validation + ops; Phase 2c only when a fresh whole-stage Tier 1 signal is + needed). Keep baseline metrics from the FIRST pass (don't re-baseline). 7e Stop before iteration 2 or 3 if no useful untapped options remain, the previous pass regressed materially, the user opted out, or the next pass @@ -410,8 +736,8 @@ exactly `profile-stage:after`. Phase 7 is a default three-pass posture for broad optimization, not permission to run three full workflow reruns. Later passes are expected to be cheaper because they reuse evidence and narrow scope. Revalidation in iterations is -same-or-narrower by default; expanded validation scope, Tier 3 cross-component -probes, full sweeps, or newly destructive operations require explicit user +same-or-narrower by default; expanded validation scope, whole-stage Tier 3 +sweeps, full sweeps, or newly destructive operations require explicit user approval. Always compute the "untapped options" list for transparency in the report, even if the user opts out. @@ -425,27 +751,30 @@ scene-aware adjustment rules. Owned by `usd-validation-runner`. The package keeps only two local validation contracts here: the inline minimum-openability check and the -`validate-usd-asset-validator` reference. External profile/package validators +`validate-usd-validation-nvidia` reference. External profile/package validators such as SimReady are deliberately outside this package and should be invoked only through their owning workflow when the user explicitly asks for them. ### Performance stack (scoped) -`usd-validation-runner` selected plan -> `so-run-validators` -> `so-interpret-validators`. +`usd-validation-runner` selected plan -> `usd-optimize-run-validators` -> `usd-optimize-interpret-validators`. ### Phase-aware subset Owned by `usd-validation-runner/README.md`. Summary: -- `structuring` → minimum-openability + targeted AV blockers only. -- `optimization` → minimum-openability + scoped AV + perf stack (Tier 1 cheap whole-stage stats/probes + Tier 2 on flagged targets; Tier 3 scoped probes mandatory on flagged targets, full-stage Tier 3 requires approval). -- `already_optimized` → minimum-openability + scoped AV + Tier 1 cheap whole-stage stats/probes only. +- `structuring` → minimum-openability + targeted usd-validation-nvidia blockers only. +- `optimization` → **2c:** minimum-openability + scoped usd-validation-nvidia + Tier 1 cheap + whole-stage stats/probes. **Phase 4 (per target):** Tier 2 on each target and + Tier 3 on each flagged cross-component pair, scoped by construction — no + full-stage default; whole-stage Tier 3 is a bespoke user request only. +- `already_optimized` → minimum-openability + scoped usd-validation-nvidia + Tier 1 cheap whole-stage stats/probes only. ## Operation ordering invariants -These are local workflow-ordering invariants. Scene Optimizer operation +These are local workflow-ordering invariants. Usd Optimize operation mechanics, parameters, and defaults live upstream in -[usd-optimize](https://github.com/NVIDIA-omniverse/usd-optimize/); resolve the +[usd-optimize](https://github.com/NVIDIA-Omniverse/usd-optimize/); resolve the checkout through `references/upstreams/usd-optimize.md`. - **`findOccludedMeshes` + `removePrims` FIRST** — remove internal geometry @@ -457,11 +786,29 @@ checkout through `references/upstreams/usd-optimize.md`. `usd-hierarchy-dedupe-candidates` + `apply-restructure` before mesh-level `deduplicateGeometry`. - `meshCleanup` BEFORE `decimateMeshes`. -- `deduplicateGeometry` BEFORE `decimateMeshes`. +- `deduplicateGeometry` BEFORE `decimateMeshes` — **with the instancing caveat**: + `deduplicateGeometry`'s default `duplicateMethod` (Instanceable Reference, 2) + replaces duplicates with instances, and `decimateMeshes` skips instanced prims + (mutating an instance would affect every copy), so running dedupe first with + the default method makes decimation a silent no-op on everything just deduped + (confirmed on large data-center CAD stages). When both ops are planned, either + decimate BEFORE dedupe, or run dedupe with a non-instancing method and flip + `instanceable` afterwards. See `usd-optimize-run-operations/references/units-and-tolerances.md` + for the dedupe parameter gotchas. - `generateNormals` BEFORE `meshCleanup` only when normals are missing or invalid; otherwise skip — never overwrite user-authored normals. -- `data-quality-baseline` first when validators report mesh-quality issues. +- Run the `data-quality-baseline` *pipeline* (computeExtents, generateNormals, + meshCleanup — see `references/operations/operations.json`) first when + validators report mesh-quality issues. - **Never `merge`** if scenegraph-instanced / point-instanced / streaming geometry is in play. -- Deinstance/Flatten Instances BEFORE `merge`. +- Remove scene-graph instancing on the affected subtree (author + `instanceable=false`; there is no catalog op for this — it is a USD edit) + BEFORE `merge`. +- **Within-prototype `merge` executes the manifest `merge` disposition**: run it + INSIDE a prototype, AFTER occluded-geometry removal and BEFORE + `meshCleanup`/`deduplicateGeometry`/`computeExtents`, as + `merge → conditional vertex-weld → computeExtents`. Only weak/none-identity + units, only when bounds-coherent (§9 guard) — never on a strong-identity + (addressable) component/subcomponent. - Set Instanceable AFTER reference-heavy authoring. - `removePrims` BEFORE `pruneLeaves`. - Common chain: `fitPrimitives` -> `deduplicateGeometry` -> `organizePrototypes`. @@ -480,7 +827,7 @@ in the same batch so changes propagate to instances. ### Analysis-only ops -The SO ops listed below produce reports but do not mutate the stage. They +The Usd Optimize ops listed below produce reports but do not mutate the stage. They are not invoked by any named pipeline — agents reach for them on user request or as part of bespoke triage: @@ -492,12 +839,12 @@ request or as part of bespoke triage: often a sign of poor authoring or failed import. Treat as a Tier 2 targeted medium probe through `usd-validation-runner`, not a cheap whole-stage default. - `utilityFunction` — meta-utility op for ad-hoc SO scripting; rarely the - right tool but available when one of the recipe skills needs it. See - `references/operations/utilityFunction.md`. + right tool but available when one of the recipe skills needs it. See the + `utilityFunction` entry in `references/operations/README.md`. The lossless coincidence/occlusion analyzers (`findCoincidingGeometry`, `findFlatHierarchies`, `findOverlappingMeshes`) are wired as live analysis ops: -prefer running them through `so-interpret-validators`, which routes them from +prefer running them through `usd-optimize-interpret-validators`, which routes them from validator findings. If you do run an analysis-only op on user request, summarize its findings as @@ -520,22 +867,21 @@ SA-flagged containment pairs with opaque enclosures, followed by | When | Outcome | |---|---| -| Phase 0: direct SO execution requested but SO unavailable | Halt with `blocked_missing_scene_optimizer`; do not substitute another workflow. | -| Phase 0: requested SO op absent from the loaded runtime | Halt with `blocked_missing_so_operation`; surface supported alternatives if any. | -| Phase 0: broad optimization request, SO unavailable, and user declines install | Switch to structural-only path. Skip Phases 4-5; set `workflow_mode: structural_only` in the 6d report (verdict stays in its enum). | +| Phase 0: direct SO execution requested but Usd Optimize unavailable | Halt with `blocked_missing_usd_optimize`; do not substitute another workflow. | +| Phase 0: requested Usd Optimize op absent from the loaded runtime | Halt with `blocked_missing_usd_optimize_operation`; surface supported alternatives if any. | +| Phase 0: broad optimization request, Usd Optimize unavailable, and user declines install | Switch to the `structural_only` path. Skip Phases 4-5; set `workflow_mode: structural_only` in the 6d report (verdict stays in its enum). | | Phase 0: User chooses "exit" at install prompt | Exit with reason "user declined runtime setup". | | Phase 1a: profile-stage fails to open the asset | Halt with diagnostic; the asset cannot be optimized if it cannot be opened. | -| Phase 2c: SA's `phase_recommendation = already_optimized` | Skip Phases 2d-5; jump to Phase 6 verify; produce report with `workflow_mode: no_op` and `verdict: neutral`. | -| Phase 2e: User chooses "exit" at restructure gate | Skip to Phase 6d and write a diagnosis-only report. | +| Phase 2c: SA's `phase_recommendation = already_optimized` | Continue through the pipeline; Phases 3-5 find no work; produce report with `workflow_mode: no_op` and `verdict: neutral`. (No diagnose-and-exit shortcut.) | | Phase 2e: User chooses "optimize as-is" | Skip Phase 2f; continue to Phase 3 with the original stage. | | Phase 3b: All instancing candidates fail readiness | Skip Phase 3 result-application; continue to Phase 4. Note in report. | -| Phase 4d: A target's optimized output fails cheap re-verify | Discard that target's output; continue with other targets. Report failure in 6d. | +| Phase 4d: A target's optimized output fails re-verify | Discard that target's output; continue with other targets. Report failure in 6d. | | Phase 6c: Verdict = regressed > 20% (critical) | Recommend revert (do not publish); user decides whether to publish anyway. | | Phase 6c: Verdict = `mixed` | Report honestly; do not present as success. | | Phase 6d: optimization-report writes successfully | In-flow pass ends. Phase 7 may continue into the next scoped iteration unless the user opted out or stop criteria apply. | | Phase 7: User declines iteration | Flow truly ends. The Phase 6d report stands as the final deliverable. | -## Expected duration hints (typical large stages: ~100K prims, ~200K meshes) +## Expected duration hints (typical large stages: ~200K prims, ~100K meshes) These are guidance for setting user expectations and timeout windows, not hard SLAs. @@ -545,9 +891,8 @@ These are guidance for setting user expectations and timeout windows, not hard S | Phase 1 | ~5 min (profile open + SA pass) | | Phase 2c structural validators | ~2 min | | Phase 2c Tier 1 cheap whole-stage stats/probes | ~5 min | -| Phase 2c Tier 2 perf validators | ~30 min | -| Phase 2c Tier 3 perf validators (scoped to flagged targets/pairs) | minutes - mandatory when flagged | -| Phase 2c Tier 3 perf validators (full-stage) | hours - always confirm before running | -| Phase 4 per target | ~10-30 min depending on op chain | +| Phase 4 Tier 2 perf validators (per target) | ~30 min total, parallelized across targets | +| Phase 4 Tier 3 perf validators (per flagged pair) | minutes per pair - mandatory when flagged | +| Phase 4 per target (validate + op chain) | ~10-30 min depending on op chain | | Phase 5 ref-remap | ~few min for typical impact sets | | Phase 6 re-validation | same as Phase 2c | diff --git a/skills/omniverse-usd-performance-tuning/skill-card.md b/skills/omniverse-usd-performance-tuning/skill-card.md index 4671d606..2fe14d11 100644 --- a/skills/omniverse-usd-performance-tuning/skill-card.md +++ b/skills/omniverse-usd-performance-tuning/skill-card.md @@ -1,5 +1,5 @@ ## Description:
-Top-level workflow skill for USD performance diagnosis and optimization, used for slow loading, high memory, low FPS, or generic scene optimization requests.
+Top-level workflow skill for USD performance diagnosis and optimization. Handles slow loading, high memory, low FPS, and broad scene-optimization requests; delegates auth/runtime setup to Phase 0 owners.
This skill is ready for commercial/non-commercial use.
@@ -9,11 +9,17 @@ NVIDIA
### License/Terms of Use:
Apache-2.0
## Use Case:
-Developers and engineers working with USD scenes who need to diagnose and resolve performance issues such as slow loading, high memory usage, low FPS, or GPU crashes in NVIDIA Omniverse workflows.
+Developers and engineers working with USD scenes who need to diagnose and resolve performance problems such as slow loading, high memory usage, low FPS, GPU device-lost events, and validation failures.
### Deployment Geography for Use:
Global
+## Requirements / Dependencies:
+**Requires API Key or External Credential:** [Yes]
+**Credential Type(s):** [OAuth Token]
+ +Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate.
+ ## Known Risks and Mitigations:
Risk: Review before execution as proposals could introduce incorrect or misleading guidance into skills.
Mitigation: Review and scan skill before deployment.
@@ -21,37 +27,59 @@ Mitigation: Review and scan skill before deployment.
## Reference(s):
- [Workflow Reference](references/workflow.md)
- [Skill Map](references/skill-map.md)
+- [Operations Registry](references/operations/README.md)
- [USD Structure Assessment](references/usd-structure-assessment/README.md)
-- [Scene Optimizer Operations](references/operations/README.md)
-- [Setup USD Performance Tuning](references/setup-usd-performance-tuning/README.md)
-- [USD Validation Runner](references/usd-validation-runner/README.md)
- [Optimization Report](references/optimization-report/README.md)
-- [Scene Optimizer Run Operations](references/so-run-operations/README.md)
-- [Compare Profiles](references/compare-profiles/README.md)
-- [Profile Stage](references/profile-stage/README.md)
+- [USD Validation Runner](references/usd-validation-runner/README.md)
+- [Usd Optimize Run Operations](references/usd-optimize-run-operations/README.md)
+- [Setup USD Performance Tuning](references/setup-usd-performance-tuning/README.md)
## Skill Output:
-**Output Type(s):** [Analysis, Shell commands, Configuration instructions, Files]
-**Output Format:** [Markdown with structured JSON reports]
+**Output Type(s):** [Files, Analysis, Shell commands]
+**Output Format:** [Optimized USD stage, JSON report, Markdown summary, rendered HTML report]
**Output Parameters:** [1D]
-**Other Properties Related to Output:** [Produces optimization-report.schema.json-conforming reports and HTML previews via render_preview.py]
+**Other Properties Related to Output:** [Structured JSON conforms to optimization-report schema; HTML rendered via template]
+ +## Evaluation Agents Used:
+- Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`)
+- Codex (`openai/openai/gpt-5.5`)
+ + ## Evaluation Tasks:
-NVSkills-Eval 3-Tier evaluation (external profile): Tier 1 static validation (9 checks, 10 findings), Tier 2 deduplication analysis (2 checks, 17 findings). Tier 3 live agent evaluation not available in this report.
+9 evaluation tasks (8 positive, 1 negative), each running in an isolated sandbox pod.
## Evaluation Metrics Used:
Reported benchmark dimensions:
-- Security: Checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access.
-- Correctness: Checks whether the agent follows the expected workflow and produces the correct final output.
-- Discoverability: Checks whether the agent loads the skill when relevant and avoids using it when irrelevant.
-- Effectiveness: Checks whether the agent performs measurably better with the skill than without it.
-- Efficiency: Checks whether the agent uses fewer tokens and avoids redundant work.
+- Security: Whether the skill avoids unsafe operations, secret leakage, and unauthorized access.
+- Correctness: Whether the final answer is correct against the reference answer.
+- Discoverability: Whether the right skill was found and executed when needed.
+- Effectiveness: Whether the skill helped complete the user's goal and followed expected workflow behavior.
+- Efficiency: Whether the skill avoided wasted tool or skill usage.
+ +Underlying evaluation signals used in this run:
+- `security`: Checks for unsafe operations, secret leakage, and unauthorized access.
+- `skill_execution`: Whether the expected skill was found and executed.
+- `skill_efficiency`: Routing quality, workspace-aware skill reads, and productive tool use.
+- `accuracy`: Final-answer correctness against the reference answer.
+- `goal_accuracy`: Whether the user's goal was achieved.
+- `behavior_check`: Whether the expected workflow behavior was followed.
+ +## Evaluation Results:
+| Measure | Codex (Baseline → Skill Uplift) | +|---|---:| +| Overall | 46% → 84% (+38 points) | +| Security | 89% → 100% (+11 points) | +| Correctness | 20% → 76% (+56 points) | +| Discoverability | 47% → 91% (+44 points) | +| Effectiveness | 37% → 63% (+26 points) | +| Efficiency | 35% → 91% (+56 points) | ## Skill Version(s):
-0.1.0 (source: frontmatter, pyproject.toml)
+0.1.0 (source: frontmatter)
## Ethical Considerations:
NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse.
diff --git a/skills/omniverse-usd-performance-tuning/skill.oms.sig b/skills/omniverse-usd-performance-tuning/skill.oms.sig index bd9e75ae..432edcb9 100644 --- a/skills/omniverse-usd-performance-tuning/skill.oms.sig +++ b/skills/omniverse-usd-performance-tuning/skill.oms.sig @@ -1 +1 @@ -{"mediaType":"application/vnd.dev.sigstore.bundle.v0.3+json","verificationMaterial":{"x509CertificateChain":{"certificates":[{"rawBytes":"MIICgzCCAgmgAwIBAgIUKIyS7SxNteQIiWzK1dWj85E6520wCgYIKoZIzj0EAwMwVTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjEpMCcGA1UEAwwgTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBJQ0EgMDEwHhcNMjYwNDAxMDAwMDAwWhcNMjgwNDIyMTUzMzA5WjBUMQswCQYDVQQGEwJVUzEbMBkGA1UECgwSTlZJRElBIENvcnBvcmF0aW9uMSgwJgYDVQQDDB9OVklESUEgQWdlbnQgU2tpbGxzIFNpZ25pbmcgMDAxMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEYoRM9bQl/dGlwSRNi6bTpIJUXH8Nv9GciP6LSflJYYMLCc296kpyuTSsk5ddbAWiDcFX3C/ydX3jwc+qCLYP6uHy9XphyLjOQ27Yb2J6rBLVtRBS1mgGco/Gr7fL6ODco4GaMIGXMB0GA1UdDgQWBBRQ/5ZW3nJ6lmo9SVk7I15o7UGmpTAfBgNVHSMEGDAWgBRPGpILxMBBleJSsBGjrMKsby1CgjAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDA3BggrBgEFBQcBAQQrMCkwJwYIKwYBBQUHMAGGG2h0dHA6Ly9vY3NwLm5kaXMubnZpZGlhLmNvbTAKBggqhkjOPQQDAwNoADBlAjAUygu/GiOCIXrgGr4SmLgeEVDcEitfFUv7ALbvLVGVyMysB3mxmO/uInZfXzWcJZsCMQDxuoxj4ZmO30jhkPIcCxGFCOvnUsnfU3TfGcouYm4M6iRpbKvtVnHPiy4bi6pcKf0="},{"rawBytes":"MIICiDCCAg6gAwIBAgIUZsIuSv9NkpJCNqtYEfCouVv5BzowCgYIKoZIzj0EAwMwUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTAgFw0yNjA0MDEwMDAwMDBaGA85OTk5MTIzMTIzNTk1OVowVTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjEpMCcGA1UEAwwgTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBJQ0EgMDEwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAASI72cR3ctKGg4VWnB3bNja6g1Z2PnOmFEopkPof+QeIcPk9rT+g9MjJnq51EQXL93a7C2GJ9J985G4o2V85VD7wJ1RaXhluHW2rf3y8bQGeAYaKMr5s/hUgn+M3/9WlWejgaAwgZ0wHQYDVR0OBBYEFE8akgvEwEGV4lKwEaOswqxvLUKCMB8GA1UdIwQYMBaAFItnoAjjfuCEUvzyvWyI2vOGvwPjMBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYDVR0PAQH/BAQDAgEGMDcGCCsGAQUFBwEBBCswKTAnBggrBgEFBQcwAYYbaHR0cDovL29jc3AubmRpcy5udmlkaWEuY29tMAoGCCqGSM49BAMDA2gAMGUCMQCeIMMfAbyzPDacw2MxG+Yt1cikrJX/DVxiGfXuHmkkXn6VgSzE79+lkqDErpVO2gYCMCNEColOyvUvkzZGUEI1hQ3PfMgi3FIo9tHoBKMw4/wGBLFpu/0ubtmbBXM6/UMOEw=="},{"rawBytes":"MIICRTCCAcygAwIBAgIUeJdY3rV86EdvFmG7L8LJBsyQFYkwCgYIKoZIzj0EAwMwUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTAgFw0yNjA0MDEwMDAwMDBaGA85OTk5MTIzMTIzNTk1OVowUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTB2MBAGByqGSM49AgEGBSuBBAAiA2IABAYpiXCDjJ9NT2eSDhyHJVSw1Tbze18cGG2F/578oWvHxg23eQAhNRYdq88i1iOshZSO6C29doKui5Xpmo/7Ctw9Sx4PP2RzOmIuOLCuTdNtKcTRwi4GEsd5BAFvWj42M6NjMGEwHQYDVR0OBBYEFItnoAjjfuCEUvzyvWyI2vOGvwPjMB8GA1UdIwQYMBaAFItnoAjjfuCEUvzyvWyI2vOGvwPjMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgEGMAoGCCqGSM49BAMDA2cAMGQCMCwtAjWLaNwgGWNCgdyNoTyvNhqWRECRJV2r3+7w8g0PL6NHLOsbkgE09BH95h8XlgIwTaQmbbUh2ChAJ5TA1wRiVDnCcvbzHlZl2jM2FcwQQZlk19LOAbyGMRixbu2Ww/rj"}]},"tlogEntries":[]},"dsseEnvelope":{"payload":"ewogICJfdHlwZSI6ICJodHRwczovL2luLXRvdG8uaW8vU3RhdGVtZW50L3YxIiwKICAic3ViamVjdCI6IFsKICAgIHsKICAgICAgIm5hbWUiOiAib21uaXZlcnNlLXVzZC1wZXJmb3JtYW5jZS10dW5pbmciLAogICAgICAiZGlnZXN0IjogewogICAgICAgICJzaGEyNTYiOiAiZTgzODkyYjA2ZjFiNDJkMGMxNjE5ZDYwMzMxNjMwMmIyMWQ3ZmNmNzVmODdiYWM3MDdiOGI2OWI2YjFkNjNlYSIKICAgICAgfQogICAgfQogIF0sCiAgInByZWRpY2F0ZVR5cGUiOiAiaHR0cHM6Ly9tb2RlbF9zaWduaW5nL3NpZ25hdHVyZS92MS4wIiwKICAicHJlZGljYXRlIjogewogICAgInJlc291cmNlcyI6IFsKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImQ3N2QzMTI5YWViZDY1NTk4OTZlODUxNjEyOTdhYWQ2NDlmMWJiZmM0ZTJiODc3NGUwZTZkYzgwNWFkMTE1MmMiLAogICAgICAgICJuYW1lIjogIkJFTkNITUFSSy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjhhNzFiMDIzZWU3ZDk5YzFkNWIwNTczMTllM2I2OWY5MGUwMzg0MWMzZTliNTZkNTI1YjMzNmY5YmIyZTI2MTgiLAogICAgICAgICJuYW1lIjogIlNLSUxMLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMDMxMjEzY2JiOTVmYzBkMWExZWUzNzczOTYyNzEzNjdmMjM0YzgzYWZmNjNhNWVkNWUwNTYyZjE3M2ZhODU3YiIsCiAgICAgICAgIm5hbWUiOiAiYWdlbnRzL29wZW5haS55YW1sIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiOTg3N2E1YmM4NTVlY2YxMjNjMTVhODQ2YzFmZjIyMWYyMzM2NTJkODEwMmZkY2RjYTVhNjM4ZDI4YWEyZDRlMSIsCiAgICAgICAgIm5hbWUiOiAiZXZhbHMvZXZhbHMuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjM1NWEyYmU3MTIwZTE0NzI5NWM3YmEyZWI1ZDllM2MyNzNiYWZiNDIzNzk3NmE2NzIxYzZjM2JkMjI5YTE0YjQiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvY2FkLWNvbnZlcnNpb24vUkVBRE1FLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiODViZmY2MTYyZTY5N2U5NzkyNTFmMWJiNWJlMmY4N2I0NzE1NzkwZTllNDRlMjZhMmQ5MjllYmJkMmFiM2ZhZSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9jYWQtY29udmVyc2lvbi9zY3JpcHRzL2NvbnZlcnNpb24tcmVwb3J0LnNjaGVtYS5qc29uIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNDI1OTkyZTgwODBkZWEwOWUxYzRmYTQyYWVlNGJiZDcyZGQ0MTllZWMyZjc1YTAxNjg2NDIzODIxZWViOWIxOSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9jb21wYXJlLXByb2ZpbGVzL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImExZDU4OTU4NDE2NzFmNWYwODNmNzY0MGNhMzNhNDI5NWNlM2QzZWUwNWUzNzRiZDNmYjQwZTk1YzA5ODAwNzEiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvY29tcGFyZS1wcm9maWxlcy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImVlNGRjYjMwNTM0ZGM5NGU3MDljYzI1MTI5Njc0MDkzM2ZiZDE2NzM3NDkwODNhMWQ4NGE4YmJlZWNlN2YyNzEiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb21uaXZlcnNlLWF1dGhlbnRpY2F0aW9uL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjJmNjI1YTExMTMxODAxYjFjMDMzNjVhOTNiYmNmN2Q0YTk1Zjk3YjM2NTRhNTQ1ZjM3ZmMwMjUwYjdmZDRiZTAiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9DTEFTU0lGSUNBVElPTi5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjAyZTI2YTc5NzE1MGE1ZWVkOTZjMWE3NzUyMzE1ZTQ5Yzg4MWI5M2U1ODg2MjgyOGY4NWFlZGMwMTVkMWY0ZjUiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9FWEVDVVRJT04ubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJhMTlkNTZlNWI0YjlkNTFlZTY3MWUwZWQ1YmQwNDdhYzc0MWZhN2VhZWQ5ODcxYzBjMDRhOWFhYWZkNWNkMmQ4IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvUkVBRE1FLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNmJlNmRlYjk0MjM3NjY1NDEwMGQyMWVkZDNmMWVkNWNjMzA5YjA0OWM5N2EyOGE1MzY2ZGM1MDkwNWYwOWYwZiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL19jdXJhdGlvbi5qc29uIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMjA4ZDEyNmRjNTc5YWJkM2I3NDBhZjVhNjQ4Nzk0NTI5N2M4ZTg0MzFmNjAwMDk5NDc1OTBiOTY1NTI0YjVjYSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL190ZW1wbGF0ZS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjgwODJhNThiOTMyMzdhYjhjMzNmOTliNTBiOGRmNjM2OTc5NDQ0YWFmYmVhZTZkOGNjNzdkNzM5M2Q2Yjk2MzQiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9ib3hDbGlwLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNTMxMzVmNGVlNzNmZTg1YzllMDFjZGY4OWQ0ZWY1YWQzODhjZWFkOWJlM2VhNmI4N2EzMTdkODdjZWFmYmQ4MyIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL2NvbXB1dGVFeHRlbnRzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiODY0MjIxZDNlZTVjMjI1YTc5NDFkZmVkNjkyNTQwNzA1N2E3MGJkMGM4YWFjNjU2ZDhjNTQ5MWVmODU1NmM2NiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL2NvdW50VmVydGljZXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJiMTNhNmRhYWE3YjQyYWYwYTkyYjgzZTYzZTZlMzkwOGY4NjBkMjA2NWE4MmQwYWUxYjIzODQ5ODM4MDhiM2RkIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvZGVjaW1hdGVNZXNoZXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI0YmQ1Yzc1YTk3YjkxYWExNmUyZWRkOGEwOTQ1MjhkYWI1YWU5OWI1MzkwZGUyYmIyNTIyNmYyZmQ5NTMxZTFjIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvZGVkdXBsaWNhdGVHZW9tZXRyeS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjczMzdjZjdhMDhmY2I5M2Q3YmQ5ZDU2MmI0ODMxNjAwMGIyNTg0MGUxYjc2YmM0Y2MyZDNiNjk5MmI5YTFmMTUiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9kZWR1cGxpY2F0ZUhpZXJhcmNoaWVzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNTNhZThiNzJmNmIxMGI3ZmE5ZDhiOTA3MGYwODgwNWZkYTY5MTk5YjI1MjRkMjRmNjczZWI2NjZmZTQxMTNhNyIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL2RlbGV0ZUhpZGRlblByaW1zLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiZTU1Y2NjNmE3ODgwMWNlNjdlOTk4MTBlN2FjMWI3YTdiODFjM2VlOGY1MTZhYzc2MGE5NTJiYTFkYjU4MmZiNyIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL2RlbGV0ZVByaW1zLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiYzNiMzU4ZjBiMWYwOWY0OTJlMWFjYzI0NWNhMjBjNDRkNGYwMDNjYWE3MzIzZjEwNzVjZjI5MWQxNDVjNDNkOCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL2RpY2VNZXNoZXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJhODNkOGUwMTZmMTA0ZDQxMTY0YzAwYjZlMWQxMmJmY2JkYzEyYTAwOWM4M2U5NzE2MTUyYjAzOWRjMzlkMzlkIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvZWRpdFN0YWdlTWV0cmljcy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImI2NTFkMGM1Yjg3ZDQ2NWU1ZjRlZDBiNzA5ZTZkOWFiZGE5MmY3MjNjNzI4NWQ5MmQyZWM1NzJjOTI0ZjBlNDkiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9maW5kQ29pbmNpZGluZ0dlb21ldHJ5Lm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiM2RhNDM5MjFkNGM5YjYxMjVjOGJiMWIwYTA0NWU0NWM5YzVjMmZlNTQ4NTZkNTBlYWE5MDUxN2U1ZWRhZWZkZiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL2ZpbmRGbGF0SGllcmFyY2hpZXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJjNWYyMTUxMzg5ODNhOTMwNGM1ZGIzMjI0ZjMxNzc3YjkyYTg0ZDQ3NjY1Y2FlYWNiOTQxMjIyODcyMzIyYWFhIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvZmluZE9jY2x1ZGVkTWVzaGVzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiYWI0MzI0OTcyZThhNGE0ZTEzYjExNGU5MGEyMWYxOTM0MzM3NDIyNzI2YTZkZDBlY2E0M2U2MTAyODYyNDY1OSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL2ZpbmRPdmVybGFwcGluZ01lc2hlcy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjIwOTNmZjNkZmNmMDVlNmY2MDMzOTY1YjI3YzY0YmZmNDFjOTdiM2RhZjc4M2Q3OGFlYjNiODIyOGU5N2UxM2EiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9maXRQcmltaXRpdmVzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNzM2NGFjNjA2NjFlODA0NzcyOGZlYjdmNmQxNzQ4Y2I5ZDY0MzUyNTI1ODExNGViZTQ3M2E3ZjNjNjg2YzllNCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL2ZsYXR0ZW5IaWVyYXJjaHkubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJlN2M0OGUwZGRkODQ3Mzc3OWYxMDUzYmM0NDhhMmJiYWQzZGZhYTVlNWM5ZDE3M2U2MzY3YzM2ZmVkMjk1M2RhIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvZ2VuZXJhdGVBdGxhc1VWcy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImVjOWMxZTA0NTkyMzE5Y2UzMGY3OTNjMWY2NDk1MWRjNDJjZDEzYTljNmY0NjNkM2RjZDM2ZjVjYWFhNjZjMTIiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9nZW5lcmF0ZU5vcm1hbHMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJkNDg4ZTA1ZGQyODNhOWQ0MGI5MjQ5NzI0ZjQ4MTNhZGI3OTQ1ODYyY2YwOTk1ZDdkOTUxMjhiNTU5ZDc0NDRmIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvZ2VuZXJhdGVQcm9qZWN0aW9uVVZzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiYjhmODFiZDgzY2EzYWJlZGEzZDAwZmJhZGM3NWMzY2EyZWE0Y2Q0YTBlNGEwMTI4YjA1YTJmMjk3YzY0NThiZSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL2dlbmVyYXRlU2NlbmUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI0ZDk0NjRkZGQzNWYzM2E5ZTY3MTNkODFiMTFkY2M0YTliMzgxZjJkNzk1YTRmZmVlMTRmOTZkYTE3OWQzNzkwIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvbWFuaWZlc3QuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjQwOTMyZTllNDg5NDJlZWExODZjM2ZmOTZiZmE2OGMxZDIyNTkxYjBkYjVhNDY3ZWJkMDdlYzRmZjQwMjg1OGYiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9tYW5pZm9sZE1lc2hlcy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImZmOWRiNTM5OTNhYzFjMzhkMmZlMTc1ZTRjMGIzNzFjZmRjMzkzMzZlYjc0NGMxYjNhMDBjMmQ0OGRmYzI0NWUiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9tZXJnZS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImE3YWNhMzNjYzg2NmUxNTczMWFkNjI2MGQ0YzZjZjA0MGUxMjAyZDQwZTg3NmQ3MTExOTcxZjM4NjNlNzM5ZTQiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9tZXJnZVZlcnRpY2VzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiN2RiNWJjMGYxYmM5OTI0MWUxOTI0NTRlYjJjODM5YjViZGU5OTRjNGQ2YmY1YTJkMzgzMDBiMGVlMzNiMDkwNiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL21lc2hDbGVhbnVwLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNzYzOTEyMDU4ODJkNjUwOWUwYWU0ODk2M2YyZmYyMGQ2ZmYwMTllMzcxNmI2MzIwNWE0ZmRlYzE1YTE4NjFhNCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL29wdGltaXplTWF0ZXJpYWxzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNTJmZWZiZGZiZDMwZTMxYjI1MDkwMWI1YzkzMTYxOTNjY2Y1NGY4NzYwNTJjMDMxMzljOGQyYzA0MGUxYWI0YiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL29wdGltaXplUHJpbXZhcnMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICIzZDBkNGQ1MTc0YjYwNjk3OTUyMTk0M2E2OTVlN2ZhODllZDU0YWIyNjM3MTNjMTY2ZmQzYzIyMjNhNGVlMjA0IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvb3B0aW1pemVTa2VsUm9vdHMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJjYWY2MDhhMTZkM2VkZGFiMzI1M2MyZDQ2ZDdjZWIxYzAzNGFiN2YyNGRiODE3NjM3Y2JkNmM3ODgzOGUwNzI5IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvb3B0aW1pemVUaW1lU2FtcGxlcy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjdmYWY3NGIzOGJjMWI5NmJjNWM5ZGY1ODNlZmI0N2E1NGQyODZlMzhhNzY0N2YxZTdjMTdlMzFlNzlhYzk1YzUiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9vcmdhbml6ZVByb3RvdHlwZXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJhMzU2NzcwZTdiMzgzMTgwMTQyOTM5MTE3MjFlZmNhN2NiYmNmNjQ5Y2RmNjM2OTdiNzEyMjc5MmEyY2JhYzRhIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvcGl2b3QubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJkNjVjYzM0Y2JiYTM0NTRiMTk1OGIxMTIxMDM3OGJkNGU2OWMyNjJmYTE5NjgxN2M3NWU1OTJhODNmYmM3NTk0IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvcHJpbWl0aXZlc1RvTWVzaGVzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNWQ2MTFjNDQ4NGJiNDY4MWI4NjcwYTBhMjM2OWI2MjYxNjhiYzU4ODg4Mzc4NWFhNmM0ZTQxMjVmOGZkMDNhYiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL3ByaW50U3RhdHMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI5MmUzZjY0N2IwMDg5N2Y0ZTU1NzMxODU3NzVhNzIxNzYyMTJhZjI0Y2MyOTkwNDE5YWU0M2YwMGRjNzQ1ZWRjIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvcHJvYmUtc25hcHNob3RzL3NvLTExMC4wLjQuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImNiN2MyMDRhN2ExMmZlNTIwYWFkNjJjYWQzZDhhZTRiZDlmN2M2ZmZhMDg3YzFkNmZlYjczNzkwMzgzZDMzNWEiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9wcnVuZUxlYXZlcy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjQ3NTEwZWExZTVmY2YzOGRmMTAwYzhiNDE1NDA5MGE1MTY4ZmFhN2VmZWI2OWNmZTcxOWU2YjliMDc2YmJhNGMiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9weXRob25TY3JpcHQubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICIyYTA2ZDkwMDU0NjBiMGM3MGUyMWU3NGFhODg3OTA3OWJhN2QxY2FhMmYzMzE2YzkyN2NhZTgwM2U2ZjY4YjI3IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvcmVtZXNoTWVzaGVzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiZGY3MWZiNzRkMWZhZTViMTdjZTc2ZTM2MjZmOTA4ZDJjM2YwZTUwOGU5OTQzOWJkYTY5YTQyNTY0Yzg4M2VjZiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL3JlbW92ZUF0dHJpYnV0ZXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI2ZWE3OGNjOTZlYThlZjc3OGYxZTAzZTA5YTUxZWNiMGFjMmYxMGU1NDY4MjY0NTI4Mzg0YWZlZTMzNzg5ZTczIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvcmVtb3ZlUHJpbXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI2OTVhZTg4ZjJmMDMyNDlkOTRhMTg4NDZhZmQ0MzBiM2RkYWQ0ZjA2YjlhMDFiNzBhY2MyNDcyM2RhYWUyZDcxIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvcmVtb3ZlU21hbGxHZW9tZXRyeS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImNjMGFhM2ExZWM3OGNiYzIxMmNiZTMwOTk3ZmI3ZDM0NzcwNWQ4OWQxYmJmOTNjYjNmYmI2NTRmNjhjZDNmOTUiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9yZW1vdmVVbnR5cGVkUHJpbXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI4NzE4OGJjNjY2NDAyNDdmNTc1NmEyZjEyMzZiOTBkNjI3OGM4ZWRlM2FlYzI2YzQwNmQzNjAzNTQ2NGM2YTI3IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvcmVtb3ZlVW51c2VkVVZzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiOTZkNTM0ZmVhZDE1NWM5NGM3NzNkNTM2YzIyYjBjZmRhNWEyZjUzNjRlYzYzNzRiNjJkNmE2NzY0YmNhODE1NCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL3J0eE1lc2hDb3VudC5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjUyNjg3Y2Q4NWIwYjAwZTc4Y2IzMDQ0NzcwMmIyMGRmODhlZWMxMDVmZDdhN2I4NzdiZWM5NzE5OTBjMGQ4YzciLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9zY3JpcHRzL29wZXJhdGlvbi1jdXJhdGlvbi5zY2hlbWEuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjJjOTdiNGNlMDkyMDYzNTk1MmZiYTNiYTRmMmMzZWE5ZmJjZTJhNmRlNTkxNmNmOGJjMjE1YjNkNTU4ZmIxNDUiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9zY3JpcHRzL29wZXJhdGlvbi1tYW5pZmVzdC5zY2hlbWEuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjI0MDZiZWNkOWYxYzkzMjljYTlkNGJkZWQzOWQwNjYyODQ3N2IzZDFkNmRhOTM2MDA3YzNkMmE5ZDI5NzNjMWYiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9zaHJpbmt3cmFwLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNmI4YzUxNTc3MzYxMDg5NGE0MGJhYjQ3Yjc1MDI5N2FiYTk3ODFmNGQ0M2ZmODYxNmE1YTZiMTkxYWMxN2IyYyIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL3NwYXJzZU1lc2hlcy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjUyNWM3MGQ1MDA0ZjA1MDFhOWU1MDc5ZWY4NzBlOWMzNWQ0MjdlZGM1Njg4YWE2Njc2NWIyMDQ2MTU2YWEzOTIiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9zcGxpdE1lc2hlcy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjI3YmEyZjU3NTFhMDRhM2JiY2I1ZTJhMDBlYmNmNzE4ZjE5ZTJlMDA5YWM3YTFjMjhjNjM2NGZhNWQ5YzJhNTAiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9zdWJkaXZpZGVNZXNoZXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI1MmM4NGE4MjZkNmVlMjcyMDg1OTY3NTQ5NWZjOGUyMzBhNjM3ZmRiN2NkODBlZjk0MGRmZjIyNTc0N2EyZDkzIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvdHJpYW5ndWxhdGVNZXNoZXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJlZDQ1YjVlMDhkYTNlYjk2YjBiMjg3YmMyODJhODhmNWFmODhiMDY2MmY2ZDY1ZTRhODYxNTdhNzM5YjgyMDlhIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvdXRpbGl0eUZ1bmN0aW9uLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNzIxNDIwNjkwNzA3OTQ1MDQyMDM0ZWFjNjc1OGQyZmQyN2JlZDNmOGJmMjdmYzNlY2MyMWRlZjY0MTNmNzg4YSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcHRpbWl6YXRpb24tcmVwb3J0L1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjJhNGExYmQ5YjliODg5ZGJmYjYzODRmYjkyZmZjZGRjMGRjZTg5YmYxYmVlZTdkNzBiY2U4MzdmYWE4ODA4NTIiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3B0aW1pemF0aW9uLXJlcG9ydC9yZWZlcmVuY2VzL29wdGltaXphdGlvbi1yZXBvcnQtdGVtcGxhdGUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICIyYmQ5ZTQ0MzAzMDIzMDg0ODY0MGEzZmIzODVjM2MwZGEyNjZmYWMzZGYxYjA2Zjc5NGJiZWI0ZTA3MTI0YTkwIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wdGltaXphdGlvbi1yZXBvcnQvc2NyaXB0cy9vcHRpbWl6YXRpb24tcmVwb3J0LnNjaGVtYS5qc29uIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiZWM5ZDdlYjBlYjQ0ZjMxNzNiZWY1MGFlZTdhY2I4YTA2MjVhYWYxNzcwOGUwMjJmYmE5ZTIwZGVlNTE2OWQxZSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcHRpbWl6YXRpb24tcmVwb3J0L3NjcmlwdHMvdmFsaWRhdGVfcmVwb3J0LnB5IgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMWZjYmIyOWY5MGVkMGUzMjM5OWIxOTdmZTk4M2U1Zjk5OTY3ZTcwNWQ3NTVlZWVjN2Q3NjMwM2FmOGE4ZWNmYyIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vdXRwdXQtd29ya3NwYWNlLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNzMwYWE4ODYwODIyOGE4MTlkZmIxNjFiNWRkMzk0MzEwYTBmZmNhNmQ3M2NlNzVlYmU2ZDNmM2JhNzc5NTk2MCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9wcm9maWxlLXN0YWdlL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjQ3YTI2NDcyZDEyYTQ0N2M3M2QxYjEwNGMwNjllZTU0ZTRiMzQyMWUxZjQ3MDcwZWJhMGU0OGU0ZjY0NDVmMjMiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvcmVwb3J0LXRlbXBsYXRlcy9SRUFETUUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICIzYTcyNzI1ZTViMDFiY2Y4YzNhOTY5MGI3NWIyYzdhZjcyMjZhZmIzYTg5YmM0ZWUwMjE2ODZiYTZjY2Q1NmViIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3JlcG9ydC10ZW1wbGF0ZXMvb3B0aW1pemF0aW9uLXJlcG9ydC5kZXNpZ24tZml4dHVyZS5qc29uIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNDMxMmY4YWM5OWVjZDlhODY3OGQ5NTI5MTFkMmI4NzU4NTJlMDMwNjQyMzI1MmY0N2U3ZTZlZGQwYTUyMDcwOCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9yZXBvcnQtdGVtcGxhdGVzL29wdGltaXphdGlvbi1yZXBvcnQuZGVzaWduLWZpeHR1cmUubWFuaWZlc3QuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjJlNGVhZGJjMTUxM2U0NTJmMWQ0NWU1ZmNkZjJjMDJmY2Q1ZGNkNTUxMzJhZDQ5Mjc5YTVhODk5YTI1ZTdiOTUiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvcmVwb3J0LXRlbXBsYXRlcy9vcHRpbWl6YXRpb24tcmVwb3J0Lmh0bWwudGVtcGxhdGUiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI3ZmEyMzI1MjUzOTQwNmViNThmZjQ4MzFhZDc1ODIzNzY5ZTY3YzZhZGQ0YjJjM2QyYmU1NDIxMTEzZTc5YmE3IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3JlcG9ydC10ZW1wbGF0ZXMvb3B0aW1pemF0aW9uLXJlcG9ydC5tZC50ZW1wbGF0ZSIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImU5Y2MwNWY1YTFmYzY2ZTIxNDU2YTQ3MTA1NTllMDU2YWIyODNjZDZlMTgxZTRlZDk2OTBjNjM5MDgzZTE3NzIiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvcmVwb3J0LXRlbXBsYXRlcy9vcHRpbWl6YXRpb24tcmVwb3J0LnN0cnVjdHVyYWwtb25seS1maXh0dXJlLmpzb24iCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJiMTNlZmM0YjEyMGUwOWVmNThmMjFhNTc2YjQ5ZTA0MzAzOTM5MGVlNzliZTNhODFhN2RkODQ1MTE0NjBjMDk0IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3JlcG9ydC10ZW1wbGF0ZXMvcmVuZGVyX3ByZXZpZXcucHkiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI0MmNhNTkzNDYxY2NiZGQ5Y2RiZTc2ODRhZjRkZWVhNTMwNThhYzVjMTg5YmU4OTNhMDM4MzM4NjAzMjBjYjg4IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3J1bnRpbWUtYXJ0aWZhY3QtdG9rZW4tYnVkZ2V0Lm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiOTBkYjkxNWZlYmZlYzE0ZjNjMWZlNmM3Y2U5Y2QyNzhjNTRmN2VhZTc3YjcwMDFmMDRmYTYzMWNjM2NkMTdiZCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9zZXR1cC11c2QtcGVyZm9ybWFuY2UtdHVuaW5nL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjlkNzAxZjVjODVlMTgwNzlhNzc3MmI1N2M4ZTVkOWI0Yzk2NWNlYWZkMDQzYzU4ZjI4MDQ0YTA4MGVjYTJhYjMiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvc2V0dXAtdXNkLXBlcmZvcm1hbmNlLXR1bmluZy9yZWZlcmVuY2VzL2luc3RhbGwtYXNzZXQtdmFsaWRhdG9yLXN0YW5kYWxvbmUvUkVBRE1FLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMzU3NDQ4MmIyYTUwMzc2YzE0ZTY0YmUzNTkzNGMzMmNhZWU5M2VmNDJhY2IzMTBmYjgyNWFmMDFmZmVlOThkNyIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9zZXR1cC11c2QtcGVyZm9ybWFuY2UtdHVuaW5nL3JlZmVyZW5jZXMvaW5zdGFsbC1raXQvUkVBRE1FLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNTZjZGM0Njg0ZTNkZTYwODhkNmE2MjQ4ZmFiNDIwZGMxMWRkNTY3ZmM2OWJmNGZmZmU2ODdjZDdiZTllNGUwOCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9zZXR1cC11c2QtcGVyZm9ybWFuY2UtdHVuaW5nL3JlZmVyZW5jZXMvaW5zdGFsbC1zby1zdGFuZGFsb25lL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjQyYzcwOWFkMzNlMDdkOGU2NzA3ZDczYjZmNDI0YThmNmIwZTMzYmJmMDE0NDM2NmJhMDE4NDE3MDQzNWUxMWMiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvc2V0dXAtdXNkLXBlcmZvcm1hbmNlLXR1bmluZy9yZWZlcmVuY2VzL2luc3RhbGwtc28tdmlhLWtpdC9SRUFETUUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJmMGM4MjBiNDgzZDVmMGJhNTQzM2Y2NDNhYmI5OWY4NDI0ZTM4MGMxMGI1NzdlMjQ3ZmFhNjA1Y2QyZmUxZjIxIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3NldHVwLXVzZC1wZXJmb3JtYW5jZS10dW5pbmcvcmVmZXJlbmNlcy9raXQtZGlzY292ZXJ5Lm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMjEyMDk5NDVhMmFhNDFjZGFkZjdkZGVkNGRjOWZlOTdjZGFiZjJkZTljOGViMzI0MjYwMjNhODI0ODZlMjU5YyIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9zZXR1cC11c2QtcGVyZm9ybWFuY2UtdHVuaW5nL3JlZmVyZW5jZXMvcnVudGltZS1jb250ZXh0LWhlYWRlci5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjY3NjM1MTVkZjZkOTAxN2JkYWFlNjlmMzkyZWE4ZTMzYjRjODAxZDljYjkwNzc3YjIzNDExMGUyZWEwYmNkMTAiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvc2V0dXAtdXNkLXBlcmZvcm1hbmNlLXR1bmluZy9yZWZlcmVuY2VzL3J1bnRpbWUtcHJvYmUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICIxMmJkNDZkZDNiNjJhMmExNDUwYzcwZDUxMzQ4ZWYyOTQ0NTFhYWFjMzU5YjBhNWFmZDA5OTZjY2QyZGRmNjY5IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3NldHVwLXVzZC1wZXJmb3JtYW5jZS10dW5pbmcvcmVmZXJlbmNlcy9zdGFuZGFsb25lLXJ1bnRpbWUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJlODkwMjVhZmQ3OWUwNzA2NGRmODRmM2MxN2U4MDg3MTA2Nzc2OTQzNDM1NTA5NDE0MGEzOTI2MGRkNjRjYTQ4IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3NldHVwLXVzZC1wZXJmb3JtYW5jZS10dW5pbmcvc2NyaXB0cy9wcm9iZS1zbmFwc2hvdC5zY2hlbWEuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjI1YjA1ZjYwYzUwYjhlMzhjNDczM2FiODFjZTk2MGZiMWNmZjJjNDhjMmQ2NDYzMTAyZDdmNDU1ZGM1Yjc1MWYiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvc2V0dXAtdXNkLXBlcmZvcm1hbmNlLXR1bmluZy9zY3JpcHRzL3NldHVwLXByZWZsaWdodC5zY2hlbWEuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjA0MTQ5Mzg1OWU4OGE0ZWFjNmRjZWE4ODdiMmVlOTNiYjFlMzA1MTA5NWJlZTRiNWYyYjNkMzgyMDkwMjMyN2EiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvc2tpbGwtbWFwLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMTc0YjllNWY2MTIwZDBkOWI2MDc0NDM4MmExYjUxMTQ0OWEzODkyZmJkNTg1OTBhYzAxYWNjMWEzNDgzM2IzOSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9zby1ydW4tb3BlcmF0aW9ucy9SRUFETUUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI0ZmViZmJiNTNiYTcwNTYzY2VmODY3YzY4NDNjYzMxOGM5NmJhZWQ0M2ZmNmI0YjVhNzgyZWNiZTdlZDA1NTU4IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3NvLXJ1bi1vcGVyYXRpb25zL3JlZmVyZW5jZXMvYmF0Y2gtbW9kZS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImEyYjUwZmNiM2QxYTE2MTg2NzA4YjQ0NGMwM2VmODkxYjM1NjdmMjhlZDMxZWYyY2Q2NGJlYTFlNGI0YzhhZTIiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvc28tcnVuLW9wZXJhdGlvbnMvcmVmZXJlbmNlcy9jb25maWctZnJvbS1ldmlkZW5jZS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjFmNWQ1NGE4OWFjNDliMDQ3NjdmNDUzZWUzMTM2M2QzNzFiYzMwYTVlNjIxNDY3MGE3ZWJiMGFjM2FmZTg3YzMiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvc28tcnVuLW9wZXJhdGlvbnMvcmVmZXJlbmNlcy9pbnZvY2F0aW9uLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiZTNkNWQwMGM0YTNlYmMxNjk3NTI3MjJiMDZlNzMxNjUyOWY5NTQ3NjBhNmMxZWQ3MGNlMzc5ZGZlOWIyMzcwNSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9zby1ydW4tb3BlcmF0aW9ucy9yZWZlcmVuY2VzL29wZXJhdGlvbi1zYWZldHkubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJmNzA0NDI2NjZlMWY2NGMxMWVjMTY0Y2Q2MjZiZTkyZDg2NWFkODZlMTg3YWQ5NDYyODAyNzExZmM4NzdmN2FkIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3NvLXJ1bi1vcGVyYXRpb25zL3JlZmVyZW5jZXMvcGlwZWxpbmVzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiZGI0YjJkM2JhNjI3Nzk4MGMyNmY1ZWIwMTI4YTVhNmRhODRkMGMxMDdkMGQ1NDljZjkyZTNjNTQ2Y2VhOGEwYiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9zby1ydW4tb3BlcmF0aW9ucy9yZWZlcmVuY2VzL3NvLWNyZWF0ZS1wcm94eS9SRUFETUUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJlYjJkMzA0ZWRmZjJiZWU3MTMxYjIyY2QwYWM3NzczN2UzNTdkMTU2OWZkM2ExZDk5ZjJkMmY2NGE5ZGNkMGRlIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3NvLXJ1bi1vcGVyYXRpb25zL3JlZmVyZW5jZXMvc28tY3JlYXRlLXByb3h5L3JlZmVyZW5jZXMvYm91bmRpbmctYm94LXByb3h5LW1vZGVzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNTdlZThkZTk0NTMyYTc4OTkyZWI1MTc5MDY3ZTIzNDE5NjNhMzZiOWIzNWM2ZjFlNGYxYjljYjAzY2U0ZjZmZiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9zby1ydW4tb3BlcmF0aW9ucy9yZWZlcmVuY2VzL3NvLWNyZWF0ZS1wcm94eS9yZWZlcmVuY2VzL2RlY2ltYXRlLXN0ZXAtcmVjaXBlcy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjM3OTc3NjgyNTVmOTJiNTU1MDljMDJhMDMxNzhhYWJlYTQ4ZmFmN2Q1Zjc5YjNmMGEzZDk5MWY0ODMwNGY4MjIiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvc28tcnVuLW9wZXJhdGlvbnMvcmVmZXJlbmNlcy9zby1jcmVhdGUtcHJveHkvcmVmZXJlbmNlcy9kZWNpbWF0aW9uLXR1bmluZy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjlkMzhjYmNmMmMxNWZlOGYzZDI5ZTIzMjAyNjEzM2I0ZjkwNGVjOWE3Y2M0MjkxOGIyNWE5ZTNkZmU4YTY5NzciLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvc28tcnVuLW9wZXJhdGlvbnMvcmVmZXJlbmNlcy9zby1jcmVhdGUtcHJveHkvcmVmZXJlbmNlcy9wcm94eS1jb25maWctcmVjaXBlcy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjk2MGM0YjA4NWUxZDg3MzcxYzA2ODllNWNmNDc3MmEyODM4MTNmYWZkZTRkZWE4YzY2MzJmOTFmNWVjNTAzNzgiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvc28tcnVuLW9wZXJhdGlvbnMvcmVmZXJlbmNlcy91bml0cy1hbmQtdG9sZXJhbmNlcy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjc4OWFhOGUwYWQzOTY3NjM1NzVhZTk2MTcwYThhZGY5Yjg2YzBlOWE1ZTE5YjhlYjhmNDhhMWZlMmUxNTZlMjAiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXBzdHJlYW1zL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjkxYWRkYWFiODU5MzA4OTY3NDE0OTBjMzBmNzljMmQ0YWQwZTY5NTBlNDNkY2YzMGQ3ZDBmMDAyY2QwNDY2NmQiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXBzdHJlYW1zL3VzZC1vcHRpbWl6ZS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjZmYWQ2NzBkZjI3MWIxN2UxMjlmN2U2MzVmOTQ4ZDQ1MTYxNTQ4N2Q1NGFmYTkyNDFkMzRlZDVjNWExZjQ0YjMiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjNkYWMxMTM4ZWViOTk3Y2RlOTU1MGVlNWY5MjM3ZWY0ZTFmODhjMGIwZWQxN2YwMTY2YzhlZDhmNGJjZDVmNTMiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3JlZmVyZW5jZXMvYXBwbHktcmVzdHJ1Y3R1cmUvUkVBRE1FLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNzUzMDE5MGM5MDc0YzQwMjkwOGE2YzhhMzAyNzRlODg0YTU0MzdkNmM4MmJiMjc1MDhiZmM0YThkMGUwNzI1MiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvcmVmZXJlbmNlcy9hcHBseS1yZXN0cnVjdHVyZS9yZWZlcmVuY2VzL2hpZXJhcmNoeS1kZWR1cGUtcmV3cml0ZS10b29sLXNwZWMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJkNDJmNTBlMDUwMjQwOTJiN2MzYzMzM2QzNmNhYjk4YzFkMDUwYTc3MDE1YmMzNzQ5YThkMTQyNTA3YzliMGExIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1zdHJ1Y3R1cmUtYXNzZXNzbWVudC9yZWZlcmVuY2VzL2FwcGx5LXJlc3RydWN0dXJlL3JlZmVyZW5jZXMvcmVmLXJlbWFwLW1vZGUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICIzMDBhOGE4NzVmZDZmY2Q5ZDFiNzljNDAyNjRiNzdiZGQ3YTMzYjkzZWIxMWJlZWI1Mzk3ZGFmOTM1ZGYwNjI3IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1zdHJ1Y3R1cmUtYXNzZXNzbWVudC9yZWZlcmVuY2VzL2FwcGx5LXJlc3RydWN0dXJlL3JlZmVyZW5jZXMvcmVzdHJ1Y3R1cmUtbW9kZS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImI5NjVjMDQxZTg3NTViNWViMGNiMjAxODA2ZTk4MGFlMmIyMzE3ZWE1MjExNWU1YmMyMGI5MTc3OGEwNDc3YzYiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3JlZmVyZW5jZXMvYXBwbHktcmVzdHJ1Y3R1cmUvc2NyaXB0cy9hcHBseS1yZXN0cnVjdHVyZS1tYW5pZmVzdC5zY2hlbWEuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjEyMDYxYTgxNmRiMjE3ZTA2YWI4ZDBlZTViMjVhZGE5OWJmMTQxYmNjYWFlMTE2YmQzZDJjNjU0ZjFkN2ZlNDYiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3JlZmVyZW5jZXMvYXNzZXQtc3RydWN0dXJlLXByaW5jaXBsZXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJjN2I2YTllMDdhN2M1MjJkNTg0YWZlMzNlYzk3YTZkN2RjNmVlZTM1MzJjMjY4YThhZWZhMDU2YzBiZDMzOTNmIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1zdHJ1Y3R1cmUtYXNzZXNzbWVudC9yZWZlcmVuY2VzL2NvbXBvc2l0aW9uLWF1ZGl0Lm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMjYyMWE2OWEzZWJjZWE0ZWVhZjlkYjdjMzJlZjA0Y2MzYzYyNWUwZDAwNTcwNGEyNTQ3YTUyNGNkNmI5NTRhNSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvcmVmZXJlbmNlcy9mYWN0b3J5LWxldmVsLXN0cnVjdHVyaW5nLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNWIzOTNlZjAyMTNkZWFiZjNhNTdkZmM2MjdjZDkwMTNlNWEyOGY2YmIxMTMyOGQxMTBmYTc3MzY4Y2IxOWY2MiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvcmVmZXJlbmNlcy9pbnN0YW5jaW5nLXJlYWRpbmVzcy9SRUFETUUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI1YzJjNWMzNWQ3ZWI5YjYyMzQxMjZjZTQzMGQwOTIwZmNmODI3MDkxNGM3OTQ5MTY5NWE3N2UzZGQzMzYwYmNkIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1zdHJ1Y3R1cmUtYXNzZXNzbWVudC9yZWZlcmVuY2VzL2luc3RhbmNpbmctcmVhZGluZXNzL3JlZmVyZW5jZXMvaW5zdGFuY2luZy1ndWlkZS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjc1NTM4NTllZTE1YzU3ZDk0OTlkZDZjZWNhMzE2NzAyZTU0MDkwM2VjMGIzM2EzYTU1MTY3YWI3ZGViMzYwMDkiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3JlZmVyZW5jZXMvaW5zdGFuY2luZy1yZWFkaW5lc3MvcmVmZXJlbmNlcy9pbnN0YW5jaW5nLXRyYWRlb2Zmcy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjgzYWM0ZWNjY2YxYjVjZDc3ZDhkZDljMDVkMWRiMjYyNTE3NDE1ZWFlNDQ5MzMwNDNjY2MzYzJmNjdlYTcxZDAiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3JlZmVyZW5jZXMvbGF5ZXItaGVhbHRoLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiM2JjOWE0NDg2YzFkYzU3NGZmNWYzNmMyYTRiYjQyZTk1OTJiNGUyNmNlNTk3ZGE0Nzg1Mjc2MjU4MzBiYTI5ZCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvcmVmZXJlbmNlcy9vcHRpbWl6YXRpb24tdHJhZGVvZmZzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNjEyYTZiYWIxM2EwYjI4ZDliM2ZkNTg3OWM3MzExMDY3ZjUzMjFjNzk5MTY2ZjgwNTFjYjZjZDY1ZjMyYWMzZSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvcmVmZXJlbmNlcy9yZXN0cnVjdHVyZS1kZWNpc2lvbi9SRUFETUUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI2NGRmMmE5NjAwOGFjYzJiODRhOTgwY2U1Y2ZkY2Q3OWY2MDJjNTIxYTBmYWVhZGYxYmMzNWZkMWFhZjhiNDRkIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1zdHJ1Y3R1cmUtYXNzZXNzbWVudC9yZWZlcmVuY2VzL3VzZC1lZGl0LXRhcmdldC1wbGFubmVyL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjVjMDFlM2VhYTUzNmNmMTFiMzA3MzQwOTE2YTk5ZDJiNTUzMzYzNTk0MGJiMTI0NjU3Y2Y2OGZlNmU4MmZhNmQiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3JlZmVyZW5jZXMvdXNkLWVkaXQtdGFyZ2V0LXBsYW5uZXIvcmVmZXJlbmNlcy9vdXRwdXQtc2F2aW5nLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiZWIyMjExYjMyMzQxOGFmMzdiZThlYTIwNzYzZDliYTRiN2RlNjE1NjJmODM5NWFjNjgzZjk4ZGUzMTg2MDU5YyIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvcmVmZXJlbmNlcy91c2QtZWRpdC10YXJnZXQtcGxhbm5lci9yZWZlcmVuY2VzL3ZhcmlhbnRzLXBheWxvYWRzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMzE4NGNiMzcwZWI3MDQzZTYxZTQ2MzdmZjRmNzBiZDg5ZDJhMjI4YTYzNWUzNmFkOGYzZDcyOWZkODRmODZkNSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvcmVmZXJlbmNlcy91c2QtaGllcmFyY2h5LWRlZHVwZS1jYW5kaWRhdGVzL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImYxN2Y1NGE1MDg1MzM3ZDcxNTVlYWYyOGUwNzVjNzliNDgxZmYyYTRjZjQ0YTM5MGI4Y2RjNDRjOTM5YzE2ZjQiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3JlZmVyZW5jZXMvdXNkLWhpZXJhcmNoeS1kZWR1cGUtY2FuZGlkYXRlcy9yZWZlcmVuY2VzL2luc3RhbmNlLWNhbmRpZGF0ZS1maW5kZXItc3BlYy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjI2NTFmZjQ2ZDhmYmZjZWVhOGFhMmE3OTA4OTc5NjM2ODBkZGE5MjkzOWQzZjY0ZTEwNGFjODM1ZGNkMDZkMWIiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3NjcmlwdHMvYXVkaXQtcmVwb3J0LnNjaGVtYS5qc29uIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMWM4Zjg5YzUwMWYyNzE0NGIxOGM0ZjZhZjNiYTMxY2Y1Yzc3OWExNmNhMjJiOTU0OTJlNTUyNjI0YzNhZGZjNSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvc2NyaXB0cy9vcHRpbWl6YXRpb24tcGxhbi5zY2hlbWEuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImQzZWJlZjQxMTE1MmRjYWFlYzFiN2VlNjQxOWMyZDQyOGFhY2FlNmI1ZTkzOTE1M2M1YTI4ZmQwYzJlMTNlNzYiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3NjcmlwdHMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50LXJlcG9ydC5zY2hlbWEuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjY4MmEzZjhlYjQ5ZTI1MTI4MDU0NTYzZjA1YjU3NTVmMWEwNTlhYmIwM2I1YjVkYmNlMmRhOWJmZmYzZmZlOTIiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXZhbGlkYXRpb24tcnVubmVyL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImJkNzBiOTRkMDY1NTQ1ZDA0ODFjZGMwZGMzYmVhZTlhMTA2YTliYmMxYzJkNTQzZWUyMjU2MTBiMzYxZGFiMjciLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXZhbGlkYXRpb24tcnVubmVyL3JlZmVyZW5jZXMvc28taW50ZXJwcmV0LXZhbGlkYXRvcnMvUkVBRE1FLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiZTk0Yzc5MTIyYjY3OTZiMWExODNmMGQ2NDU1MTM0MWMyZDAwYmZkZDAxMWQ3NmJkZTNhMDc5N2RiNDIwYjVhMCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2QtdmFsaWRhdGlvbi1ydW5uZXIvcmVmZXJlbmNlcy9zby1pbnRlcnByZXQtdmFsaWRhdG9ycy9yZWZlcmVuY2VzL2ZvbGxvdy11cC1xdWVyaWVzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiYjMwMzRjNDJjNWVlNjRjYmZmN2I3YmI4ZjRiMzk5ZTQ1ODQ3NDVkNDEyYTc3ZGFlMWY0OGIyMDg1MjhlNTdmMCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2QtdmFsaWRhdGlvbi1ydW5uZXIvcmVmZXJlbmNlcy9zby1pbnRlcnByZXQtdmFsaWRhdG9ycy9yZWZlcmVuY2VzL3J1bGUtcmVmZXJlbmNlLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiM2IzM2YwYTY4YTE3ZDgyNjk5NGQ3YjczZDc5NzgxODA5MzRlYTc1NmQyYWNjZjc3NzBiZTFiNmNlOWU4MmVjNiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2QtdmFsaWRhdGlvbi1ydW5uZXIvcmVmZXJlbmNlcy9zby1ydW4tdmFsaWRhdG9ycy9SRUFETUUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJmNjE0NDIyMTU2YjdiMDQ0Njc1YmM4YzUwZTBmNDNiMTY3NDE3NmRjMzA2Mzg5YTZmMGZmODc2YzE0MjY5YmI2IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC12YWxpZGF0aW9uLXJ1bm5lci9yZWZlcmVuY2VzL3NvLXJ1bi12YWxpZGF0b3JzL3JlZmVyZW5jZXMvaW5mcmFzdHJ1Y3R1cmUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJlNTNlNjg1NzY1NTYwMGRjNGFjMTg1MjE5M2E2MmVmYmYzMzkxMDNmNmRjNWRhNTZmNmY5ZWE3OWViNDRmYmVjIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC12YWxpZGF0aW9uLXJ1bm5lci9yZWZlcmVuY2VzL3ZhbGlkYXRlLXVzZC1hc3NldC12YWxpZGF0b3IubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJmODhhNGQzZWRhMjk5ZDg2NzAzMDgwMGY3NGIxZDgwNmZmMmI4ZDJkMDM1NTNiNzJiYTIzMTYwNWQzY2ViMDViIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC12YWxpZGF0aW9uLXJ1bm5lci9yZWZlcmVuY2VzL3ZhbGlkYXRvci1jb25jZXB0cy5qc29uIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMmZkYWE0M2YyODczZGU2MTM2NTQwZGI5ZTUwNmM3ZWIyNmI0ZWYwNWZkMDY5NmY5YjBkMjFmNzJkNzY2MzMxMCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2QtdmFsaWRhdGlvbi1ydW5uZXIvc2NyaXB0cy91c2RfdmFsaWRhdGlvbl9leGVjdXRvci5weSIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjljOTlhZjI3OWUyZDMwZjg3MGZmMjk1ZGQ3N2ZkYzBiNjA1NGFmMzAxMmEyZDI3ZWRkOGZkZTYyZjA0M2E0MDgiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXZhbGlkYXRpb24tcnVubmVyL3NjcmlwdHMvdmFsaWRhdGlvbi1yZXBvcnQuc2NoZW1hLmpzb24iCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJmNWNiNGFlN2Q5ZDc5NWYzYjgwYWFiMmJkMWNiYjZjMzc3NzNiYzJmMTVkZTYzNmFmMTczYmQxOGI0NGFjYTAxIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC12YWxpZGF0aW9uLXJ1bm5lci9zY3JpcHRzL3ZhbGlkYXRpb24tc2NvcGUtbm90ZS5zY2hlbWEuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImNmNTI1ZWQ2MzBmZmMzYTAyYzgwOTBiZDQ3NTVkNGQzNDBmYTEyN2JlMDMyNWIyYmY3OTkwMGE2YTc4MWRjYTciLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXZhbGlkYXRpb24tcnVubmVyL3NjcmlwdHMvdmFsaWRhdG9yLWNvbmNlcHRzLnNjaGVtYS5qc29uIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiZTcyOTYxM2JhYzRjZmRkZmYyY2Y3Njc2NDAxM2Y2ZGYwOGQyOGY2ZjJhYWVjMzM5OTU1NTRkNTg1MTllNTc1ZSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy93b3JrZmxvdy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjc3NWVmOTMyMmQzMzBiMmRlZjAzZTNjNzRjOGRjMzNjZmRhNDExY2Q5NDk0YmEzYmY4NDUxOGQ4MWQ3NWU0ODQiLAogICAgICAgICJuYW1lIjogInNraWxsLWNhcmQubWQiCiAgICAgIH0KICAgIF0sCiAgICAic2VyaWFsaXphdGlvbiI6IHsKICAgICAgImlnbm9yZV9wYXRocyI6IFsKICAgICAgICAiLmdpdGh1YiIsCiAgICAgICAgIi5naXRpZ25vcmUiLAogICAgICAgICIuZ2l0IiwKICAgICAgICAiLmdpdGF0dHJpYnV0ZXMiCiAgICAgIF0sCiAgICAgICJtZXRob2QiOiAiZmlsZXMiLAogICAgICAiaGFzaF90eXBlIjogInNoYTI1NiIsCiAgICAgICJhbGxvd19zeW1saW5rcyI6IGZhbHNlCiAgICB9CiAgfQp9","payloadType":"application/vnd.in-toto+json","signatures":[{"sig":"MGUCMQD4bjufbPKiPuqBBuobdiE76lbwM7nBOvqJa0ikxsXnFYD98+sHlSiXRPDETQwP0AsCMDJuG2+rsHKufVj2CZr6vrS/BpfyUCsOoPn8ua++wEykO1y1YtYqGge8hKCH2MwedA==","keyid":""}]}} \ No newline at end of file +{"mediaType":"application/vnd.dev.sigstore.bundle.v0.3+json","verificationMaterial":{"x509CertificateChain":{"certificates":[{"rawBytes":"MIICgzCCAgmgAwIBAgIUKIyS7SxNteQIiWzK1dWj85E6520wCgYIKoZIzj0EAwMwVTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjEpMCcGA1UEAwwgTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBJQ0EgMDEwHhcNMjYwNDAxMDAwMDAwWhcNMjgwNDIyMTUzMzA5WjBUMQswCQYDVQQGEwJVUzEbMBkGA1UECgwSTlZJRElBIENvcnBvcmF0aW9uMSgwJgYDVQQDDB9OVklESUEgQWdlbnQgU2tpbGxzIFNpZ25pbmcgMDAxMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEYoRM9bQl/dGlwSRNi6bTpIJUXH8Nv9GciP6LSflJYYMLCc296kpyuTSsk5ddbAWiDcFX3C/ydX3jwc+qCLYP6uHy9XphyLjOQ27Yb2J6rBLVtRBS1mgGco/Gr7fL6ODco4GaMIGXMB0GA1UdDgQWBBRQ/5ZW3nJ6lmo9SVk7I15o7UGmpTAfBgNVHSMEGDAWgBRPGpILxMBBleJSsBGjrMKsby1CgjAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDA3BggrBgEFBQcBAQQrMCkwJwYIKwYBBQUHMAGGG2h0dHA6Ly9vY3NwLm5kaXMubnZpZGlhLmNvbTAKBggqhkjOPQQDAwNoADBlAjAUygu/GiOCIXrgGr4SmLgeEVDcEitfFUv7ALbvLVGVyMysB3mxmO/uInZfXzWcJZsCMQDxuoxj4ZmO30jhkPIcCxGFCOvnUsnfU3TfGcouYm4M6iRpbKvtVnHPiy4bi6pcKf0="},{"rawBytes":"MIICiDCCAg6gAwIBAgIUZsIuSv9NkpJCNqtYEfCouVv5BzowCgYIKoZIzj0EAwMwUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTAgFw0yNjA0MDEwMDAwMDBaGA85OTk5MTIzMTIzNTk1OVowVTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjEpMCcGA1UEAwwgTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBJQ0EgMDEwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAASI72cR3ctKGg4VWnB3bNja6g1Z2PnOmFEopkPof+QeIcPk9rT+g9MjJnq51EQXL93a7C2GJ9J985G4o2V85VD7wJ1RaXhluHW2rf3y8bQGeAYaKMr5s/hUgn+M3/9WlWejgaAwgZ0wHQYDVR0OBBYEFE8akgvEwEGV4lKwEaOswqxvLUKCMB8GA1UdIwQYMBaAFItnoAjjfuCEUvzyvWyI2vOGvwPjMBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYDVR0PAQH/BAQDAgEGMDcGCCsGAQUFBwEBBCswKTAnBggrBgEFBQcwAYYbaHR0cDovL29jc3AubmRpcy5udmlkaWEuY29tMAoGCCqGSM49BAMDA2gAMGUCMQCeIMMfAbyzPDacw2MxG+Yt1cikrJX/DVxiGfXuHmkkXn6VgSzE79+lkqDErpVO2gYCMCNEColOyvUvkzZGUEI1hQ3PfMgi3FIo9tHoBKMw4/wGBLFpu/0ubtmbBXM6/UMOEw=="},{"rawBytes":"MIICRTCCAcygAwIBAgIUeJdY3rV86EdvFmG7L8LJBsyQFYkwCgYIKoZIzj0EAwMwUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTAgFw0yNjA0MDEwMDAwMDBaGA85OTk5MTIzMTIzNTk1OVowUTELMAkGA1UEBhMCVVMxGzAZBgNVBAoMEk5WSURJQSBDb3Jwb3JhdGlvbjElMCMGA1UEAwwcTlZJRElBIEFnZW50IENhcGFiaWxpdGllcyBDQTB2MBAGByqGSM49AgEGBSuBBAAiA2IABAYpiXCDjJ9NT2eSDhyHJVSw1Tbze18cGG2F/578oWvHxg23eQAhNRYdq88i1iOshZSO6C29doKui5Xpmo/7Ctw9Sx4PP2RzOmIuOLCuTdNtKcTRwi4GEsd5BAFvWj42M6NjMGEwHQYDVR0OBBYEFItnoAjjfuCEUvzyvWyI2vOGvwPjMB8GA1UdIwQYMBaAFItnoAjjfuCEUvzyvWyI2vOGvwPjMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgEGMAoGCCqGSM49BAMDA2cAMGQCMCwtAjWLaNwgGWNCgdyNoTyvNhqWRECRJV2r3+7w8g0PL6NHLOsbkgE09BH95h8XlgIwTaQmbbUh2ChAJ5TA1wRiVDnCcvbzHlZl2jM2FcwQQZlk19LOAbyGMRixbu2Ww/rj"}]},"tlogEntries":[]},"dsseEnvelope":{"payload":"ewogICJfdHlwZSI6ICJodHRwczovL2luLXRvdG8uaW8vU3RhdGVtZW50L3YxIiwKICAic3ViamVjdCI6IFsKICAgIHsKICAgICAgIm5hbWUiOiAib21uaXZlcnNlLXVzZC1wZXJmb3JtYW5jZS10dW5pbmciLAogICAgICAiZGlnZXN0IjogewogICAgICAgICJzaGEyNTYiOiAiMjE0MzBmODU1Y2ExODQ3Yzg0ZjFhOTU0YmYyZWFhYmE4ZDlhOGQ2NGVlN2I3NzhlZmJhNWI2YzAzYTNmYWI1MSIKICAgICAgfQogICAgfQogIF0sCiAgInByZWRpY2F0ZVR5cGUiOiAiaHR0cHM6Ly9tb2RlbF9zaWduaW5nL3NpZ25hdHVyZS92MS4wIiwKICAicHJlZGljYXRlIjogewogICAgInNlcmlhbGl6YXRpb24iOiB7CiAgICAgICJpZ25vcmVfcGF0aHMiOiBbCiAgICAgICAgIi5naXQiLAogICAgICAgICIuZ2l0YXR0cmlidXRlcyIsCiAgICAgICAgIi5naXRpZ25vcmUiLAogICAgICAgICIuZ2l0aHViIgogICAgICBdLAogICAgICAibWV0aG9kIjogImZpbGVzIiwKICAgICAgImhhc2hfdHlwZSI6ICJzaGEyNTYiLAogICAgICAiYWxsb3dfc3ltbGlua3MiOiBmYWxzZQogICAgfSwKICAgICJyZXNvdXJjZXMiOiBbCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJmZDg1YTI2MGRmY2FlMjFkMDY0MWY2YWY4MDBlMDI4ZTBlZTQwMzI3MzdlYWNkMWVmZmY5ZDcwZThmM2EzZmJhIiwKICAgICAgICAibmFtZSI6ICJCRU5DSE1BUksubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJiYTE1NmRiYTNhNDE0MmFhYjgzYjI4MTYzODNlODdhYWRmZWE2OTg4NTVkN2VmYmU3YTA2MTEyMDc0OTcyNjE1IiwKICAgICAgICAibmFtZSI6ICJTS0lMTC5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjdiMTk4NTZhMjU0NTVjNzAzNmYxODViOTJhNzg0MzU2OTcwMTdlODllNTBiOTc2Mzg4MWQxMzA3ZTg5ZTNkNjMiLAogICAgICAgICJuYW1lIjogImFnZW50cy9vcGVuYWkueWFtbCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjAwZjgwMGNhM2JmMWYxNzQ3YzI4NWRlMjAyNmMxOWUwNzA5YjkzOGI4YjU5MWQxOTcyYTMzMDg0MWVjNjdhMWIiLAogICAgICAgICJuYW1lIjogImV2YWxzL2V2YWxzLmpzb24iCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICIyOWNkYjlkYmNmYzExYjJmZmQ3MTMyNzk3NTBkY2Y5Zjg2NWVkNjEzMGM1MDQ1NTE4ZDViMDJhNjE2MDBjNTNlIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL19zaGFyZWQvc3RhbmRhcmQtaW5zdHJ1Y3Rpb25zLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiZWI1ZWQ0ODk2NzdkNWRkMTJmMDUxZWU4Nzk2ZWVjZjM2MWU2NTExNTJkMjI3MjM5YmRhNDNmODRkN2UxODY5NSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9fc2hhcmVkL3N0YW5kYXJkLW91dHB1dC1mb3JtYXQubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI3ZGRjY2FlMDc5M2ExOWUyZmNmNTZmMmI1N2FmNzBjMzUzMTVkMTZjZjViMjM0YzFkN2I5ZjE5ZDVkMjYzY2Q5IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL2NhZC1jb252ZXJzaW9uL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjg1YmZmNjE2MmU2OTdlOTc5MjUxZjFiYjViZTJmODdiNDcxNTc5MGU5ZTQ0ZTI2YTJkOTI5ZWJiZDJhYjNmYWUiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvY2FkLWNvbnZlcnNpb24vc2NyaXB0cy9jb252ZXJzaW9uLXJlcG9ydC5zY2hlbWEuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjc5N2VkMDQxZTc1ZjFiNTk3MTdkNzU5MTAxN2YzMWQzZWFiNDZlOTJjY2E1NjQ0YzVkMWE2NzMwNzMzNTI2ZGMiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvY29tcGFyZS1wcm9maWxlcy9SRUFETUUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI1ZGRkOTVmY2Q2NjliMDM3NDg0ZTU5ZjY1MzA5MjBmYWIzZDU5YTgxNDY5YTBjYjE4ZmY1MzU4ZGZiODI4Yjg4IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL2NvbXBhcmUtcHJvZmlsZXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJkNjY2OTcxODA2ZjA5NDYyODIyNTE5ZjU0ZjVlNGYzOWRkMTQ1Yjg4MWVhNjk2ZmMzY2RiNjFkNmQ5ZWNmMzgwIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29tbml2ZXJzZS1hdXRoZW50aWNhdGlvbi9SRUFETUUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJjZjYzMWZjMDZmMDc3M2M1YzIxM2RiYmUwM2ZkZDM5OGUyNDYyNmZlOGY4MjUzZDlhYjBmY2ExZmU0M2YzNDQ0IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvQ0xBU1NJRklDQVRJT04ubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI5ODljOTE0ZDI2Zjk0NjllODhiZDFhN2YyODBkZGE0ODg3Yzc0ZWNjZGY2YTFhMjAwMzY4NjAzN2VlOTUyNDIwIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvRVhFQ1VUSU9OLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiZDI5ODM3MzMyNjIzMzk5NTg3YmRlMmY5MWZlMWFhNWU2ZWQ4NTFiZWY3YzFlNjJhNTljNmVhODg1Zjg4N2UyOSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjVkMjA0OTc4MWZhYmMwMmQxNmM5NjM3MTg0MGNmNDg2ZWI2ODY2NmJmOTExOWRmMWFhMGE3MWY3ZTU4NDc2ZDEiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9vcGVyYXRpb25zLmpzb24iCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJlNWMxOTE3YjczYmIzMzkzNTRiNjEzNzA4MjdkODFjNDQ5YjBmZTU4MWVmNTFlZjMwNGExMjQ3MWM1NzkwZTcwIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wZXJhdGlvbnMvcHJvYmUtc25hcHNob3RzL3VzZC1vcHRpbWl6ZS0xLjAuNC5qc29uIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiZjkxMmEzNzQ2MmYxMGM4MjM4MzZkMmY4MzM5MmQ5NjIwMjZkYWMwNzQyNGVkMTA1YmJiZGY0NWViZDU0ZTMwNSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcGVyYXRpb25zL3Byb2JlLXNuYXBzaG90cy91c2Qtb3B0aW1pemUtMS4xLjEuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjhmZDRmMjE1OGI3N2RhNTU5MjEwN2VjN2QyYzU4YTUzZjNjMDIxMzdmM2VlYmMyNTg4NWYyOWM5MDBmOGMwZjMiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3BlcmF0aW9ucy9zY3JpcHRzL29wZXJhdGlvbnMuc2NoZW1hLmpzb24iCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJkZjYzNzk5NzBlMWJhYWJhM2Y2OTA5ZWZlMTc5ZTRkOTFkZGFlNmM5MGUxZTlmNjRlYjdjYzhlODk4YmY0ZWNlIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wdGltaXphdGlvbi1yZXBvcnQvUkVBRE1FLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMjgwYjlkMmY3YjJiYTEwY2NkY2U5NzQ2NTY2OWM4YTZjNTY2YzRhZDE0NjNlYmQxNWU4YmQ0MjM3NWEyZTlmZiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcHRpbWl6YXRpb24tcmVwb3J0L3JlZmVyZW5jZXMvb3B0aW1pemF0aW9uLXJlcG9ydC10ZW1wbGF0ZS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjFjYzM0MzEzZTYwZDdhNzZhNmFlNDAyNWU2NjU5NmM1ZmI2NzVmMzBkNTI4N2I4NDc3ZTMzYWM4OGM0NjU2OTciLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3B0aW1pemF0aW9uLXJlcG9ydC9zY3JpcHRzL2Rlc2NlbnRfY29udmVyZ2VuY2VfY29tbW9uLnB5IgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNTIwYzAxMGFkYWQ0YWZiMWFiZTNiNTM0ZWFmMjg3ZjliZmViYmI4M2RiYThmY2ZhODNlODdlMTk1YTMzNTlhZCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9vcHRpbWl6YXRpb24tcmVwb3J0L3NjcmlwdHMvb3B0aW1pemF0aW9uLXJlcG9ydC5zY2hlbWEuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjg1YzFmMzE4NDc5ZGU1YTZiYzVhNzMyNDgyOTJkNDQ2MzQxMDdlYWUyNTNkMzc2MmU2MzhhODBhOThhYTFkZGIiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvb3B0aW1pemF0aW9uLXJlcG9ydC9zY3JpcHRzL3Rlc3RfdmFsaWRhdGVfcmVwb3J0X2Rlc2NlbnQucHkiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICIxODgzZDJjZThkZjkwMjc0ODM4MjUwMWFlYjRiNjJhYTdhOTI5NThmNmJkZWFlOGJhMzRmNDA1NGQyYWFiOTE4IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL29wdGltaXphdGlvbi1yZXBvcnQvc2NyaXB0cy92YWxpZGF0ZV9yZXBvcnQucHkiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJkN2RjODQ0MTY2NmNmOWI3YWY4ZjEzZTRmNjYxNGQ4NDlmYTVhNmUzZTFjNmY0ZTY4ZjE4YWY2ZjcyMjRlZGFkIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL291dHB1dC13b3Jrc3BhY2UubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJlN2JjZDZmZjM3MDU3YTQ1NGQ5MzU5YjJkYzBiOTQzMmM3ODA3ZTQ2ZTA1OWVlMmU5Y2I0ZmZkNmM5MTUwYzcwIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3Byb2ZpbGUtc3RhZ2UvUkVBRE1FLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiYzcyYTk0NTVjMTNlMDUyM2VhOTY4NDBlOWYzMGMwMTQ1MzEyNTI0ZThhM2FhNGQ1ZjExYzUxZDFkN2EwZmI5OCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9yZXBvcnQtdGVtcGxhdGVzL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjQwNWQ3N2MxODUwMTZhMDgwMTRhYjA1OTE1OWNiZWUxYzg0YTAwNGMzNGJmNzFkODlkMTY1MmNjMTY2YWE5ZWMiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvcmVwb3J0LXRlbXBsYXRlcy9vcHRpbWl6YXRpb24tcmVwb3J0LmRlc2lnbi1maXh0dXJlLmpzb24iCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICIzODA3MjAyYzU2NWM3NjhhNThhYTNlOGFmNmY2MjY2N2FjYjYyMTc5ZjY0YmEzNDc2ZWE3ODNhYTdmNDYzODk5IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3JlcG9ydC10ZW1wbGF0ZXMvb3B0aW1pemF0aW9uLXJlcG9ydC5kZXNpZ24tZml4dHVyZS5tYW5pZmVzdC5qc29uIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMzAzNDg4ODk2ZmZiMGFjNzJhNTZkOTA2ZGZlNmE4MjM3ZTg4M2VhODE1OWU5NGMzZDhiZWFmNTNmNTdhMDI2NCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9yZXBvcnQtdGVtcGxhdGVzL29wdGltaXphdGlvbi1yZXBvcnQuaHRtbC50ZW1wbGF0ZSIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjc1NjRkODZmODFlZmFhODE0MjE1MTA3ODdjYWRiOWJjMDVhMWU2YzI2YTVjY2Y0YTJiNjZiZDYzMmY2YzljOTEiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvcmVwb3J0LXRlbXBsYXRlcy9vcHRpbWl6YXRpb24tcmVwb3J0Lm1kLnRlbXBsYXRlIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNjcwNzIyNTI2Y2Q4ZWUxMTZmMDU5NmZjYTgxMDlmODc2ODhhM2EzYWExMDg1NTZhYTBiYTMyOWNkNDNkOWM4MyIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9yZXBvcnQtdGVtcGxhdGVzL29wdGltaXphdGlvbi1yZXBvcnQuc3RydWN0dXJhbC1vbmx5LWZpeHR1cmUuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImIxM2VmYzRiMTIwZTA5ZWY1OGYyMWE1NzZiNDllMDQzMDM5MzkwZWU3OWJlM2E4MWE3ZGQ4NDUxMTQ2MGMwOTQiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvcmVwb3J0LXRlbXBsYXRlcy9yZW5kZXJfcHJldmlldy5weSIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImY1NmYzZGY3YmRkNjlhYWEwYmY3MGRjZDgxNzQ0YTBiZGQ5YTA1YjU4MzRlZjkwY2I3Y2M1MjE2ZmZlZWFhNmEiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvcnVudGltZS1hcnRpZmFjdC10b2tlbi1idWRnZXQubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJhMDA5ZWM3MWQxMDY4NTVkMmZkZDU0MTViN2E3ZjJmNjEzMWE2NDUxMjkxYmU4MWM4MDFhMDZjOTYyMjZiOGJjIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3NldHVwLXVzZC1wZXJmb3JtYW5jZS10dW5pbmcvUkVBRE1FLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiN2NjYzc4Y2NmOWEyMTVmYjg1MDQ2NmI5ZDY1ODQzMGQxNWFmNTdiMGMyYzE3ZTg0NGNmOWE4ZjgwNDI1MDMxMyIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9zZXR1cC11c2QtcGVyZm9ybWFuY2UtdHVuaW5nL3JlZmVyZW5jZXMvaW5zdGFsbC1raXQvUkVBRE1FLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNTQ3ZDY4MzU1NWU1MGFhY2Y4Y2NjZDM2YzQwZWQzNDE2YmRhYjM4YjMxMDdlZDFhYWFlMmI4OTRiMGM1YWFhMiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9zZXR1cC11c2QtcGVyZm9ybWFuY2UtdHVuaW5nL3JlZmVyZW5jZXMvaW5zdGFsbC11c2Qtb3B0aW1pemUtc3RhbmRhbG9uZS9SRUFETUUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI2NDFiNTM2NGI0ZDMxOGRiZDlmZDc3N2Q2NjdiZTgwYzg0OTBiOTBhM2Y2YzdhN2JhZjMyNDEzNTNjOTE2YTQ4IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3NldHVwLXVzZC1wZXJmb3JtYW5jZS10dW5pbmcvcmVmZXJlbmNlcy9pbnN0YWxsLXVzZC12YWxpZGF0aW9uLW52aWRpYS1zdGFuZGFsb25lL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImViNzIwNjA1YWQ2OTI2NjI1NDkyYzFlZjJjZDhmMDU0NGNlMDFlMTgwY2MyNzdiZmFiYTc3MWNhY2RiMzFkMTQiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvc2V0dXAtdXNkLXBlcmZvcm1hbmNlLXR1bmluZy9yZWZlcmVuY2VzL2tpdC1kaXNjb3ZlcnkubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICIwNWQ5MzllNzczODVkMWFmNWJlOTY1ZjY0YjFmMjZkYTg3NWYyZDYwMjFlZDY5MTlmYjdhMWJlNWFjODE1N2I2IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3NldHVwLXVzZC1wZXJmb3JtYW5jZS10dW5pbmcvcmVmZXJlbmNlcy9ydW50aW1lLWNvbnRleHQtaGVhZGVyLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiM2Y5MmM3OTI4YzhlYTI0N2IwZjliMDNmZjU3NGZlMGQxZDIxOTNkNDNmOWEwMTNiNDI0MDI2NTI3YjM1NTg4MyIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9zZXR1cC11c2QtcGVyZm9ybWFuY2UtdHVuaW5nL3JlZmVyZW5jZXMvcnVudGltZS1wcm9iZS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjJlNWI4NmE4MmFmZGQ3NTgxM2Y4YWUwNjgxZmYyMzVmOTgzMWQzMmE3MDAxNjg4ODJhYTU2ODM5NjQzMGI3NzkiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvc2V0dXAtdXNkLXBlcmZvcm1hbmNlLXR1bmluZy9yZWZlcmVuY2VzL3NvLXZhbGlkYXRvci1hdXRvLXJlZ2lzdHJhdGlvbi5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjI0NzU5YWM5OGU3NTkzYThmZGJmNzNkMmY1Y2Q1NzI5ZTNhNmVjNjk0NjdjYTFkMTQzNTRhNmU5OWQ1NmE5ZDIiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvc2V0dXAtdXNkLXBlcmZvcm1hbmNlLXR1bmluZy9yZWZlcmVuY2VzL3N0YW5kYWxvbmUtcnVudGltZS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImRkNzMwYTVjYzc2Njk5NDlkMzA3ZTgwYTIzZjY3NWYyYjU1Mzc5NmFlNmFjMTAwYWM1NzI0YjRlNjliYjM5YzYiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvc2V0dXAtdXNkLXBlcmZvcm1hbmNlLXR1bmluZy9zY3JpcHRzL3Byb2JlLXNuYXBzaG90LnNjaGVtYS5qc29uIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiZmVjYzNkMjY2OTFlMTI2ZTgzZGZiMGE0NzhmOWFiMDAzYzlhODhmMWNlMTgxZmQ3OGI2ODU3YTU5MjUxNjgzMCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9zZXR1cC11c2QtcGVyZm9ybWFuY2UtdHVuaW5nL3NjcmlwdHMvc2V0dXAtcHJlZmxpZ2h0LnNjaGVtYS5qc29uIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiYzRmZDUyZTgxYWY3MDU4N2M0ZTQ1NWYyMGRmNzlmNjEzNTFlYzE0ZDg5MjgxYjI1ZDFiMDgyNWI0ODQ5ZTE0YiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy9za2lsbC1tYXAubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI1NDcxNDUyMGFlZGQ1ZTRkMDE4MzI4MzcwMjlkOTQ3OTBjMDI2NDBhYWU1NWMyZmMyZjAyNDQ1MjM2YTc3OWUzIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3Vwc3RyZWFtcy9SRUFETUUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJhNmMxZjIwZGY2NzU3ZGMyMDIyNWIyMWFjODU1MTIwZmNlZjRmMTAxMWRiNTFmYjI3YWYyYWQ2YzBmZDM3YjBiIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3Vwc3RyZWFtcy91c2Qtb3B0aW1pemUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJhMGMyNjcyNDVkZjlmMTY5MDlhYzBjYjg4NzViODA2YmJlOTdiMjE4MzhlOTgwZGM3MWJhYTM1NThlYTM2ZWJlIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1vcHRpbWl6ZS1ydW4tb3BlcmF0aW9ucy9SRUFETUUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI3ZTQxMjQ4ZjJhNGQxMTBjYzU1NTU4NDg1OTZlMDliNGYzYjYyYjRkMThmYWQ0OWFiZTMzMjA3ZmQxMzRhMjM0IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1vcHRpbWl6ZS1ydW4tb3BlcmF0aW9ucy9yZWZlcmVuY2VzL2JhdGNoLW1vZGUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICIyNWFlY2QyMmMxYjRmYWMzMDM5NTMxZWFlOGQ5ZWY2ZmExNzU3NzM5ZmZkZjlkNzRlNTg1YTdhN2UzMzU0OWJhIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1vcHRpbWl6ZS1ydW4tb3BlcmF0aW9ucy9yZWZlcmVuY2VzL2NvbmZpZy1mcm9tLWV2aWRlbmNlLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNDg0MzhjODg5YTI3Njk3N2VkNzI0MjQ3MWZkMWNiZjY4ZWU5MWQxNjExNjVlYzBjMjNmYTFjZWYwZTk5MzVmNyIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtb3B0aW1pemUtcnVuLW9wZXJhdGlvbnMvcmVmZXJlbmNlcy9pbnZvY2F0aW9uLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiN2RkYzBiZTFiYTdiNjRiOTE1NTNjZTFhNzEwYWE0MWIwMWQzYjAwYWEzZTgzNDA4NTk3Mzc5MjZlMDlhNjdmYyIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtb3B0aW1pemUtcnVuLW9wZXJhdGlvbnMvcmVmZXJlbmNlcy9vcGVyYXRpb24tc2FmZXR5Lm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiZTE3ZmYzNmIxYWI5MWYwM2UyMGJjNzczYjg4YTgwZjY0Y2I5NzE3MTcwZjZkMmQzMTJhMzM3MDM4YWY2OGQ2YSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtb3B0aW1pemUtcnVuLW9wZXJhdGlvbnMvcmVmZXJlbmNlcy9waXBlbGluZXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICIzN2NkNmYwZDM4N2Y3MzcwZjA1ZGEzOWViNDZhOTU4NGY0YTllN2FkMDIzYTRkNGY4M2I5NTgzZDkxNjE2Y2MwIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1vcHRpbWl6ZS1ydW4tb3BlcmF0aW9ucy9yZWZlcmVuY2VzL3VuaXRzLWFuZC10b2xlcmFuY2VzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMTc4YTU3N2FhMTAzMTZiOGUxY2QyNzU2MmYxOWVkYTJhMzAyYTlkZmJmZTM4MmQ2NzIwYzJjMGFiY2U1OTJhNCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtb3B0aW1pemUtcnVuLW9wZXJhdGlvbnMvcmVmZXJlbmNlcy91c2Qtb3B0aW1pemUtY3JlYXRlLXByb3h5L1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjY1NWEwODYxOWJmNjQ1NTEzZTlhM2Y0OWVkOGExZDYwMTY0YzJjYTEzYTVlYTE2NmRiNzc3NmIyZDg4ODczMzkiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLW9wdGltaXplLXJ1bi1vcGVyYXRpb25zL3JlZmVyZW5jZXMvdXNkLW9wdGltaXplLWNyZWF0ZS1wcm94eS9yZWZlcmVuY2VzL2JvdW5kaW5nLWJveC1wcm94eS1tb2Rlcy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImUyOGQ0YWFkMjcyZTM0ZDU2NjZhOTAxNTViNzBmYzcxOTBjOWJiMDJhZDk2MjJlMjM4YTE2ZmFmNzY5OGFjYzYiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLW9wdGltaXplLXJ1bi1vcGVyYXRpb25zL3JlZmVyZW5jZXMvdXNkLW9wdGltaXplLWNyZWF0ZS1wcm94eS9yZWZlcmVuY2VzL2RlY2ltYXRlLXN0ZXAtcmVjaXBlcy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjc1MjMwYTkxMmVhN2MxMTUwOGY4MTc5ZDllMGI2MzI4Mjk1ZGQwNzdmY2M2YzNhNjlhYjA5MzA3NzdmMzNhODMiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLW9wdGltaXplLXJ1bi1vcGVyYXRpb25zL3JlZmVyZW5jZXMvdXNkLW9wdGltaXplLWNyZWF0ZS1wcm94eS9yZWZlcmVuY2VzL2RlY2ltYXRpb24tdHVuaW5nLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMjYzYzAzYzJiMTg3MDBhMzA0Zjc0YWE1NmQ2NTlhYzFhNDVlOWZjNDEzNjYzMmJmYzA3MGIyNjRlNjEwZTk3NSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtb3B0aW1pemUtcnVuLW9wZXJhdGlvbnMvcmVmZXJlbmNlcy91c2Qtb3B0aW1pemUtY3JlYXRlLXByb3h5L3JlZmVyZW5jZXMvcHJveHktY29uZmlnLXJlY2lwZXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJmNmJhNmZmOGEyYWJjMzg0M2EwOTRmNmM1NzZhNjA4N2U4Zjg3NmYzZWYxM2E3ZTdiOWZlZjMyNWQ4ODFlYmFlIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1vcHRpbWl6ZS1ydW4tb3BlcmF0aW9ucy9zY3JpcHRzL2JhdGNoLXBsYW4uc2NoZW1hLmpzb24iCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI2YzgwZjUzZGZjN2NmYWU4ZmU5YTRjZWI4OTllOTQ3YjBkZjQ3NTU1NjM1NzI3NDA2MDY1MjEwN2VmNGE3ZmM0IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1vcHRpbWl6ZS1ydW4tb3BlcmF0aW9ucy9zY3JpcHRzL3J1bl9iYXRjaC5weSIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImVmOGM2N2NlNTgwNTc2MjA2NDFjMTNkOWE0NTAxMDllMTQ3Njc5ZjBmZWI2Y2EyNzMyOWVjNTY3NDJkZWRiZjIiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLW9wdGltaXplLXJ1bi1vcGVyYXRpb25zL3NjcmlwdHMvc3RhdHVzLnNjaGVtYS5qc29uIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiODVjMGVhYjAzMTMxNWJhYzE2ODVjYzVhMzM0N2RkMWYwZjE0MmJkZGE2YzMxMmJlOTE5MGZhMDUxY2U4NzdjMiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvUkVBRE1FLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNWYzMTI5OTAxMzkyZmFiODdkZDExZDYxNWIxNWY3Y2QyMDZmYmI0ZTIxMWRiZWY5NTlkMmI5MzU4N2ExZmE2YSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvcmVmZXJlbmNlcy9hcHBseS1yZXN0cnVjdHVyZS9SRUFETUUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJlNjE5MDFlODhiMDIwN2ExNjNiNDI4MTVjMjkwYWMwMmI4YmQ3ZDgyNjQ0ZWQxZGNiYzVkZWFkNWY2MTQ0OGI4IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1zdHJ1Y3R1cmUtYXNzZXNzbWVudC9yZWZlcmVuY2VzL2FwcGx5LXJlc3RydWN0dXJlL3JlZmVyZW5jZXMvbWVzaC1tZXJnZS1yZXdyaXRlLXNwZWMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJlYzc4N2MyMTE3YzMwY2QxZmE4MDQ3ZTk0Nzc5OTQzMTgxMGJmZGVjOTUyODRjMGNjMzc0NzlhYmY5YWU5MGI2IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1zdHJ1Y3R1cmUtYXNzZXNzbWVudC9yZWZlcmVuY2VzL2FwcGx5LXJlc3RydWN0dXJlL3JlZmVyZW5jZXMvcmVmLXJlbWFwLW1vZGUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJjMDE1MWQ4ZGYyYTRkYWY4MzM5NGNkN2Y2ODUxNTg0MjA2MzkzMjljMTQ4MTBkMTY2NzlhMzYzM2Q4M2Q1MTEwIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1zdHJ1Y3R1cmUtYXNzZXNzbWVudC9yZWZlcmVuY2VzL2FwcGx5LXJlc3RydWN0dXJlL3JlZmVyZW5jZXMvcmVzdHJ1Y3R1cmUtbW9kZS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjE0MWFiOThiOWJiOTU1YzE2MDRkOTE0M2I0ZTNjOTZlODQ0NjJhY2QyNjk1NmI3ZDg4MjViNTYzZmMzYjJhYTYiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3JlZmVyZW5jZXMvYXBwbHktcmVzdHJ1Y3R1cmUvc2NyaXB0cy9hcHBseS1yZXN0cnVjdHVyZS1tYW5pZmVzdC5zY2hlbWEuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjcyN2NiNmRlZTgyNjJhZTEwNmVjMTI2YTViYTFkNGNiODZkZjEzZjA0ZGI1ODdmMTdiNjU5MzBiMmQ5M2NmOTMiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3JlZmVyZW5jZXMvYXNzZXQtc3RydWN0dXJlLXByaW5jaXBsZXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJlY2ZjOTEyZjY0NmY0Mjc0NjljOWEwNWUyZWRkYzg4Yjg1OWEwZWVkYTllZTc2NjhjODJhZjlmZGQ0OTU4MGI3IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1zdHJ1Y3R1cmUtYXNzZXNzbWVudC9yZWZlcmVuY2VzL2NvbXBvc2l0aW9uLWF1ZGl0Lm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiYTJiNDg1MTdjYTcyMGVjMDkxMDhlMTczZTFkM2UwOGM3YTQ1ZTM3YzIzOTNjOGFhMDczMzBkYTgzMDEzYjcwYSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvcmVmZXJlbmNlcy9mYWN0b3J5LWxldmVsLXN0cnVjdHVyaW5nLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNjViZjc4M2QyM2U0NWY3ZmVjNzQyNjJmYTNmNzRmY2Y2MmNkYzQ3NzA5MzNiZDNhMjA4ZGY0ZmQyNzE0NjY2NiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvcmVmZXJlbmNlcy9pbnN0YW5jaW5nLXJlYWRpbmVzcy9SRUFETUUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJkMDA1ZmRiYjUyMzEyYTdiYjdjOTMzOTRiMGZlODI5ZDNmZDg4NGRjY2MyOTUxZjU5ZmNlOGMzODY1OGI0ODAwIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1zdHJ1Y3R1cmUtYXNzZXNzbWVudC9yZWZlcmVuY2VzL2luc3RhbmNpbmctcmVhZGluZXNzL3JlZmVyZW5jZXMvaW5zdGFuY2luZy1ndWlkZS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjE4MjZmNmNiYmY0MDk1MDcxYzhiZTEyNWJhMTlkNTJlNDIyZWNjN2VhNjI0MmRhMWI3ZDdhN2FjNDkxMDdmNGIiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3JlZmVyZW5jZXMvaW5zdGFuY2luZy1yZWFkaW5lc3MvcmVmZXJlbmNlcy9pbnN0YW5jaW5nLXRyYWRlb2Zmcy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjcyZWM2NzY0M2E0ODgyODg1ZDc1ZDBlOWQ5NTgxMDJlNGZmMDQyZWVkMjk3MzZhNWYyYWRlY2Q3MDQwOTAzMjAiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3JlZmVyZW5jZXMvbGF5ZXItaGVhbHRoLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMTgyZGY0MTg1YjA5MWZlZjhjYTg3NTAyMzk5ZGIwYzFmNThhZGFkMDIyZjkyZWIzZmZhNDlhMTAyYTQ5NzUzNyIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvcmVmZXJlbmNlcy9vcHRpbWl6YXRpb24tdHJhZGVvZmZzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNzRjYzc0ZjRiMzNiZmE0NWNjYTBhOWM2NmFjZDhhNGMxNGEyMTJjNDE1NjEzZWJiY2EyYjQ4MDJiNGVmMjZjYSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvcmVmZXJlbmNlcy9yZXN0cnVjdHVyZS1kZWNpc2lvbi9SRUFETUUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJkZTNmNjcwMzA2NTM5M2NlZjQyZjk3NTM0MTU3NGQ1ODgyZGZhYjc0YTVlODI3MjU5Njg2YWY2OGE2MGQ1YjY0IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1zdHJ1Y3R1cmUtYXNzZXNzbWVudC9yZWZlcmVuY2VzL3VzZC1lZGl0LXRhcmdldC1wbGFubmVyL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImU3NjEyZWI1MmVkY2Q3YzRiNzgyMGFlOTk3ZTYxNDc5OTdlYWVhZjU1ZWJkNjgzN2VmNWFjZTBiYjdmZjlhZjEiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3JlZmVyZW5jZXMvdXNkLWVkaXQtdGFyZ2V0LXBsYW5uZXIvcmVmZXJlbmNlcy9vdXRwdXQtc2F2aW5nLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMzY1MjJkZDc0Zjg3MWRmZmM4ZWI3ZDMxNmU4ZGFiZWZhYmU1MjdjYTQxZGYwOWE3ZWQ2MGUwMjIzZmQ4ZmYxYyIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvcmVmZXJlbmNlcy91c2QtZWRpdC10YXJnZXQtcGxhbm5lci9yZWZlcmVuY2VzL3ZhcmlhbnRzLXBheWxvYWRzLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiOGM1ODBhZTE3M2RlMjA2ZWFmMjE3YjhiYTQ2ZDRhNTkzMWQ3NjM0YjcyMDdkYWU5NjYzMDkwN2ExYzZiMDk4NiIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvcmVmZXJlbmNlcy91c2QtaGllcmFyY2h5LWRlZHVwZS1jYW5kaWRhdGVzL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjBmNzcxMmRhNzExMzZhMTM1ZDQyNzYyM2ExNTQ3MWNlNTBiYmJhNzAxMTFjYmI4NmI5YTFjZjhkZTFiZjM2MjUiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3JlZmVyZW5jZXMvdXNkLWhpZXJhcmNoeS1kZWR1cGUtY2FuZGlkYXRlcy9yZWZlcmVuY2VzL2luc3RhbmNlLWNhbmRpZGF0ZS1maW5kZXItc3BlYy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImM5ODIzMzE4NDExODFlY2NkMzIwNGE4MTI4MDExM2QxMDIyZDRkMzczZWJkZmQ3NTIxNzI4MDVjMTM1YTNhMDkiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3JlZmVyZW5jZXMvdXNkLWhpZXJhcmNoeS1kZWR1cGUtY2FuZGlkYXRlcy9zY3JpcHRzL2luc3RhbmNlX2NhbmRpZGF0ZV9maW5kZXIucHkiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI1MjNjNmE5MTBjNDE1ZWI3YWFjMjNkZmVkZWE1ODQ4YzM2YjBmOTViMTNiMDIyODljNmY4ZmRiZTk3NDMxZGYxIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1zdHJ1Y3R1cmUtYXNzZXNzbWVudC9yZWZlcmVuY2VzL3VzZC1oaWVyYXJjaHktZGVkdXBlLWNhbmRpZGF0ZXMvc2NyaXB0cy9zZWxlY3RfZnJvbnRpZXIucHkiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJiOWE0ZjRiZmM4M2YwOWEwY2Q1YTY5MDE3MmRjMjViZmYzNTM4NTY2ZGIwYmI4ZTYyZDY3ZTIyN2UwMDMxN2I0IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1zdHJ1Y3R1cmUtYXNzZXNzbWVudC9yZWZlcmVuY2VzL3VzZC1tZXNoLWZyYWdtZW50YXRpb24tY2FuZGlkYXRlcy9SRUFETUUubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJkNzQyYzU3NTVmNmQ3OTY4NmNiZTA3ZjYxNzYwMzc2NDkyMWI4YWI2OWM1ZjUyYzUxYzA1ZGZlODAzYjE0Njg3IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC1zdHJ1Y3R1cmUtYXNzZXNzbWVudC9yZWZlcmVuY2VzL3VzZC1tZXNoLWZyYWdtZW50YXRpb24tY2FuZGlkYXRlcy9yZWZlcmVuY2VzL21lc2gtZnJhZ21lbnRhdGlvbi1maW5kZXItc3BlYy5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjgxM2JkOTY4N2VjNTljYmM3YTUzOWFmY2U3Y2ZlMGYyZmI1YTIzYmQ5NjQzZTBmZjkxYjg1MzE4OGFmZjljYTYiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3JlZmVyZW5jZXMvdXNkLW1lc2gtZnJhZ21lbnRhdGlvbi1jYW5kaWRhdGVzL3NjcmlwdHMvbWVzaF9mcmFnbWVudGF0aW9uX2ZpbmRlci5weSIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjI2NTFmZjQ2ZDhmYmZjZWVhOGFhMmE3OTA4OTc5NjM2ODBkZGE5MjkzOWQzZjY0ZTEwNGFjODM1ZGNkMDZkMWIiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3NjcmlwdHMvYXVkaXQtcmVwb3J0LnNjaGVtYS5qc29uIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMWM4Zjg5YzUwMWYyNzE0NGIxOGM0ZjZhZjNiYTMxY2Y1Yzc3OWExNmNhMjJiOTU0OTJlNTUyNjI0YzNhZGZjNSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2Qtc3RydWN0dXJlLWFzc2Vzc21lbnQvc2NyaXB0cy9vcHRpbWl6YXRpb24tcGxhbi5zY2hlbWEuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjZlMDJjZmExMTZkM2ZkOGQxZTJmMWNkZDdhY2QxZTY5NjVhNzFhYTAxY2U5NzU5NTYwNmI4ZDljODNmYmQzMDkiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50L3NjcmlwdHMvdXNkLXN0cnVjdHVyZS1hc3Nlc3NtZW50LXJlcG9ydC5zY2hlbWEuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjllYjczYjQwMTAyZDk3NWQzYWZjNDJhNWY5N2FiZGMyMmQ1YzRkYTkzYjBiZTcyMjBmNzUxMjg1ZGQzN2IxODUiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXZhbGlkYXRpb24tcnVubmVyL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjExY2I1NzgzNWJhZGRiZTJmZDdiN2IxYjk5MDlkYWRhMDgwYTZkMjQ4ZWYxZDM3ZTEzODhmYjRjMDVkODY2ZDkiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXZhbGlkYXRpb24tcnVubmVyL3JlZmVyZW5jZXMvdXNkLW9wdGltaXplLWludGVycHJldC12YWxpZGF0b3JzL1JFQURNRS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjYyYzhkOTM0MmU4ZGZhNzRlYjhkOGRhYjkxYTVlYzgyZTZhNWFjZmQwODQwYWEyZTY0YzYzMzFiOGUyYzMyYzAiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXZhbGlkYXRpb24tcnVubmVyL3JlZmVyZW5jZXMvdXNkLW9wdGltaXplLWludGVycHJldC12YWxpZGF0b3JzL3JlZmVyZW5jZXMvZm9sbG93LXVwLXF1ZXJpZXMubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI3Mzg1YmZkZGQxZTc0YzZhODVjYjMxNDBmYmU5ZDA5NGQ2MzU4ZjAyZWJhOTA0M2MzMzI4OTE0Y2MxMmI0ZWVjIiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC12YWxpZGF0aW9uLXJ1bm5lci9yZWZlcmVuY2VzL3VzZC1vcHRpbWl6ZS1pbnRlcnByZXQtdmFsaWRhdG9ycy9yZWZlcmVuY2VzL3J1bGUtcmVmZXJlbmNlLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiYzgzMWMyYzg4MjhkMzFlYzkyZGFmOTkyYTM4MWRiZTAzOWZiYWZjYmIyZTc4YTdmM2VjMDNiYzdiNzkxY2I3ZSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2QtdmFsaWRhdGlvbi1ydW5uZXIvcmVmZXJlbmNlcy91c2Qtb3B0aW1pemUtcnVuLXZhbGlkYXRvcnMvUkVBRE1FLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiMmY0OGE5YzJkNGYyMTE3ODlkOWI0NmZiYzI4MDJiODQ2N2JjNmQwMzA2YWZkNDdlZjJmOTIzYWFiYmIxMDFhMCIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2QtdmFsaWRhdGlvbi1ydW5uZXIvcmVmZXJlbmNlcy91c2Qtb3B0aW1pemUtcnVuLXZhbGlkYXRvcnMvcmVmZXJlbmNlcy9pbmZyYXN0cnVjdHVyZS5tZCIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImEzM2IxMTE3YTZhOTAyODE1NTQyZDMyOWQ1ZGExZDA0MGE4YzNkNDM5NWFkNjhlNWMyODMyNzc5ZTBjY2RkNDQiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXZhbGlkYXRpb24tcnVubmVyL3JlZmVyZW5jZXMvdmFsaWRhdGUtdXNkLXZhbGlkYXRpb24tbnZpZGlhLm1kIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiNGUzNTk4YjA5YzliYzM5ODg0ZDcxOWQ2NmFjMmU5Yjk1MmY4YmEzN2I4N2VhODI5YmEyNjUyZmRhZmUzYTVjOSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2QtdmFsaWRhdGlvbi1ydW5uZXIvcmVmZXJlbmNlcy92YWxpZGF0b3ItY29uY2VwdHMuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogImQwNzg3NzI3YWMxNWI0MmE4MTkwZDExZWU5ZjVlOWY2NGY1ZWVkNDFjNzc2NjNmYjQyYzdlNTk5MTdhYjE2MTkiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvdXNkLXZhbGlkYXRpb24tcnVubmVyL3NjcmlwdHMvdXNkX3ZhbGlkYXRpb25fZXhlY3V0b3IucHkiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICI5Yzk5YWYyNzllMmQzMGY4NzBmZjI5NWRkNzdmZGMwYjYwNTRhZjMwMTJhMmQyN2VkZDhmZGU2MmYwNDNhNDA4IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC12YWxpZGF0aW9uLXJ1bm5lci9zY3JpcHRzL3ZhbGlkYXRpb24tcmVwb3J0LnNjaGVtYS5qc29uIgogICAgICB9LAogICAgICB7CiAgICAgICAgImFsZ29yaXRobSI6ICJzaGEyNTYiLAogICAgICAgICJkaWdlc3QiOiAiZjVjYjRhZTdkOWQ3OTVmM2I4MGFhYjJiZDFjYmI2YzM3NzczYmMyZjE1ZGU2MzZhZjE3M2JkMThiNDRhY2EwMSIsCiAgICAgICAgIm5hbWUiOiAicmVmZXJlbmNlcy91c2QtdmFsaWRhdGlvbi1ydW5uZXIvc2NyaXB0cy92YWxpZGF0aW9uLXNjb3BlLW5vdGUuc2NoZW1hLmpzb24iCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJjZjUyNWVkNjMwZmZjM2EwMmM4MDkwYmQ0NzU1ZDRkMzQwZmExMjdiZTAzMjViMmJmNzk5MDBhNmE3ODFkY2E3IiwKICAgICAgICAibmFtZSI6ICJyZWZlcmVuY2VzL3VzZC12YWxpZGF0aW9uLXJ1bm5lci9zY3JpcHRzL3ZhbGlkYXRvci1jb25jZXB0cy5zY2hlbWEuanNvbiIKICAgICAgfSwKICAgICAgewogICAgICAgICJhbGdvcml0aG0iOiAic2hhMjU2IiwKICAgICAgICAiZGlnZXN0IjogIjE0ZjRhMTZlYjM3M2Y4YzhkZjNmYjQ3OWMyMDQ0OGNhYTcwNTY2OWFlMmZmZDA4MzBhOTQ1MWY3ODZhYWM2MTkiLAogICAgICAgICJuYW1lIjogInJlZmVyZW5jZXMvd29ya2Zsb3cubWQiCiAgICAgIH0sCiAgICAgIHsKICAgICAgICAiYWxnb3JpdGhtIjogInNoYTI1NiIsCiAgICAgICAgImRpZ2VzdCI6ICJlZDRjNjk5MWM3ZjY1MDIyZGQ3ZjBlNDlhNGFmN2NhZGQ2ZWJhMGQ3NTAzNjMzN2FhMmNiNzY2YTBiZTdhZjE0IiwKICAgICAgICAibmFtZSI6ICJza2lsbC1jYXJkLm1kIgogICAgICB9CiAgICBdCiAgfQp9","payloadType":"application/vnd.in-toto+json","signatures":[{"sig":"MGUCMBwoxOPLSh7/tPbKCKdJb8ms4TQRAXnuSJBDlyA50Zwwus9L/2bRq3UPqiXFB1T3+gIxAOrWnjJFgZfClQSnWucU/fGtfw/S6kG0HQsNVrAtBLgYUs2+3YvRGz8EDl3LhGN8Kg==","keyid":""}]}} \ No newline at end of file
#OperationMethodResult