Omniverse Cad To Simready

Content Agents

When to Use

Use this router reference after USD conversion and minimum USD validation when an asset needs NVIDIA Omniverse Content Agents service calls. Select the right nested call reference, preserve each service report, and hand the newest USD or USDZ artifact to the next workflow stage.

This is not the deployment workflow and not a replacement for the service-specific call references. If an endpoint is missing, hand off to deploy-content-agents for the required target, then return to this router and run the selected service call.

This installed router reference ships a narrow scripts/run.py control-plane wrapper for deterministic service sequencing and report generation. It still delegates service calls to the portable scripts/run.py from each selected service reference; it does not reimplement Material, Physics, or Texture Agent behavior.

Prerequisites

• Python 3.12 and uv (per repo README.md).

• Prefer a ready PHYSICAL_AI_PREFLIGHT_MANIFEST from the preflight reference. The client wrappers consume prepared CONTENT_AGENTS_*_BASE_URL endpoints from that manifest before falling back to direct environment variables. When PHYSICAL_AI_REQUIRE_PREFLIGHT=1 is set, missing or unhealthy services block at the preflight guardrail.

• A required .usd, .usda, .usdc, or .usdz input asset.

• Reachable Material, Physics, Texture, or OVRTX endpoints through CONTENT_AGENTS_*_BASE_URL, unless this router hands off to deployment first.

• Bearer auth through explicit usage token environment variables when a provided endpoint requires auth: CONTENT_AGENTS_TOKEN, NGC_API_KEY, NVCF_API_KEY, or selected service-specific variables such as CONTENT_AGENTS_MATERIAL_AGENT_TOKEN, MATERIAL_AGENT_TOKEN, CONTENT_AGENTS_PHYSICS_AGENT_TOKEN, PHYSICS_AGENT_TOKEN, CONTENT_AGENTS_TEXTURE_AGENT_TOKEN, or TEXTURE_AGENT_TOKEN.

Routing

Choose the smallest route that satisfies the user request and selected workflow profile:

Prefer explicit user intent over default ordering. For simulation-readiness, run visual material assignment before physics assignment so the Physics Agent can use the materialized USD when available. Run texture generation after material assignment, and do not replace the physics-authored USD path for simulation validation unless the user explicitly wants to validate the textured USDZ.

Run the local router when more than one Content Agents call is selected so path handoff is deterministic:

python3 /path/to/skills/omniverse-cad-to-simready/references/content-agents/scripts/run.py \
  /path/to/material_input.usd \
  --output-dir /path/to/output/content-agents \
  --call material \
  --call physics \
  --report /path/to/output/content-agents/content-agents.json

Add --call texture only when textured output or textured packaging is requested. The consolidated output_usd_path remains the latest simulation USD when physics ran; textured_usdz_path is reported separately.

Inputs

Collect:

Instructions

1. Confirm the asset exists and is USD-family.

2. Determine the requested Content Agents calls from user intent, workflow defaults, and selected SimReady profile.

3. Resolve required service endpoints from explicit inputs or CONTENT_AGENTS_*_BASE_URL.

4. For each missing required endpoint, use deploy-content-agents with the matching target. Require a healthy service before returning to this router.

5. Do not run simready-conform-profile, FET001 unit normalization, or other FET repairs before the first Content Agents call. If minimum USD validation found metersPerUnit != 1.0 or another repairable SimReady issue, record it for the post-assignment conformance pass and continue with the converted/minimum-valid USD as the service input.

6. Use the material-agent-client reference first when material assignment is requested or needed. Its wrapper stages USD-layer uploads without MDL shader sourceAsset references when those references point at missing converter sidecars such as gltf/pbr.mdl; preserve the material_upload_info field from its report.

7. Use the physics-agent-client reference on the latest materialized USD path when physics assignment is requested or needed. Its wrapper automatically inspects USD topology and enables --optimize-usd --enable-deinstance --enable-split for composed CAD assets with GeomSubset, instance, or prototype component structure. It also stages Physics Agent uploads without MDL shader sourceAsset references and unresolved service-internal USDZ subasset paths from Material Agent outputs when those references would only affect visual material source files and can break main optimizer packaging. If the optimized Physics service path fails because Scene Optimizer is unavailable, the wrapper retries once without the optimizer flags and records both attempts. Preserve the usd_topology, physics_optimizer, physics_upload_info, and attempts fields from its report.

