Supported Hands#

The wrapper accepts native GraspIt! robot XML and exports compatible MuJoCo palm-and-finger models to the same interface. Model support is specified by the kinematic representation and evaluated operations. A native model supplies its own joint transmission and closure behavior. An exported model supplies serial hinge chains, collision geometry, and an affine map from independent coordinates to source hinges. The theory guide defines the map and coordinate conventions; the export guide describes source triangles and compiled collision hulls.

Model Coverage#

Hand

Model Interface

Geometry Coverage

Evaluated Operation

RealHand L6, right

MuJoCo export; 6 independent coordinates, 11 hinges

49 configurations per mode, 12 links

Planned key grasp and bimanual A7–L6 insertion

LEAP Hand

MuJoCo export; 16 independent coordinates, 16 hinges

4 configurations per mode, 17 links

Planned cube grasp and ZArm–LEAP lift-and-hold

PSYONIC Ability Hand

MuJoCo export; 6 independent coordinates, 10 hinges

12 configurations per mode, 11 links

Planned sphere grasp and Franka–Ability lift-and-hold

Barrett

Upstream native GraspIt! XML; 4 coordinates, 9 links

Native pose and contact queries

Cube closure, object-frame contacts, and wrench metrics

Shadow Hand, right palm

MuJoCo export; 18 independent coordinates, 22 hinges

5 configurations per mode, 23 links

Sphere closure, contacts, quality, and link-geometry queries

Inspire Hand, right

MuJoCo export; 6 independent coordinates, 12 hinges

5 configurations per mode, 13 links

Sphere closure, contacts, quality, and affine coupling

The export comparisons evaluated both source and convex_hull modes at the stated configurations. The planning gallery presents the planned and executed L6, LEAP, and Ability configurations.

Grasps on Native and Exported Hands#

The grasps below use the native robot interface for Barrett and the MuJoCo export profiles for Shadow and Inspire. Barrett grasps a 50 mm cube; Shadow and Inspire grasp a sphere of 60 mm diameter. Each image uses the queried closed joint state and object pose. Green markers identify recorded contacts; the annotations locate the fingers and palm/object frames. Select an image to view it at full size.

Hand

Object Contacts

Contacting Finger Chains

Native Ferrari–Canny Quality

Barrett

6

3

0.146

Shadow

11

5

0.423

Inspire

7

5

0.539

These scores describe normalized wrench resistance under GraspIt!’s native wrench-budget convention for each hand/object model. Higher values indicate greater worst-direction resistance under this convention. Comparisons require a common object, friction coefficient, moment scale, and force-budget convention.

The Barrett, Shadow, and Inspire records contain object-frame contact positions and inward normals, the object-relative palm pose, independent coordinates, and source asset hashes. They connect each illustrated configuration to its closure and numerical score.

The Shadow profile covers the palm and fingers; the two wrist joints remain outside the exported subtree. Its four distal pairs use an explicit equal-angle planning approximation, \(q_{J1}=q_{J2}\). The manufacturer’s model repository provides the broader hardware description. Contact-dependent tendon motion requires its own closure model; this affine profile specifies a kinematic planning model. The Inspire profile preserves six URDF mimic relations, including \(q_{\mathrm{intermediate}}=1.06399q_{\mathrm{proximal}}-0.04545\) rad for each non-thumb finger.

The GraspIt! Barrett assets and Inspire model collection provide model-source entry points. The evaluated Inspire source is the right-hand dex-urdf model at revision f5e7132, distributed under its MIT asset license. The evaluated Shadow source derives from the assets in XRoboToolkit’s hand example, with the equal-angle planning couplings stated above; its retained asset notices include Apache-2.0 and BSD-3-Clause. The validation record identifies exact source files by SHA-256. Users retain the source asset licenses when obtaining models; this wrapper does not redistribute those meshes.

Use the Native Barrett Model#

The Docker image includes the upstream GraspIt! model collection. From the wrapper repository, this command closes Barrett on the supplied 50 mm cube and records contacts, coordinates, and quality. The cube center is expressed in the hand frame in millimeters. The evaluated configuration returned six contacts and positive Ferrari–Canny quality.

mkdir -p output
docker run --rm --user "$(id -u):$(id -g)" \
  -v "$PWD/output:/output" graspit-py \
  xvfb-run -a python /src/examples/contact_quality.py \
  --robot /opt/graspit/models/robots/Barrett/Barrett.xml \
  --object /opt/graspit/models/objects/cube.xml \
  --object-position-mm 0 0 100 --out /output/barrett-cube.json

Prepare Shadow and Inspire Models#

Reusable profiles in examples/hand_profiles/ declare the palm root, expected independent-coordinate and hinge counts, preshape joints, and affine couplings. The preparation example resolves collision mesh paths and converts URDF mimics into MJCF joint equalities. For \(q_f=b+a q_d\), MuJoCo’s displacement-coordinate coefficients are \(c_0=b-q_f^0+a q_d^0\) and \(c_1=a\), where the superscript denotes a reference coordinate. This preserves the absolute URDF offset when reference coordinates are nonzero.

