Skip to content

About

Python bindings, grasp planning, and MuJoCo model export for GraspIt!

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

GraspIt! Python Wrapper

Documentation · GraspIt! Simulator · arXiv Preprint (Coming Soon)

graspit_python_wrapper exposes the GraspIt! simulator as a Python library for grasp synthesis and evaluation with multifingered hands. The native bindings provide hand pose and joint control, autograsp, collision queries, contact geometry, and wrench-space metrics. The contact planner ranks simulated closures by Ferrari–Canny quality or task-wrench capacity under approach and friction uncertainty. The MuJoCo exporter generates GraspIt! hand and object descriptions and records the joint correspondence for transferring a planned configuration back to MuJoCo.

Installation on Linux

The reference build uses Ubuntu 24.04 and Python 3.12. Docker builds the pinned public GraspIt! source with the supplied compatibility patch.

git clone https://github.com/coenwerem/graspit-python-wrapper.git
cd graspit-python-wrapper
docker buildx build --load -f docker/Dockerfile -t graspit-py .

The installation guide also covers native builds and headless execution.

Grasp Planning

The RealHand L6 walkthrough uses a user-supplied MuJoCo model of the right hand and a 50 mm cube. For an existing GraspIt! model, pass the robot XML, object XML, and a JSON configuration defining the hand axes, approach search, and any task loads. From the directory containing those files, run the planner in the Docker image.

docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" graspit-py \
    xvfb-run -a python -m graspit_python_wrapper.planning \
    --robot hand.xml --object object.xml \
    --config problem.json --out candidates.json

Each candidate contains the object-relative palm pose, closed joint coordinates, object-frame contacts, and sampled wrench scores. The theory guide defines those quantities and their coordinate conventions. The supported-hands guide documents native Barrett support and export coverage for the RealHand L6, LEAP, PSYONIC Ability, Shadow, and Inspire hands. It provides runnable kinematic profiles and records the operations evaluated for each model. The calling application supplies arm kinematics, trajectory planning, and execution.

Planned Grasps and Simulated Execution

RealHand L6 LEAP Hand PSYONIC Ability Hand
RealHand L6 fingers closed on the blue insertion key LEAP Hand holding a blue cube PSYONIC Ability Hand holding a blue sphere
Planned key grasp Simulated cube hold Simulated sphere hold

The RealHand L6 image shows the planned GraspIt! closure. The LEAP and Ability images show final configurations from recorded MuJoCo lift-and-hold simulations. The planning guide reports Ferrari–Canny scores for the RealHand L6 and LEAP grasps.

Barrett Hand Shadow Hand Inspire Hand
Native Barrett cube grasp with finger labels, contact markers, and palm and object frames Exported Shadow Hand sphere grasp with finger labels, contact markers, and palm and object frames Exported Inspire Hand sphere grasp with finger labels, contact markers, and palm and object frames
Six contacts, Ferrari–Canny ε = 0.14587 Eleven contacts, Ferrari–Canny ε = 0.42337 Seven contacts, Ferrari–Canny ε = 0.53871

These GraspIt! closures use the native Barrett model and the Shadow and Inspire export profiles. The hand-model guide provides the illustrated grasp records, model sources, and coordinate conventions.

MuJoCo Model Export

MuJoCo Source Workcell Exported RealHand L6 in GraspIt!
MuJoCo workcell with two A7 arms and RealHand L6 hands during bimanual key insertion GraspIt! export of the right RealHand L6 at the planned insertion-key grasp

The MuJoCo panel shows a recorded bimanual key insertion. The GraspIt! panel shows the exported right hand closed on the key from a second viewpoint. The export guide explains how to reconstruct planned configurations and compare link geometry.

The visualization roadmap specifies the planned standalone viewer for model correspondence, grasp records, contact normals, and frames.

Citation and References

Cite the wrapper using CITATION.cff and record the software revision used. The wrapper is licensed under GPL-3.0-or-later.

See the manual references for sources on hand posture, frictional contact, and grasp wrench spaces.

About

Python bindings, grasp planning, and MuJoCo model export for GraspIt!

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages