Creating SurfaceGripper from Scratch

[fhndan89]

Hello everybody,

I want to create a SurfaceGripper completely in code.
This means I don’t want to load a USD-File which already has all necessary functions included.
So, I need to create the joint myself. This is the code I used to create it:

def create_joint(self) -> None:
    self._usd_context = omni.usd.get_context()
    self._stage = self._usd_context.get_stage()
    for i in range(self.num_grippers):
        prim_utils.create_prim(f"/World/envs/env_{i}/robot/suction_cups_joints", "Xform")

        d6Joint = UsdPhysics.Joint.Define(self._stage, f"/World/envs/env_{i}/robot/suction_cups_joints/joint0")
        d6Joint.CreateBody0Rel().SetTargets([Sdf.Path(f"/World/envs/env_{i}/robot/suction_cups/cup0")])
        d6Joint.CreateBody1Rel().SetTargets([Sdf.Path(f"/World/envs/env_{i}/robot/surface_gripper_ref")])
        d6JointPrim = d6Joint.GetPrim()

        locked_axes = [
            UsdPhysics.Tokens.transX, UsdPhysics.Tokens.transY, UsdPhysics.Tokens.transZ,
            UsdPhysics.Tokens.rotZ
        ]
        for locked_axis in locked_axes:
            limitAPI = UsdPhysics.LimitAPI.Apply(d6JointPrim, locked_axis)
            limitAPI.CreateLowAttr(0.0)
            limitAPI.CreateHighAttr(0.0)

            linearDriveAPI = UsdPhysics.DriveAPI.Apply(d6JointPrim, locked_axis)
            linearDriveAPI.CreateStiffnessAttr(10e6)
            linearDriveAPI.CreateDampingAttr(10e6)

        limit_axes = [
            UsdPhysics.Tokens.rotX, UsdPhysics.Tokens.rotY
        ] 
        for limit_axis in limit_axes:
            limitAPI = UsdPhysics.LimitAPI.Apply(d6JointPrim, limit_axis)
            limitAPI.CreateLowAttr(-self.config["suction_cup"]["limits_rotation"]/2)
            limitAPI.CreateHighAttr(self.config["suction_cup"]["limits_rotation"]/2)

            linearDriveAPI = UsdPhysics.DriveAPI.Apply(d6JointPrim, limit_axis)
            linearDriveAPI.CreateStiffnessAttr(5000.0)
            linearDriveAPI.CreateDampingAttr(1000.0)
    return None

And this is the code to create the gripper afterwards:

def create_virtual_gripper(self) -> None:
        self.virtual_grippers_config = SurfaceGripperCfg(
            prim_expr=f"{self.prim_paths_robot}/surface_gripper_ref/SurfaceGripper",
            max_grip_distance= 0.1,# self.config['suction_cup']['height'],
            coaxial_force_limit=self.coaxial_force_limit,
            shear_force_limit=self.shear_force_limit,
            retry_interval=1/60
            )
        for i in range(self.num_grippers):
            gripper_joint = [
                p.GetPath() for p in self._stage.GetPrimAtPath(f"/World/envs/env_{i}/robot/suction_cups_joints").GetChildren()
            ]
            joint_prim = self._stage.GetPrimAtPath(gripper_joint[0])
            robot_schema.ApplyJointAPI(joint_prim)
            robot_schema.ApplyAttachmentPointAPI(joint_prim)
            gripper_prim_path = f"/World/envs/env_{i}/robot/surface_gripper_ref"
            self.gripper_interface = surface_gripper.acquire_surface_gripper_interface()

            result, gripper_prim  = omni.kit.commands.execute(
                "CreateSurfaceGripper",
                prim_path=gripper_prim_path,
            )
            attachment_points_rel = gripper_prim.GetRelationship(robot_schema.Relations.ATTACHMENT_POINTS.name)

            attachment_points_rel.SetTargets(gripper_joint)

            gripper_prim.GetAttribute(robot_schema.Attributes.MAX_GRIP_DISTANCE.name).Set(0.0)
            gripper_prim.GetAttribute(robot_schema.Attributes.COAXIAL_FORCE_LIMIT.name).Set(0.0)
            gripper_prim.GetAttribute(robot_schema.Attributes.SHEAR_FORCE_LIMIT.name).Set(0.0)
            gripper_prim.GetAttribute(robot_schema.Attributes.RETRY_INTERVAL.name).Set(0.0)
        self.virtual_grippers = SurfaceGripper(cfg=self.virtual_grippers_config)
        return None

I was already able to find the command to apply the AttachmendPointAPI:
robot_schema.ApplyAttachmentPointAPI(joint_prim)

When I check the “Property” of the joint in the simulation, I can see that everything should be setup correctly:

However, I get the following Warning:

2025-08-22T14:09:37Z [24,986ms] [Warning] [isaacsim.robot.surface_gripper.plugin] Gripper /World/envs/env_0/robot/surface_gripper_ref/SurfaceGripper has no joint at attachment point /World/envs/env_0/robot/suction_cups_joints/joint0

And I cannot pick up work pieces.
Additionally, I would like to know how te set the “Clearance Offset” and the “Forward Axis” with a command.
Also, I run the script in IsaacLab and not in IsaacSim. However, the warning comes from IsaacSim. That’s why I post it here. And I checked the source code of the IsaacLab-API. In the end it creats a GripperView and calls it during the execution.
How can I fix my code to be able to grasp something?

[vick-yu]

Given that your script uses modules and classes specific to Isaac Lab, the most effective place to get support is on the Isaac Lab GitHub repository.

The developers and community members there are more familiar with the framework's internal workings and can provide specialized assistance for issues like this. You can find the discussion forums at isaac-sim/IsaacLab/discussions.