hkqai/Isaac Lab Scene Initializer

Isaac Lab Scene Initializer

Guides the user from a blank slate (or partial YAML) to a validated, ready-to-run Isaac Lab Python script. The bundled scripts/isaac_scene_loader.py handles all code generation.

---

Workflow

Phase 1 — Understand the Scene

If the user has an existing YAML, read it first and summarise what's already there.

Otherwise, ask the user (briefly — not all at once):

• Which robots? For each: USD path, position [x, y, z] (metres), end-effector frame name. Optional: rotation, fix_root, prim_path override.
• Which assets (lab furniture, containers, etc.)? For each: USD path, position, scale. Should the object be a static visual, a physics object (physics: true), or fixed-in-place with a collider (pinned: true)?
• Desired output script name (default: <yaml_stem>_isaac.py next to the YAML).

You do not need to have all answers before proceeding — draft the YAML with what you know and flag missing fields clearly with # TODO comments.

---

Phase 2 — Author / Extend the YAML

Write or update the YAML following this structure:

scene:
  robots:
    - name: "robot_name"              # unique identifier, used as USD prim name
      usd_path: "/abs/path/robot.usd" # .usd / .usda / .usdc / .usdz only
      position: [x, y, z]             # metres, default [0, 0, 0]
      rotation: [rx, ry, rz]          # rotation vector (axis-angle) in degrees, default [0,0,0]
      end_effector_frame: "tool0"     # body/link name for the end-effector
      fix_root: false                 # optional; set true if USD was converted with --fix-base
      prim_path: "/World/name/root"   # optional; override default /World/{name}

  assets:
    - name: "asset_name"              # unique identifier
      file: "/abs/path/model.usd"
      position: [x, y, z]
      rotation: [rx, ry, rz]         # rotation vector, degrees
      scale: [sx, sy, sz]            # default [1, 1, 1]
      physics: false                 # true → rigid body + collision + mass=1 kg
      pinned: false                  # true → kinematic (fixed) + collision, no mass

Rotation convention — rotation vector (axis-angle), identical to Blender:

• [0, 0, 0] → identity
• [0, 0, 90] → 90° around Z
• [45, 0, 0] → 45° around X

Scale — uniform scale (all three equal) is passed to UsdFileCfg(scale=…). Non-uniform scale is applied via a USD xform op after spawning.

physics vs pinned — do not set both to true on the same asset (kinematic bodies ignore forces, so adding mass/rigid props is contradictory). Flag this to the user.

Always output the complete YAML, not a partial diff.

---

Phase 3 — Validate

Before running the generator, check the YAML for these issues. Report all problems found and fix them (or ask the user) before proceeding:

| Check | What to verify | |---|---| | Required fields | Each robot has name, usd_path, end_effector_frame. Each asset has name, file. | | File existence | Every usd_path / file path exists on disk (os.path.exists). Resolve relative paths from the YAML's directory. | | USD extension | Extension is one of .usd, .usda, .usdc, .usdz. | | Unique names | No two robots share a name; no two assets share a name. | | Physics conflict | An asset must not have both physics: true and pinned: true. | | Non-empty scene | At least one robot or asset is present (warn only — empty scenes are allowed). |

If all checks pass, tell the user "Validation passed — generating script." and continue. If any check fails, list the problems clearly and wait for the user to resolve them before running the generator.

---

Phase 4 — Generate

Run the bundled script:

python /home/kennychufk/workspace/pythonWs/MatClaw/skills/isaac-lab-scene-init/scripts/isaac_scene_loader.py \
    <yaml_path> [output_script.py]

• If output_script.py is omitted the generator writes <yaml_stem>_isaac.py next to the YAML file.
• The script resolves all paths to absolute form and pre-computes quaternions internally — no post-processing needed.

After the generator prints Generated: <path>, tell the user the output path and remind them how to run the result inside Isaac Lab:

./isaaclab.sh -p <output_script.py>

---

Quick Field Reference

Robot fields

| Field | Required | Default | Notes | |---|---|---|---| | name | Yes | — | Used as USD prim name under /World/ | | usd_path | Yes | — | Absolute or relative path to USD | | position | No | [0,0,0] | Metres | | rotation | No | [0,0,0] | Rotation vector, degrees | | end_effector_frame | Yes | — | Body name; query at runtime via robot.find_bodies(name) | | fix_root | No | false | USD converted with --fix-base; noted in generated comments | | prim_path | No | /World/{name} | Use for MJCF-converted USDs with nested roots |

Asset fields

| Field | Required | Default | Notes | |---|---|---|---| | name | Yes | — | | | file | Yes | — | USD path | | position | No | [0,0,0] | Metres | | rotation | No | [0,0,0] | Rotation vector, degrees | | scale | No | [1,1,1] | Uniform or non-uniform | | physics | No | false | Rigid body + collision + 1 kg mass | | pinned | No | false | Kinematic (fixed) + collision, no mass |

---

Common Pitfalls

• Relative paths — isaac_scene_loader.py resolves paths from the process working directory, not the YAML location. Use absolute paths or run the script from the YAML's directory.
• MJCF-converted robots — the articulation root is often nested (e.g. /World/ur5e/worldBody). Use prim_path to point at it explicitly.
• fix_root is informational — it adds a comment in the generated script. The USD itself must have been converted with --fix-base; this flag doesn't alter the spawning code.