Set USD (LightBeam)

SUMMARY

Set USD configures the asset used when the requested lightbeam sensor prim is absent from the open Isaac Sim stage. An existing prim is used unchanged, so its authored asset is never replaced.

The Skill

sensor.set_usd(
    "https://assets.telekinesis.ai/usd/sensors/"
    "simple_light_beam_sensor.zip"
)

The asset may be an HTTP(S) URL to a .zip bundle or a local .usd file, bundle directory, or .zip file. URLs and local bundles are resolved only when connect() finds that the requested prim is missing. The resolved USD stage is added below /World/<USD file stem>.

Calling set_usd() while connected logs a warning. The new asset applies to the next connection after disconnect().

The Code

"""Load a lightbeam sensor into an Isaac Sim stage from a USD asset.

Supports Isaac Sim only.

Usage:
    python set_usd.py --prim_path <PRIM_PATH>
    python set_usd.py --prim_path <PRIM_PATH> --usd <BUNDLE_URL_OR_PATH>

Note:
    Open Isaac Sim before running this. The asset is loaded only when the
    sensor prim is missing from the open stage. An existing prim is used as
    it is and the configured asset is ignored.
"""

import argparse

from loguru import logger

from telekinesis.medulla.sensors import isaacsim


def main(prim_path: str, usd: str) -> None:
    """Load a lightbeam sensor from a USD asset and connect to it."""

    # ===================== Create Sensor ======================================
    sensor = isaacsim.LightBeamSensor(name="my_simulated_lightbeam")

    try:
        # ==================== Run Skill =======================================
        sensor.set_usd(usd)

        # ===================== Connect Sensor =================================
        sensor.connect(simulation_prim_path=prim_path)
        logger.success(f"Connected to lightbeam sensor at {prim_path}.")
    except (ConnectionError, RuntimeError, TypeError) as e:
        logger.error(f"Error occurred: {e}")
    finally:
        sensor.disconnect()


if __name__ == "__main__":
    p = argparse.ArgumentParser(description="Set a lightbeam sensor USD asset")
    p.add_argument(
        "--prim_path",
        type=str,
        default="/World/simple_light_beam_sensor/LightBeam_Sensor",
        help="Isaac Sim lightbeam sensor prim path",
    )
    p.add_argument(
        "--usd",
        type=str,
        default=(
            "https://assets.telekinesis.ai/usd/sensors/"
            "simple_light_beam_sensor.zip"
        ),
        help="HTTP(S) bundle URL or local .usd, directory, or .zip path",
    )
    args = p.parse_args()

    main(prim_path=args.prim_path, usd=args.usd)

Running the Example

python set_usd.py --prim_path /World/simple_light_beam_sensor/LightBeam_Sensor

To select another asset:

python set_usd.py --prim_path <PRIM_PATH> --usd <BUNDLE_URL_OR_PATH>

For all options:

python set_usd.py --help

Parameter Configuration

Parameter	Type	Default	Description
usd	str | pathlib.Path	required	HTTP(S) URL of a .zip asset bundle, or a local .usd file, bundle directory, or .zip file.

Returns

Type	Description
None	set_usd() stores the asset for a later connect() call. It does not load the asset immediately.

Raises

Exception	Condition
TypeError	usd is an empty or whitespace-only string.

Asset resolution, download, and stage-loading failures occur later during connect() and are reported as RuntimeError by LightBeamSensor.connect().

Where to Use the Skill

Use Set USD before Connection and Disconnection when the stage may not already contain the lightbeam sensor prim.