Set USD (Conveyor)

SUMMARY

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

The Skill

belt.set_usd(
    "https://assets.telekinesis.ai/usd/conveyors/simple_conveyor.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 conveyor 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
    conveyor 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.conveyors import isaacsim


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

    # ===================== Create Conveyor ====================================
    belt = isaacsim.Conveyor(name="my_simulated_conveyor")

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

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


if __name__ == "__main__":
    p = argparse.ArgumentParser(description="Set a conveyor USD asset")
    p.add_argument(
        "--prim_path",
        type=str,
        default="/World/simple_conveyor",
        help="Isaac Sim conveyor prim path",
    )
    p.add_argument(
        "--usd",
        type=str,
        default=(
            "https://assets.telekinesis.ai/usd/conveyors/"
            "simple_conveyor.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_conveyor

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 Conveyor.connect().

Where to Use the Skill

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