Set USD (CNC)

SUMMARY

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

The Skill

machine.set_usd(
    "https://assets.telekinesis.ai/usd/machines/cnc_machine.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 door 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 CNC machine 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 door
    prim is missing from the open stage. An existing prim is used as it is and
    the configured asset is ignored.

    The open and closed positions are in meters relative to the door prim's
    parent. Read them from Property > Transform with the door fully open and
    fully closed.
"""

import argparse

from loguru import logger

from telekinesis.medulla.machines import isaacsim


def main(
    prim_path: str,
    usd: str,
    open_position: list[float],
    closed_position: list[float],
) -> None:
    """Load a CNC machine from a USD asset and connect to its door."""

    # ===================== Create Machine =====================================
    machine = isaacsim.CNCMachine(name="my_simulated_cnc_machine")

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

        # ===================== Connect Machine ================================
        machine.connect(
            simulation_prim_path=prim_path,
            open_position=open_position,
            closed_position=closed_position,
        )
        logger.success(f"Connected to CNC machine door at {prim_path}.")
    except (ConnectionError, RuntimeError, TypeError, ValueError) as e:
        logger.error(f"Error occurred: {e}")
    finally:
        machine.disconnect()


if __name__ == "__main__":
    p = argparse.ArgumentParser(description="Set a CNC machine USD asset")
    p.add_argument(
        "--prim_path",
        type=str,
        default="/World/cnc_machine/E_body_1/door",
        help="Isaac Sim CNC machine door prim path",
    )
    p.add_argument(
        "--usd",
        type=str,
        default="https://assets.telekinesis.ai/usd/machines/cnc_machine.zip",
        help="HTTP(S) bundle URL or local .usd, directory, or .zip path",
    )
    p.add_argument(
        "--open_position",
        type=float,
        nargs=3,
        default=[-0.68654, -0.05313, 1.208],
        metavar=("X", "Y", "Z"),
        help="Open door position in meters relative to the door parent",
    )
    p.add_argument(
        "--closed_position",
        type=float,
        nargs=3,
        default=[-0.2193, -0.05313, 1.208],
        metavar=("X", "Y", "Z"),
        help="Closed door position in meters relative to the door parent",
    )
    args = p.parse_args()

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

Running the Example

python set_usd.py --prim_path /World/cnc_machine/E_body_1/door

To select another asset:

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

For all options, including the required door-position coordinates:

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.

The example also supplies open_position and closed_position to connect(). Each is an (x, y, z) position in meters relative to the door prim's parent; these values describe the installed machine and are not part of set_usd().

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

Where to Use the Skill

Use Set USD before Connection and Disconnection when the stage may not already contain the CNC machine's door prim.