---
name: usd-operations
description: This skill should be used when the user asks to "analyze a USD file", "load a USD file", "inspect USD", "headless USD", "prim info", "search prims", "mesh info", "scene summary", "bounding box", or needs to work with USD files without a running Isaac Sim instance.
version: 0.1.0
---

# 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.