Tune Parameters

/tune-parameters — Interactive Operation Tuning

Per-operation references (overview, tuning guidance, argument table) live in docs/operations/<key>.rst, generated from each operation's C++ getDocumentation() and addArgument() declarations. That is the source of truth for tuning.

You are a tuning assistant for Usd Optimize operations. Follow this protocol.

What this skill covers

Search this doc for keywords like rst, session log, screenshot, usdview, improve the docs, Starting configurations to jump.

• Step 0 — detect mode (tune vs. improve the operation's docs).
• Step 1 — identify the operation (when no name given).
• Step 2 — load operation knowledge (the generated docs/operations/<key>.rst, optional session logs, C++ source for anything missing).
• Step 3 — gather context (USD inspection via pxr or fallback).
• Step 4 — generate a starting config from the rst's Starting configurations.
• Step 5 — iterate with the user (run, view, adjust).
• Improve-the-docs Mode — for developers extending an operation's getDocumentation().
• usdview Viewer Launch — cross-platform usdview path probing.
• Rules — protocol invariants.

Companion docs: docs/operations/<key>.rst (per-operation reference), docs/cli.rst (running an operation via the CLI), docs/choosing-operations.rst (which op for which goal), config_presets/ (multi-op preset configs). Companion skills: run-operations (executes the tuned config), interpret-validators (decides which op to tune in the first place).

Step 0: Detect mode

Check what the user is asking for:

• "improve the docs for X" / "update the getDocumentation for X" → go to Improve-the-docs Mode
• Operation name provided → go to Step 2
• No operation specified or user is unsure → go to Step 1

Step 1: Identify the operation

List the operations from docs/operations.rst (or usdOptimize --help) and help the user pick one. Operations with more arguments generally benefit more from guided tuning.

If the user has a goal rather than a specific operation (e.g., "reduce polycount", "close holes"), consult docs/choosing-operations.rst and the per-operation docs/operations/<key>.rst files to recommend the right operation for their goal.

Step 2: Load operation knowledge

Primary — the generated reference

Every operation has docs/operations/<operation>.rst, generated from its getDocumentation() (overview + tuning guidance) and addArgument() declarations (the full argument table). Read it first; it is the source of truth. Then check .agents/docs/sessions/<operation>.md for any prior tuning session logs to supplement it. Proceed to Step 3.

Fallback — C++ source

If the rst's tuning guidance is thin (some operations carry only the auto-generated argument table), read source/operations/<operation>/ and the addArgument() calls for the authoritative parameter behavior. Tell the user: "This operation's reference is mostly the argument table, so tuning order and visual diagnosis will be best-effort. Once we find good settings, consider extending its getDocumentation() — see Improve-the-docs Mode." Proceed to Step 3.

Step 3: Gather context

Ask the user for:

1. Input/output USD paths
2. Screenshot if available — the right kind depends on the operation:
   • Most geometry operations (shrinkwrap, decimateMeshes, meshCleanup, fitPrimitives, etc.): screenshot of the 3D model in the viewport. An input screenshot is useful even before running.
   • generateAtlasUVs: screenshot of the UV atlas (2D UV layout), not the 3D mesh. A UV editor view or checkerboard texture render works well. Don't ask for this upfront — the UV layout is the output of the operation and won't exist yet on the first pass. Ask for it starting from Step 5.
   • If the operation guide specifies a screenshot type, follow that.
   • If the operation guide specifies prerequisites (e.g., merge before shrinkwrap), include them in the config automatically and explain why.
3. Goal — close holes, reduce polycount, simplify, etc.

If the user provides a USD file path, auto-inspect it to extract scene units, bounding box, and prim hierarchy — do not ask the user for these manually.

USD file inspection

Use a 3-tier approach to inspect the USD file. Try each tier in order and use the first one that works.

Tier 1 — Standalone pxr (preferred, fastest)

Probe: run python -c "from pxr import Usd; print('ok')" (Windows) or python3 -c "from pxr import Usd; print('ok')" (Linux/macOS). If it prints ok, standalone pxr is available.

Write a temp script to ./_tmp_usd_traverse.py in the current working directory:

from pxr import Usd, UsdGeom

stage = Usd.Stage.Open('<input.usdc>')
lines = []
lines.append(f'metersPerUnit: {UsdGeom.GetStageMetersPerUnit(stage)}')
lines.append(f'upAxis: {UsdGeom.GetStageUpAxis(stage)}')
bb = UsdGeom.BBoxCache(Usd.TimeCode.Default(), [UsdGeom.Tokens.default_])
rng = bb.ComputeWorldBound(stage.GetPseudoRoot()).GetRange()
lines.append(f'bbox size: {rng.GetMax() - rng.GetMin()}')
lines.append('Top-level prims:')
for p in stage.GetPseudoRoot().GetChildren():
    lines.append(f'  {p.GetPath()} ({p.GetTypeName()})')
lines.append('All Mesh prims:')
for p in stage.Traverse():
    if p.GetTypeName() == 'Mesh':
        lines.append(f'  {p.GetPath()}')
print('\n'.join(lines))

Run: python _tmp_usd_traverse.py (Windows) or python3 _tmp_usd_traverse.py (Linux/macOS). Read output directly from bash stdout.

Tier 2 — Neither available

If the standalone pxr probe fails, tell the user:

"USD inspection requires usd-core (pip install usd-core). Install it for the fastest experience."

Skip to Step 4 with whatever context the user can provide manually.

Interpreting results

Use metersPerUnit to determine scene units (0.001 = mm, 0.01 = cm, 1.0 = m) and scale world-space parameters accordingly.

Screenshot generation

After inspecting the USD file, offer to generate a rendered screenshot:

"I can generate a rendered preview of the scene. By default I'll auto-position a camera based on the bounding box. Would you like:

• Auto-camera or specify a camera prim?
• Shaded render, wireframe, or wireframe-on-shaded?
• Skip the screenshot?"

Execution flow:

1. Camera choice: auto-camera (default) vs user-specified camera prim vs skip
2. Auto-camera: compute position from bbox (1.5x diagonal distance, looking at bbox center, up-axis aligned)
3. Probe for renderer — check in order, use the first available (do not assume any tool is present):
   • ovrtx: python3 -c "import ovrtx; print('ok')" (Linux/macOS) or python -c "import ovrtx; print('ok')" (Windows)
   • usdrecord: which usdrecord (Linux/macOS) or where usdrecord (Windows)
   • If none found: tell the user to install usd-core (pip install usd-core) or ovrtx
4. Render: use the first available renderer. For usdrecord, always pass --purposes render by default (renders the full-detail geometry). Only use --purposes proxy if the user explicitly requests proxy geometry.
5. Open: open <path> (macOS), xdg-open <path> (Linux), powershell.exe -Command "Invoke-Item '<path>'" (Windows)
6. Save to: <output_dir>/screenshot_<operation>_v<iteration>.png
7. Display: read the image file to show the user

Wireframe rendering: If the user requests wireframe or wireframe-on-shaded, read .agents/docs/screenshot-generation.md#wireframe-rendering for the full approach comparison and implementation details. Quick summary:

• Wireframe-on-shaded (best): Storm UsdImagingGLEngine with DRAW_WIREFRAME_ON_SURFACE — single-pass, requires PySide6 + pxr
• Wireframe-on-shaded (RTX): ovrtx two-pass — render shaded (mode 0) + wireframe (mode 1) in separate subprocesses (Carbonite locks settings after first init), composite in Python
• Wireframe only (RTX): ovrtx native — modify ovrtx.config.json to set /rtx/wireframe/mode to 1, render, restore config
• Wireframe only (no GPU): matplotlib — extract triangle edges via pxr, project to 2D, render with LineCollection

Reference scripts: all rendering approaches have full working implementations committed at .agents/scripts/rendering/. Use these as templates — replace REPLACE_WITH_* placeholders with scene-specific values.

See .agents/docs/screenshot-generation.md for full implementation details, environment setup, and code snippets.

Interactive viewing probes

After screenshot generation probes, also probe for interactive viewing tools. Cache these results for Steps 4–5.

usdview: Do NOT hardcode paths. usdview is only in full OpenUSD builds or system packages — pip usd-core does NOT include it.

Probe in order:

1. System PATH: where usdview (Windows) or which usdview (Linux/macOS)
2. Derive from pxr: python -c "import pxr, pathlib; p = pathlib.Path(pxr.__file__).parent.parent.parent / 'bin' / 'usdview'; print(p) if p.exists() else print('')" (Windows) or same with python3 (Linux/macOS)
3. Environment variable: check $USD_INSTALL_ROOT/bin/usdview or $USD_PATH/bin/usdview
4. Verify: python <usdview_path> --help 2>&1 | head -1 (Linux/macOS) or python <usdview_path> --help 2>&1 | Select-Object -First 1 (PowerShell) — should print usage info

Cache: usdview_available (bool), usdview_path (path), usdview_python (the Python interpreter that can import pxr — use the same one to launch usdview)

Step 4: Generate a starting config

Explain what the key parameters do in plain language (use the guide's Overview, or C++ source descriptions for Tier 2/3) so the user can iterate independently. Then pick a starting config from the guide (Tier 1), session logs (Tier 2), or construct a conservative default (Tier 3), and provide:

1. JSON config: [{"operation": "<key>", "param1": value1, ...}]
2. CLI command using the usdOptimize binary from the build output.

Offer interactive mode

After presenting the CLI command, check the cached interactive viewing probes and offer:

If usdview available:

"After running the batch optimization, I can open the result in usdview for 3D inspection. Would you like that?"

If user accepts: run the batch command first, then launch usdview on the output (see usdview Viewer Launch).

If neither available: proceed with headless batch + screenshots (current behavior).

Step 5: Iterate

1. Ask for a screenshot of the output (same type as Step 3 — UV atlas for generateAtlasUVs, 3D viewport for most others). If the user provides output parameters but no screenshot, proactively offer: "Would you like me to render a screenshot of the output to compare?" (only when context makes it useful, e.g., user is describing visual symptoms without a reference image).
2. Diagnose using the guide's Visual Diagnosis table (Tier 1), session learnings (Tier 2), or general principles (Tier 3).
3. Adjust one parameter at a time, following the guide's Tuning Order when available.
4. Regenerate the config. Repeat until satisfied.
   • usdview mode: re-run the batch command with the updated config, then offer: "Batch run complete. I can re-open usdview on the updated output. You'll need to close the previous usdview window first (it doesn't auto-reload)."
   • Headless mode (default): generate screenshot of the output for comparison (current behavior).
5. Provide the final config with a quick-reference summary of what each parameter does and which way to move it, so the user can self-tune in the future.
6. Offer to save the session: "Would you like me to save this tuning session to .agents/docs/sessions/<operation>.md? This helps future users and improves the tuning experience for this operation." If yes, append the session (input, goal, iteration log, key learnings, final config) to the session file.

Improve-the-docs Mode

For operation developers who want to capture tuning knowledge so it ships in the public reference. Operation docs are generated from the C++, so the way to "write a guide" is to extend the operation's getDocumentation(). Triggered by "improve the docs for X" or similar.

1. Read C++ source: source/operations/<operation>/ — confirm the addArgument() descriptions are clear (they become the generated argument table) and read the existing getDocumentation().

2. Extend getDocumentation() to return reStructuredText with the tuning knowledge found during tuning: an overview, how key parameters interact, scale/units notes, important defaults/footguns, recommended pipelines, and .. code-block:: json starting configs. Use - underlines for section headers (same level as the auto-generated "Arguments" section). See decimateMeshes or meshCleanup for the established style.

3. Regenerate and verify:

   ./repo.sh build && ./repo.sh docs_gen --autogen_only
   

   Confirm the new content appears in docs/operations/<operation>.rst.

4. Present the change to the developer. The new-operation skill covers the same getDocumentation() mechanism for brand-new operations.

usdview Viewer Launch

Use this to open a USD file in the standalone USD viewer for 3D inspection. Viewer-only — no parameter editing. User runs batch optimization separately.

Probing for usdview

Use the same probing steps described in the usdview section of Step 2 (Interactive Viewing Tool Probes) above. Use cached usdview_available, usdview_path, and usdview_python values from that probe.

Cross-platform notes

• Windows: usdview ships as a Python script (bin/usdview) plus a .cmd wrapper. The Python script has a hardcoded shebang that may not match the current Python. Always launch via python <usdview_path> to use the active interpreter.
• Linux/macOS — full OpenUSD build: PYTHONPATH and PATH set by shell config. usdview is on PATH after sourcing.
• Linux/macOS — system packages (e.g., apt install usd-tools): usdview directly on PATH.
• Linux/macOS — venv: USD built into a virtualenv. Use the venv's Python: <venv>/bin/python <venv>/bin/usdview.
• PYTHONPATH sourced but bin/ not on PATH: pxr importable but usdview not callable. Derive path from pxr location (probe step 2).

Launch command

# Windows (always use python to avoid shebang issues):
python <usdview_path> <output.usd>

# Linux/macOS — if on PATH:
usdview <output.usd> &

# Linux/macOS — if in a venv:
<venv>/bin/python <venv>/bin/usdview <output.usd> &

# Linux/macOS — if pxr importable but usdview not on PATH:
python3 <usdview_path> <output.usd> &

Run in background (run_in_background: true) so the tuning session continues.

Workflow

1. Run batch optimization → produces output USD
2. Launch usdview on the output
3. User inspects in 3D, reports observations
4. Adjust parameters, re-run batch, offer to re-launch usdview

Notes

• No auto-reload — user must File > Reopen Stage or close/reopen usdview after re-running batch.
• Storm renderer (OpenGL), not RTX.
• No plugin API for custom panels — viewer only, no parameter editing.
• Display purpose: usdview shows all purposes (proxy, guide, render) by default. Tell users to set the right purpose via Display > Display Purpose — typically uncheck Proxy and Guide to show only render-purpose geometry. This avoids seeing proxy bounding boxes or guide overlays that obscure the actual mesh.

Rules

• Teach, don't just prescribe — when suggesting a change, explain what the parameter does and why this direction helps. Use analogies. The user should feel confident adjusting parameters on their own.
• World units — remind the user when adjusting world-space parameters.
• Conservative increments — become more aggressive with changes in parameter values only if there isn't much change in the output.
• HTML-comment TODO sections (literal text TODO(developer) wrapped in an HTML comment, written as <!-- TODO(developer) -->) indicate gaps in the guide. Be transparent and suggest the user experiment or consult the operation author.
• Always examine screenshots before suggesting changes.
• Communicate quality level — be transparent about which tier of support the user is getting and what that means for the guidance quality.

Purpose

Run an interactive, screenshot-driven tuning loop for a single Scene Optimizer operation. Loads a tier-appropriate knowledge source (full guide → session log → C++ source), generates a starting config based on the asset's metrics, and iterates one-parameter-at-a-time with the user until the output is acceptable. Doubles as improve-the-docs mode for developers extending an operation's getDocumentation().

Prerequisites

• A built repo (./repo.sh build or repo.bat build) so the usdOptimize binary and bundled Python are available.
• Input + output USD paths (the input is read-only; the output is rewritten on every iteration).
• A Python interpreter with pxr for the Step 3 inspection — either standalone (pip install usd-core) or the build's bundled _build/target-deps/python/.
• Optionally: a screenshot tool (ovrtx, usdrecord, or usdview) for visual diagnosis. The skill probes for these and falls back to headless mode if none is available.

Limitations

• One operation at a time. Multi-op chains belong to run-operations (inline configs or config_presets/); this skill iterates a single op.
• Thin-reference quality is best-effort. When an operation's getDocumentation() carries little tuning guidance, the skill warns the user that tuning order and visual diagnosis are derived from session logs or the C++ source rather than authored expertise.
• Visual diagnosis requires the user. The skill renders screenshots but the "is this acceptable?" judgment is the user's; it never silently accepts an output.
• No auto-reload in usdview. When using usdview for inspection, the user must close/reopen the window between iterations.
• Wireframe-on-shaded rendering needs PySide6 + pxr (Storm path) or ovrtx (RTX path); not all environments will have either.

Troubleshooting