8. Use the texture-agent-client reference only when texture generation or textured packaging is requested.

9. Preserve each JSON report and report HTML or prediction artifact when available.

10. Summarize the selected route, service readiness decisions, generated artifacts, latest USD-family output, and next handoff.

When an existing service endpoint requires bearer auth, export an explicit usage token environment variable before running the command. Use CONTENT_AGENTS_TOKEN for a shared Content Agents token, service-specific CONTENT_AGENTS_*_TOKEN / *_AGENT_TOKEN variables for one service, or NGC_API_KEY / NVCF_API_KEY for provided NVCF endpoints. Do not use NVIDIA_API_KEY as the default client token; it is deployment auth. Do not pass secrets as command-line arguments in normal workflows because process listings can expose argv. In normal agent workflows, omit --token entirely, including empty strings or placeholders, and let the wrapper read the credential from env or a *_FILE variable. The wrapper still accepts --token for constrained automation, but that path should be treated as a fallback.

For detached or shared-host runs, prefer file-backed secrets such as CONTENT_AGENTS_TOKEN_FILE, NGC_API_KEY_FILE, MATERIAL_AGENT_TOKEN_FILE, PHYSICS_AGENT_TOKEN_FILE, or TEXTURE_AGENT_TOKEN_FILE. The wrappers read the token from those files when the corresponding environment variable is unset, which avoids exposing token values through shell expansion or process argv.

The service wrappers poll /pipeline/<session>/status until the service reaches a terminal state or the wrapper timeout expires. Transient polling failures such as SSL or connection timeouts, HTTP 408, HTTP 429, or HTTP 5xx responses are retried and recorded as warnings when the service later completes.

Multi-File USD Uploads

The service API accepts a single uploaded USD-family file. When the input USD uses external layers or asset dependencies, the wrappers inspect dependencies with OpenUSD and package the asset as USDZ for upload with UsdUtils.CreateNewUsdzPackage. The report records this in upload_info and upload_packaging. Prefer this packaging path over flattening because it keeps the authored layer structure and referenced assets together for the service. When the process Python cannot import pxr, the wrappers try CONTENT_AGENTS_OPENUSD_PYTHON, USD_CONVERT_CAD_PYTHON, the skill repository's .venv, and uv run --python 3.12 in that order. They never discover or execute a .venv from the caller's asset directory; uv is bound to the skill-owned project when one is present and otherwise runs with --no-project. The same resolver is used for topology inspection, MDL/service-path preparation, and dependency packaging. upload_info records the selected inspection_runtime, executable, dependency paths, unresolved paths, packaging decision, and package size. If no runtime can inspect a local USD, the wrapper fails before creating a service session and asks for an already self-contained USDZ or a configured OpenUSD Python instead of silently uploading one raw layer.

Material Agent alone may receive an original USD with unresolved texture paths when inspection finds no resolved sidecars, because missing source textures can be replaced during material prediction. The report records that exception as missing_textures_passthrough with a warning. If a missing texture prevents OpenUSD from packaging otherwise resolved dependencies, the wrapper fails before session creation instead of uploading a root layer that omits those sidecars. Missing USD layers or other non-texture dependencies always fail, and Physics and Texture Agent uploads reject every unresolved dependency.

Rate Limits

Wrapper retries cover transient status polling and delayed artifact download failures, including HTTP 429 responses visible to the wrapper. They do not retry per-prim VLM prediction failures that the Material Agent records inside a completed service session. If predictions are partially rate-limited, preserve the service report, rerun later or with a smaller asset/workload when possible, and use a higher-quota service key for large assemblies.

Command Patterns

Material assignment:

python3 /path/to/skills/omniverse-cad-to-simready/references/content-agents/references/material-agent-client/scripts/run.py asset.usda output_dir/content-agents/materials \
  --prompt "$ASSET_CONTEXT_PROMPT" \
  --report output_dir/content-agents/material-agent-client.json

