Gripper Set USD

SUMMARY

Set USD chooses the USD asset a simulated suction gripper is loaded from the next time it connects to a prim that does not yet exist in the stage.

This skill is used to bring a specific gripper model into a stage, or swap in a different one, without importing it by hand first.

UNITS

usd accepts three forms: a bundle published on the asset server (e.g. "tools/suction_grippers/defitech_modelled_surface_gripper"), an HTTP(S) URL of a .zip bundle, or a path on this machine to a .usd file, a bundle directory, or a .zip.

The Skill

gripper.set_usd("tools/suction_grippers/defitech_modelled_surface_gripper")

The Code

"""
Demonstrates loading a suction gripper into the stage from a chosen USD asset.

Supports Isaac Sim only, so the example needs an Isaac Sim gripper prim path;
without one it reports that and exits, which is why running it as part of a
hardware run of run_all_examples.py does nothing.

Note:
    Connecting to a prim path that is not in the open stage loads the gripper
    there from the asset set here, so it does not have to be imported by hand
    first. A prim path that is already in the stage is used as it is and the
    asset is ignored, so this runs against either stage.

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

import argparse
from loguru import logger

from telekinesis.synapse.tools.suction_grippers import isaacsim


def main(prim_path: str | None, usd: str) -> None:
    """Loads the gripper from the given USD asset and reports where it came from."""

    if not prim_path:
        logger.warning(
            "set_usd() loads a gripper into an Isaac Sim stage, so this "
            "example needs --prim_path. Skipping."
        )
        return

    #===================== Create Gripper ======================================
    gripper = isaacsim.SuctionGripper()

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

        #===================== Connect Gripper =================================
        gripper.connect(simulation_prim_path=prim_path)

        logger.success(f"Gripper at {prim_path} is loaded from {gripper.usd_path}.")
    except (ConnectionError, OSError) as e:
        logger.error(f"Error occurred: {e}")
    finally:
        if gripper.is_connected:
            gripper.disconnect()


if __name__ == "__main__":
    p = argparse.ArgumentParser(description="Suction gripper set USD asset")
    p.add_argument("--prim_path", type=str, default=None,
                   help='Isaac Sim gripper prim path, e.g. "/World/suction_gripper"')
    p.add_argument("--usd", type=str,
                   default="tools/suction_grippers/defitech_modelled_surface_gripper",
                   help="Bundle on the asset server, an HTTP(S) URL of a .zip "
                        "bundle, or a path on this machine to a .usd file, a "
                        "bundle directory or a .zip")
    args = p.parse_args()

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

Running the Example

python set_usd.py --prim_path /World/suction_gripper

To load a different bundle:

python set_usd.py --prim_path /World/suction_gripper --usd tools/suction_grippers/suction_gripper_large

For all options:

python set_usd.py --help

Parameter Configuration

Parameter	Type	Default	Description
usd	str | pathlib.Path	-	The asset, in one of three forms: a bundle published on the asset server, e.g. "tools/suction_grippers/defitech_modelled_surface_gripper"; an HTTP(S) URL of a .zip bundle; or a path on this machine — a .usd file, a bundle directory, or a .zip.

Returns

This skill returns nothing (None).

Raises

Exception	Condition
TypeError	usd is empty
NotImplementedError	The gripper is not modelled as a USD asset and does not support set_usd

How to Tune the Parameters

set_usd only takes effect on the next connect to a prim path that does not yet exist in the stage — a prim already in the stage is used as it is and the asset is ignored. Calling it while already connected logs a warning, since the new asset is not picked up until the next connect.

Where to Use the Skill

• Loading a specific gripper model - Call before connect to bring a chosen gripper into a stage that has none yet
• Swapping grippers between runs - Point at a different bundle or local .usd file without editing the stage by hand

When Not to Use the Skill

Do not use Set USD when:

• The target prim path already exists in the stage - the existing prim is used as-is and the asset is ignored
• Expecting it to take effect on an already-connected gripper - it only applies on the next connect, not retroactively