Add scene_prep utilities and update Isaac Sim launch scripts (#324)

* Add scene_prep utilities and update Isaac Sim launch scripts

Add simulation/isaac-sim/utils/scene_prep.py with four helpers:
- scale_stage_prim: apply uniform XYZ scale to a stage prim
- add_colliders: recursively apply CollisionAPI to all mesh prims
- add_dome_light: add/update a dome light (intensity=3500, exposure=-3)
- save_scene_as_contained_usd: collect Nucleus assets into a local directory

Update example_one and example_two launch scripts to use scene_prep
for environment scaling, collision setup, and lighting instead of
inline UsdLux calls. Fix two_drone_scene_import.

Update write-isaac-sim-scene SKILL.md to reference scene_prep utilities
and ignore prepare_scene.py in .gitignore.

* updated docs

Author: krrishj18

.agents/skills/write-isaac-sim-scene/SKILL.md

@@ -118,6 +118,19 @@ import threading
 import signal
 import atexit
 import time
+
+# Scene preparation utilities (scaling, collision, lighting, export)
+# NOTE: importlib is used instead of a normal import because Isaac Sim's
+# script runner does not reliably set __file__, making sys.path manipulation
+# fragile. Loading the module by absolute file path is the robust approach.
+import importlib.util as _ilu, os as _os
+_scene_prep_path = _os.path.join(_os.path.dirname(_os.path.abspath(__file__)), "..", "utils", "scene_prep.py")
+_spec = _ilu.spec_from_file_location("scene_prep", _os.path.normpath(_scene_prep_path))
+_scene_prep = _ilu.module_from_spec(_spec); _spec.loader.exec_module(_scene_prep)
+scale_stage_prim            = _scene_prep.scale_stage_prim
+add_colliders               = _scene_prep.add_colliders
+add_dome_light              = _scene_prep.add_dome_light
+save_scene_as_contained_usd = _scene_prep.save_scene_as_contained_usd
 ```
 
 ### 4. Enable Required Extensions
@@ -176,7 +189,11 @@ class YourSceneApp:
 
         # Load environment
         self.load_environment()
-        
+
+        # Prepare environment (scale, colliders, lighting)
+        stage = omni.usd.get_context().get_stage()
+        self._prepare_environment(stage)
+
         # Spawn vehicles
         self.spawn_vehicles()
 
@@ -200,25 +217,22 @@ class YourSceneApp:
         # Option 3: Load custom USD environment
         # stage = self.pg.load_environment("/path/to/your/environment.usd")
 
-        # Add lighting (if not in loaded environment)
-        self._setup_lighting()
-        
         # Add obstacles or other static objects
         self._add_environment_objects()
-    
-    def _setup_lighting(self):
-        """Configure scene lighting."""
-        stage = omni.usd.get_context().get_stage()
-        
-        # Create distant light (sun)
-        distant_light = UsdLux.DistantLight.Define(stage, "/World/DistantLight")
-        distant_light.CreateIntensityAttr(1000.0)
-        distant_light.CreateAngleAttr(0.5)
-        distant_light.AddOrientOp().Set(Gf.Quatf(0.7071, 0.7071, 0, 0))  # Point down
-        
-        # Create ambient light
-        dome_light = UsdLux.DomeLight.Define(stage, "/World/DomeLight")
-        dome_light.CreateIntensityAttr(500.0)
+
+    def _prepare_environment(self, stage):
+        """Scale, add collisions, and light the environment."""
+        stage_prim = stage.GetPrimAtPath("/World/stage")
+        if stage_prim.IsValid():
+            # STAGE_SCALE: use 0.01 for Nucleus assets authored in cm, 1.0 if already in meters
+            scale_stage_prim(stage, "/World/stage", STAGE_SCALE)
+            add_colliders(stage_prim)
+            # Allow physics to settle after adding colliders
+            for _ in range(10):
+                omni.kit.app.get_app().update()
+        # add_dome_light defaults: intensity=3500, exposure=-3
+        # Override via kwargs, e.g. add_dome_light(stage, intensity=5000, exposure=-2)
+        add_dome_light(stage)
 
     def _add_environment_objects(self):
         """Add obstacles or other objects to the environment."""
@@ -498,6 +512,27 @@ Any limitations or known problems.
 
 ## Advanced Topics
 
+### Scene Preparation Utilities
+
+**File:** `simulation/isaac-sim/utils/scene_prep.py`
+
+Four reusable helpers that cover the most common environment setup tasks. Import them as shown in Step 3.
+
+| Function | When to use |
+|----------|-------------|
+| `scale_stage_prim(stage, prim_path, scale)` | Nucleus assets authored in centimetres need `STAGE_SCALE=0.01`; assets already in metres use `1.0`. |
+| `add_colliders(stage_prim)` | **Must** be called for physics to interact with environment meshes. Without it drones fall through the floor. Call after scaling. |
+| `add_dome_light(stage, **kwargs)` | Adds uniform hemisphere lighting. Defaults: `intensity=3500`, `exposure=-3`. Pass kwargs to override, e.g. `add_dome_light(stage, intensity=5000)`. |
+| `save_scene_as_contained_usd(src_url, output_dir)` | Copies a Nucleus-hosted stage (and all its textures/MDLs) to a local directory using `omni.kit.usd.collect.Collector`. Useful for archiving or offline replay. |
+
+**Two-step save pattern** used internally by `save_scene_as_contained_usd`:
+1. `export_as_stage_async` — writes a flat `.usd` of the live stage
+2. `Collector` — resolves and copies all referenced Nucleus assets locally
+
+Set `SAVE_SCENE_TO = None` in your script to skip saving entirely.
+
+---
+
 ### Multi-Robot Scenarios
 
 For multiple robots, spawn additional vehicles with unique IDs and ports:
@@ -578,6 +613,10 @@ def _add_dynamic_obstacle(self):
   - ✅ Position sensors outside vehicle collision geometry
   - ✅ Typical camera position: forward of vehicle center
 
+### Missing Colliders on Environment Meshes
+- ❌ Loading a Nucleus environment without calling `add_colliders()`
+  - ✅ Call `add_colliders(stage_prim)` after scaling — drones will fall through the floor otherwise
+
 ### World Reset
 - ❌ **Not calling world.reset()**
   - ✅ Call world.reset() after adding all objects before stepping
@@ -626,6 +665,9 @@ docker exec airstack-isaac-sim-1 bash -c "ros2 topic hz /drone1/sensors/camera/i
   - Single drone: `simulation/isaac-sim/launch_scripts/example_one_px4_pegasus_launch_script.py`
   - Two drones: `simulation/isaac-sim/launch_scripts/example_two_px4_pegasus_launch_script.py`
 
+- **Scene Preparation Utilities:**
+  - `simulation/isaac-sim/utils/scene_prep.py`
+
 - **Related Skills:**
   - [test-in-simulation](../test-in-simulation) - Testing modules in Isaac Sim
   - [debug-module](../debug-module) - Debugging simulation issues

.gitignore

@@ -64,4 +64,5 @@ nucleus_token.txt
 # mkdocs
 mkdocs.log
 
-prompts/
+prompts/
+simulation/isaac-sim/launch_scripts/prepare_scene.py

docs/simulation/isaac_sim/pegasus_scene_setup.md

@@ -41,35 +41,75 @@ This is toggled by the `ISAAC_SIM_USE_STANDALONE` variable in the `.env` file. I
 
 ## Scripted Scene Generation
 
-Example scripts for generating a scene are provided in `AirStack/simulation/isaac-sim/launch_scripts/`
-You can also write your own scripts for your own custom scenarios.
+Python scripts give full programmatic control over every aspect of scene construction at startup, making them especially useful for:
 
-When using the scripted launch method:
+- **Reproducible scenarios** — the entire scene is defined in code, not a saved USD file.
+- **Nucleus asset integration** — loading `omniverse://` assets that need unit conversion or collision baking before use.
+- **Multi-robot setups** — dynamically spawning N drones with distinct IDs and positions.
+- **CI / headless testing** — running without a GUI.
+
+Example scripts are provided in `simulation/isaac-sim/launch_scripts/`.
+
+### Scene Preparation Utilities
+
+**Location:** `simulation/isaac-sim/utils/scene_prep.py`
+
+`scene_prep.py` provides helpers that are shared across all example launch scripts:
+
+| Function | Purpose |
+|----------|---------|
+| `scale_stage_prim(stage, prim_path, scale_factor)` | Applies a uniform XYZ scale transform to the prim at `prim_path`, clearing any existing xform ops first. Use `0.01` for Nucleus assets authored in centimetres; use `1.0` for assets already in metres. |
+| `add_colliders(stage_prim)` | Recursively walks every child of `stage_prim` and applies `UsdPhysics.CollisionAPI` to each `UsdGeom.Mesh`. **Must be called or drones fall through the floor.** Skips prims that already have the API. |
+| `add_dome_light(stage, intensity=3500, exposure=-3)` | Adds a hemisphere light at `/World/DomeLight` (or updates it if it already exists). Pass `intensity` / `exposure` keyword arguments to override the defaults. |
+| `save_scene_as_contained_usd(source_usd_url, output_dir)` | Copies the stage and all its dependencies (textures, MDL materials) from a Nucleus `omniverse://` URL into a local directory via `omni.kit.usd.collect.Collector`. Set `SAVE_SCENE_TO = None` in your script to skip this step. |
+| `get_stage_meters_per_unit(stage)` | Returns `(meters_per_unit, scene_scale_factor)`. Multiply metric coordinates by `scene_scale_factor` to convert them into stage-space units. Useful for computing drone spawn heights when `STAGE_SCALE != 1.0`. |
+
+#### Loading `scene_prep`
+
+`scene_prep.py` lives in `utils/`, which is not on `sys.path` by default. The example scripts add it at runtime before importing:
+
+```python
+import sys
+import os
+
+sys.path.insert(0, os.path.normpath(os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "utils")))
+import scene_prep
+from scene_prep import scale_stage_prim, add_colliders, add_dome_light, save_scene_as_contained_usd
+```
+
+
+
+### Running a Standalone Script
+
+Set the following variables in the top-level `.env` file and then launch as normal:
 
-1. Define your desired script in the `.env` file and run
 ```bash
+# .env
+ISAAC_SIM_USE_STANDALONE=true
+ISAAC_SIM_SCRIPT_NAME=example_one_px4_pegasus_launch_script.py
+```
+
+```bash
+# Start Isaac Sim with the selected script
 airstack up isaac-sim
+
 ```
-This will start Isaac Sim and generate the drone(s) within the scene.
 
-2. Stop the simulation by pressing the square “Stop” button on the left side of the Isaac Sim interface.
-This is necessary before editing the OmniGraph.
+Scripts must live in `simulation/isaac-sim/launch_scripts/`. Set `ISAAC_SIM_SCRIPT_NAME` to the filename only (no path).
 
-![Stop Sim Button](pegasus_setup_images/stop_button.png)
+---
 
-3. Open and connect the OmniGraph:
-  - Right-click the graph and choose “Open Graph.”
-  - Connect the ROS2Context node so that it feeds into all desired sensor subgraphs (e.g., cameras, LiDARs).  
-  ![Connected Subgraphs](pegasus_setup_images/connected_sensor_subgraphs.png)
-  > This manual step is temporarily required due to a known bug. Automation of this is planned in a future update.
+### Common Pitfalls
 
-4. Save the scene and drones once everything is connected.
-  - You can save both the stage and the drone USDs for future reuse.  
-  ![Saving Scene](pegasus_setup_images/saving_scene.png)
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Drone falls through the floor immediately | `add_colliders` was not called | Call `add_colliders(stage_prim)` after loading the environment |
+| Colliders applied to wrong-scale geometry | `add_colliders` called before `scale_stage_prim` | Always call `scale_stage_prim` first, then `add_colliders` |
+| Physics behaves erratically after colliders added | Update frames not pumped after `add_colliders` | Pump at least 10 `omni.kit.app.get_app().update()` calls after `add_colliders` |
+| `ImportError: No module named 'omni'` at script top | `omni` imported before `SimulationApp()` | Move all `omni.*` imports to after the `SimulationApp(...)` line |
+| `scene_prep` not found / `ModuleNotFoundError` | `utils/` not on `sys.path` in Isaac Sim's Python | Use `sys.path.insert` to add the `utils/` directory before importing `scene_prep` |
+| Drone spawns at wrong height in cm-scale scene | Spawn coordinates not converted to stage space | Multiply metric `init_pos` values by `scene_scale` from `get_stage_meters_per_unit` |
 
-5. Update your environment variables:
-  - Set the ISAAC_SIM_GUI variable to point to your newly saved .usd file (make sure to put the path within the docker container or in the omniverse server)
-  - Set ISAAC_SIM_USE_STANDALONE to "false" to load this saved environment directly next time.
 
 ## Known bugs and workarounds for Scripted Scene Generation
 
@@ -94,4 +134,6 @@ Occasionally, the right camera in a stereo camera pair may fail to initialize.
 The drone not arming/taking off can be a symptom of the PX4Multirotor Node not being recognized in omnigraph. This may be due the `pegasus.simulator` extension not being loaded.
 
   - To fix, launch the simulator with `airstack up isaac-sim`, in the toolbar, click Window -> Extensions -> Third Party, serach for "pegasus", select the "PEGASUS SIMULATOR" and enable "AUTOLOAD"
-  - Restart your docker container by running `airstack down isaac-sim && airstack up isaac-sim` and the extension should load every time now.
+  - Restart your docker container by running `airstack down isaac-sim && airstack up isaac-sim` and the extension should load every time now.
+
+---