Actor SDG Generate Lighting Variations

Purpose

Generate deterministic lighting variations without changing the base USD stage. Each output is a USD sublayer, a file that overrides selected properties from another stage. Use the sublayers with Isaac Sim Replicator Agent (IRA) through environment.prop_asset_paths.

Prerequisites

• An Isaac Sim install or source build exposed through $ISAAC_SIM_DIR.
• A local USD stage or an omniverse:// stage URL.
• A writable output directory, preferably under $WORKSPACE_DIR.
• The Isaac Sim Python launcher, because the generator uses pxr.

Limitations

• The generator changes existing DomeLight, DistantLight, SphereLight, RectLight, CylinderLight, and DiskLight prims. It does not create lights.
• The generated sublayers override intensity, color temperature, exposure, and optional color tint. They do not randomize light transforms or textures.
• A successful file-generation run does not prove that every variation renders well. Inspect representative frames before starting a large dataset run.
• omniverse:// inputs require an authenticated Omniverse connection in the Isaac Sim runtime.

Available Scripts

Running scripts

From agent runtimes that expose skill execution helpers, invoke the generator with run_script():

run_script(
    "scripts/lighting_variation_generator.py",
    args=["warehouse.usd", "--dry-run"],
)

From the repository root, use the Isaac Sim Python launcher:

"$ISAAC_SIM_DIR/python.sh" \
  skills/actor-sdg-generate-lighting-variations/scripts/lighting_variation_generator.py \
  warehouse.usd --dry-run

On Windows, replace python.sh with python.bat.

Workflow

1. Validate the stage

Run a dry scan before writing files:

"$ISAAC_SIM_DIR/python.sh" \
  skills/actor-sdg-generate-lighting-variations/scripts/lighting_variation_generator.py \
  warehouse.usd --dry-run

Stop if the stage cannot open or contains no supported lights. Report the discovered light paths and types.

2. Prepare the output

Use these defaults unless the user specifies other values:

The generator refuses to replace matching output files by default. If they exist, report their count and path. Pass --overwrite only after the user approves replacing those files.

3. Generate the sublayers

Run with explicit parameters:

"$ISAAC_SIM_DIR/python.sh" \
  skills/actor-sdg-generate-lighting-variations/scripts/lighting_variation_generator.py \
  warehouse.usd \
  --count 10 \
  --output-dir "$WORKSPACE_DIR/lighting_variations" \
  --seed 42 \
  --intensity-range 0.3 3.0 \
  --temperature-range 2700 7500 \
  --exposure-range -2.0 2.0 \
  --color-tint 0.0

The same stage, seed, parameters, and output names produce the same results. This is idempotent: repeating the command produces the same final files.

4. Verify the outputs

1. Confirm the command exits with code 0.
2. Confirm the number of generated .usda files matches --count.
3. Read manifest.csv and one generated sublayer.
4. Confirm the sample contains only lighting override opinions.
5. Add one generated path to environment.prop_asset_paths and render a representative frame.

5. Report the result

Report the base stage, output directory, count, seed, parameter ranges, manifest path, and checks performed. Do not claim that the outputs rendered correctly unless a render check completed.

Troubleshooting