Place a source URDF and its meshes under input/. Replace the filename below with your local model. For Shadow, use shadow_right.json and a right-hand URDF with the named rh_* joints. Its profile makes the four planning couplings explicit and rejects conflicting source values. The Inspire profile retains the source’s six affine mimics.

.venv/bin/python examples/prepare_urdf_hand.py input/inspire_hand_right.urdf \
  output/inspire --profile examples/hand_profiles/inspire_right.json \
  --geometry-only

xvfb-run -a .venv/bin/python examples/export_hand_profile.py \
  output/inspire/scene.xml examples/hand_profiles/inspire_right.json \
  output/inspire-export --mesh-collision convex_hull --check

Install trimesh and yourdfpy in the native virtual environment for these URDF helpers. Preparation and export use the urdf and mjcf extras from Installation. Native GraspIt! is needed for --check. Preparation writes prepared.urdf, scene.xml, and preparation.json. The scene references source meshes, which must remain available. Resolve a package://name/path mesh URI with --package-root name=/absolute/package/root. A Docker invocation mounts the source directory read-only and the output directory writable.

Use --geometry-only for geometry-based GraspIt! planning: it removes source inertial elements so MuJoCo derives inertias from collision geometry during compilation. Omit it to retain input inertial elements. Both modes remove visual elements. Actuator definitions, calibrated physical parameters, and the execution controller belong to the source execution model.

Write a Profile for a New Hand#

A profile is an input to the example preparation and validation helpers. It describes the source model; it does not configure the native engine or declare independent-coordinate order. The exporter discovers that order and writes it to dof_joints in the manifest.

This minimal schema example assumes a palm named palm, an independent hinge finger_base, and a serial driven hinge finger_tip. Both hinge ranges are illustratively [0, 1] rad, with \(q_{\mathrm{finger\_tip}}=1.0q_{\mathrm{finger\_base}}+0.0\) rad. It is not a profile for an evaluated hand.

{
  "id": "my_hand",
  "palm": "palm",
  "independent_dofs": 1,
  "hinges": 2,
  "preshape_joints": [],
  "couplings": {
    "finger_tip": [1.0, 0.0]
  },
  "mimic_joints": {
    "finger_tip": {
      "driver": "finger_base",
      "ratio": 1.0,
      "offset_rad": 0.0
    }
  },
  "scope": "Illustrative serial finger; replace with the source model scope."
}

Set id to the export name and palm to the source root body. Set independent_dofs and hinges to the actual counts; the helper checks them. mimic_joints can install a missing URDF mimic and rejects a conflicting relation. Its driver must name an independent rotational joint; affine mimic chaining is unsupported. Ratios are dimensionless and offsets are in radians. couplings validates the exported multiplier and offset; it does not install a source equality by itself.

preshape_joints contains independent joint names held at their current caller-set values during autograsp. The empty list here allows the single independent coordinate to close. List finger_base only if you intend to hold it, and set its value before closure. scope records the modeled subtree and approximations. Run the preparation and export commands with the new profile and verify the resulting report.

Obtain RealHand L6 Source Assets#

The vendor’s right L6 directory provides realhand_l6_right.urdf and meshes. That source uses the palm hand_base_link and independent joints thunb_cmc_roll, thumb_cmc_pitch, index_mcp_pitch, middle_mcp_pitch, ring_mcp_pitch, and pinky_mcp_pitch. Preserve the vendor’s spelling thunb_cmc_roll when naming the joint. Its five distal mimic relations use a thumb multiplier of 2.22 and other multipliers of 1.9, with zero offsets.

These unprefixed names and source couplings differ from the evaluated L6 reference scene. The bundled examples/l6_workflow source scene requires external DexReach xarm7_l6 arm/hand meshes at revision c939934ca8e0b9b6dc336afe03c2e044b8b6ba8c. The public vendor model provides another source route; prepare its own profile and verify its export before use.

Verify Couplings and Geometry#

The profile exporter intersects each driven hinge’s limits with those of its independent coordinate. For \(q_i=a_i u_j+b_i\), it constrains \(u_j\) using \(q_i^{\min}\leq a_i u_j+b_i\leq q_i^{\max}\), reversing interval endpoints for a negative multiplier. With --check, it samples five interior configurations of the feasible intervals and queries native geometry at the applied coordinates. Source and hull comparisons use the same named coordinates and the corresponding geometric representation.

The output contains hand/<id>.xml, hand/<id>.json, hand/iv/, configurations.json, and profile-report.json. The report includes coordinate order, feasible intervals, model/profile hashes, and per-link errors.

Palm Model

Source-Mesh Maximum Error

Compiled-Hull Maximum Error

Requested-to-Applied Joint Error

Shadow

3.92 nm

3.92 nm

0 rad

Inspire

0.836 µm

1.29 µm

0 rad

These maxima cover every link across five configurations in each mode. The original native ShadowHand.xml uses fixed dynamic joints outside the current loader’s chain support; use the verified palm export profile for Shadow planning. The application supplies arm kinematics, execution controllers, and physical parameter identification.