Weld Gun Set USD

SUMMARY

Set USD chooses the USD asset a simulated spot-welding gun 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 gun 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/welding_guns/spot_welding_gun"), 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

gun.set_usd("tools/welding_guns/spot_welding_gun")

The Code

"""
Demonstrates loading a spot-welding gun into the stage from a chosen USD asset.

Supports Isaac Sim only.

Note:
    Connecting to a prim path that is not in the open stage loads the gun there
    from the asset set here, so the gun 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.welding_guns import isaacsim


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

    # ===================== Create Gripper ======================================
    gun = isaacsim.SpotWeldingGun()

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

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

        logger.success(f"Gun at {prim_path} is loaded from {gun.usd_path}.")
        logger.info(f"Spark prims declared by the asset: {gun.spark_prim_paths}")
    except (ConnectionError, OSError) as e:
        logger.error(f"Error occurred: {e}")
    finally:
        if gun.is_connected:
            gun.disconnect()


if __name__ == "__main__":
    p = argparse.ArgumentParser(description="Spot-welding gun set USD asset")
    p.add_argument("--prim_path", type=str, default="/World/spot_welding_gun_modelled",
                   help='Isaac Sim gun prim path, e.g. "/World/spot_welding_gun_modelled"')
    p.add_argument("--usd", type=str, default="tools/welding_guns/spot_welding_gun",
                   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/spot_welding_gun_modelled

To load a different bundle:

python set_usd.py --prim_path /World/spot_welding_gun_modelled --usd tools/welding_guns/spot_welding_gun_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/welding_guns/spot_welding_gun"; 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 gun 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 gun model - Call before connect to bring a chosen gun into a stage that has none yet
• Swapping guns between runs - Point at a different bundle or local .usd file without editing the stage by hand
• Reading declared spark prims - After connecting, spark_prim_paths reports the spark prims the loaded asset declares

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 gun - it only applies on the next connect, not retroactively