kickthemoon0817/usd-operations

Headless USD File Operations

This skill teaches you how to load, inspect, analyze, and modify USD files using the headless USD tools. These tools operate on local files without requiring a running Isaac Sim instance. They use a stage_id handle returned by load_usd_file.

Critical Distinction

| Tool set | When to use | Identifier | |---|---|---| | load_usd_file, get_prim_info, search_prims, get_mesh_info, get_bounding_box, summarize_scene, create_prim, update_prim_attributes, delete_prim | Offline/headless USD file analysis and editing | stage_id | | get_isaac_prim_info, search_isaac_prims, get_isaac_mesh_info, etc. | Live Isaac Sim scene (running instance) | prim path only |

Never mix these two sets. If Isaac Sim is not running, use the headless tools with stage_id. If Isaac Sim is running with a stage open, use the isaac_* tools.

Tool Chain Overview

validate_usd_file             (quick check before loading)
    → load_usd_file           (open file, returns stage_id)
        → get_prim_info       (inspect a specific prim)
        → search_prims        (find prims by type or name)
        → get_mesh_info       (vertex/face/UV analysis)
        → get_bounding_box    (spatial extents)
        → summarize_scene     (full scene overview)
        → create_prim         (add new prim)
        → update_prim_attributes  (modify attributes)
        → delete_prim         (remove prim)

Step-by-Step Workflow

1. Validate the File (Optional Fast Check)

Before loading, validate the file for USD errors without fully opening the stage.

mcp__simul__validate_usd_file
  file_path: "/home/user/assets/scene.usd"

Returns a list of errors and warnings. If the file has critical errors, loading may fail or produce incomplete results.

2. Load the File

Open the USD file and receive a stage_id handle. All subsequent headless operations require this ID.

mcp__simul__load_usd_file
  file_path: "/home/user/assets/scene.usd"

Returns: { "stage_id": "abc123", "prim_count": 142, "root_prims": [...] }

Important: The stage_id is a temporary handle for this session. Save it — you will pass it to every subsequent call.

3. Inspect a Specific Prim

Get the properties, attributes, and metadata of a single prim by path.

mcp__simul__get_prim_info
  stage_id: "abc123"
  prim_path: "/World/Robot/base_link"

Returns type, attributes (with values), children, and applied schemas.

4. Search for Prims

Find prims by type or name pattern across the entire stage.

mcp__simul__search_prims
  stage_id: "abc123"
  search_type: "by_type"
  query: "Mesh"

mcp__simul__search_prims
  stage_id: "abc123"
  search_type: "by_name"
  query: "wheel"

search_type options:

| Value | Behavior | |---|---| | by_type | Match USD schema type: Mesh, Xform, Scope, Material, Camera, DistantLight, SphereLight, RectLight | | by_name | Substring match on prim name (case-insensitive) |

5. Analyze Mesh Geometry

Get detailed mesh topology for a Mesh prim: vertex count, face count, normals, UV sets, and bounds.

mcp__simul__get_mesh_info
  stage_id: "abc123"
  prim_path: "/World/Robot/base_link/visuals/mesh"

Returns: { "vertex_count": 2048, "face_count": 1024, "has_normals": true, "uv_sets": ["st"], "extent": [...] }

Use this to assess mesh complexity before simulation (high-poly meshes should use convex decomposition for collision).

6. Get Bounding Box

Get the spatial extents of a prim in world or local space.

mcp__simul__get_bounding_box
  stage_id: "abc123"
  prim_path: "/World/Robot"
  world_space: true

Returns: { "min": [x, y, z], "max": [x, y, z], "center": [x, y, z], "size": [w, h, d] }

Set world_space: false to get local (object-space) extents.

7. Summarize the Scene

Get a full overview of the scene contents without inspecting prim by prim.

mcp__simul__summarize_scene
  stage_id: "abc123"
  include_meshes: true
  format: "text"

Use format: "json" for structured output when parsing programmatically. Use format: "text" for human-readable summaries.

include_meshes: true adds per-mesh vertex/face counts to the summary. Set to false for faster results on large scenes.

8. Modify the USD File

The headless tools support basic creation, modification, and deletion.

Create a prim:

mcp__simul__create_prim
  stage_id: "abc123"
  prim_path: "/World/NewXform"
  prim_type: "Xform"

Update attributes:

mcp__simul__update_prim_attributes
  stage_id: "abc123"
  prim_path: "/World/NewXform"
  attributes: {"xformOp:translate": [1.0, 2.0, 0.5]}

Delete a prim:

mcp__simul__delete_prim
  stage_id: "abc123"
  prim_path: "/World/UnwantedPrim"

Note: Modifications via these tools write back to the loaded stage. To persist changes to disk, the stage must be saved — use execute_isaac_script with stage.Export(path) if Isaac Sim is running, or be aware that headless modifications may require a separate save step depending on server configuration.

Common Analysis Workflows

"Analyze this USD file and tell me what's in it"

1. validate_usd_file — check for errors
2. load_usd_file → get stage_id
3. summarize_scene with format: "text" — full overview
4. search_prims with by_type: "Mesh" — list all meshes
5. Report findings

"How many polygons does this robot have?"

1. load_usd_file → stage_id
2. search_prims with by_type: "Mesh" — find all mesh prims
3. get_mesh_info for each mesh — accumulate vertex/face counts
4. Sum and report

"What is the size of this asset?"

1. load_usd_file → stage_id
2. get_bounding_box on the root prim with world_space: true
3. Report size field

Decision Guide

| User Intent | Tool to Use | |---|---| | "Is this USD file valid?" | validate_usd_file | | "Load and inspect a USD file" | load_usd_file → summarize_scene | | "Find all meshes in the file" | search_prims with by_type: "Mesh" | | "How many vertices in this mesh?" | get_mesh_info | | "What are the dimensions?" | get_bounding_box | | "Inspect prim at path X" | get_prim_info | | "Add a new prim to the file" | create_prim | | "Change an attribute value" | update_prim_attributes |

Common Pitfalls

• Using headless tools on a live stage: Do not use get_prim_info (headless) when Isaac Sim is running and you want live data — use get_isaac_prim_info instead.
• Forgetting stage_id: Every headless call requires the stage_id from load_usd_file. Calling get_prim_info without it will fail.
• Stage ID is session-scoped: The stage_id is not persistent across tool sessions. If the session resets, call load_usd_file again.
• Large scenes: summarize_scene with include_meshes: true on a scene with thousands of meshes can be slow. Use include_meshes: false for a quick overview first.
• by_name is substring match: search_prims with by_name: "link" will match base_link, arm_link_1, etc. Use more specific queries to narrow results.