The Material Agent wrapper sends vlm_max_workers=1 and omits the service-side render step by default. Use --vlm-max-workers, --render-num-workers, or --material-steps only when the selected service run needs different concurrency or its own render artifact.

For any existing endpoint that requires a different bearer token, set MATERIAL_AGENT_TOKEN, PHYSICS_AGENT_TOKEN, or TEXTURE_AGENT_TOKEN in the environment for the selected service instead of changing wrapper defaults. Use the matching *_FILE variable when the run is long-lived or process listings are visible to other users.

If the Material Agent optimized path was intended but local service logs show Scene Optimizer failed — continuing pipeline without optimization together with Permission denied: '/app/.build-resources/scene_optimizer_core/python', repair the running local Material Agent container permissions and rerun the same Material Agent command. This is a local Scene Optimizer bundle permission issue, not an asset-level reason to disable optimize_usd.

Physics assignment:

python3 /path/to/skills/omniverse-cad-to-simready/references/content-agents/references/physics-agent-client/scripts/run.py output_dir/content-agents/materials/output_material.usd output_dir/content-agents/physics \
  --render-backend remote \
  --convert-output-to-usd \
  --prompt "$ASSET_CONTEXT_PROMPT" \
  --report output_dir/content-agents/physics-agent-client.json

The Physics Agent wrapper auto-enables --optimize-usd --enable-deinstance --enable-split when USD inspection detects composed component topology, and it falls back to a no-optimizer retry when the service reports an optimizer setup failure. If the optimized attempt fails immediately at optimize_usd with no completed service steps, inspect the Physics Agent service logs before treating the no-optimizer retry as meaningful. On local Docker deployments, a known Scene Optimizer bundle permission issue can appear as Permission denied: '/app/.build-resources/scene_optimizer_core/python'; repair the running service container permissions and rerun the optimized command instead of disabling deinstance/split for instanced topology. Do not wrap the call in a shorter external timeout or terminate the wrapper while the service remains non-terminal and its current step or progress is advancing. Remote-rendered Physics stages such as identify_asset, build_dataset_usd, predict, restore_usd, and apply_physics can take many minutes on CAD or instanced assets; wait for the wrapper to return its JSON report unless the service reaches a terminal failure state or the wrapper's own timeout expires.

If the physics-authored USD still has one rigid body and the selected profile reports RB.MB.001, keep the service output and route that validation failure through simready-conform-profile / upstream simready-foundation-conform-fet-004-simulate-multi-body-physics only when the USD has at least two reusable component candidates. For a single mesh component or single GeomSubset component, simready-validate treats RB.MB.001 as non-blocking and records it under ignored_issues; do not retry the same Physics Agent call blindly.

If system python3 cannot import pxr, the Material and Physics wrappers try uv run --python 3.12 for OpenUSD topology inspection. Upload dependency inspection and packaging use the broader fail-closed runtime resolution described under Multi-File USD Uploads. Upload-copy preparation also tries the uv runtime when stripping missing MDL shader sources or clearing unresolved service-internal USDZ subasset paths before packaging.

Texture generation:

python3 /path/to/skills/omniverse-cad-to-simready/references/content-agents/references/texture-agent-client/scripts/run.py output_dir/content-agents/materials/output_material.usd output_dir/content-agents/textures \
  --report output_dir/content-agents/texture-agent-client.json

Use the concrete output_usd_path, output_usdz_path, or downloaded artifact paths from each report. Do not assume placeholder filenames from examples.

Output Format

The router summary should include:

Limitations

• This router is not the deployment workflow and not a replacement for the service-specific call references.

• Run texture generation only when texture generation or textured packaging is requested.

• Do not replace the physics-authored USD path for simulation validation with a textured USDZ unless the user explicitly requests that validation target.

Troubleshooting

Pass/Fail Policy

Block when a required service endpoint is missing and deploy-content-agents cannot deploy or verify the service.

Fail when a selected Content Agents call fails, times out, or cannot download its required output artifact.

Skip when the user explicitly disables a call, the selected profile does not need that enrichment, or texture generation is not requested.

Warn when optional prediction files, report HTML, or texture artifacts are unavailable but the required USD-family handoff exists.

Next Steps

Use this handoff: