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.
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.
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.jsonEach 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.
| RealHand L6 | LEAP Hand | PSYONIC Ability Hand |
|---|---|---|
![]() |
![]() |
![]() |
| 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 |
|---|---|---|
![]() |
![]() |
![]() |
| 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 Source Workcell | Exported RealHand L6 in GraspIt! |
|---|---|
![]() |
![]() |
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.
Cite the wrapper using CITATION.cff and record the software revision used. The wrapper is licensed under GPL-3.0-or-later.
- Miller, A. T., and Allen, P. K. (2004). GraspIt! A Versatile Simulator for Robotic Grasping. IEEE Robotics & Automation Magazine, 11(4), 110–122.
- Ferrari, C., and Canny, J. F. (1992). Planning Optimal Grasps. IEEE International Conference on Robotics and Automation.
- Todorov, E., Erez, T., and Tassa, Y. (2012). MuJoCo: A Physics Engine for Model-Based Control. IEEE/RSJ International Conference on Intelligent Robots and Systems.
- Rockafellar, R. T., and Uryasev, S. (2002). Conditional Value-at-Risk for General Loss Distributions. Journal of Banking & Finance, 26(7), 1443–1471.
- Enwerem, C., Baras, J. S., and Belta, C. (2026). FIRMGrasp: A Friction-Informed Risk Margin for Robust Grasp Synthesis. arXiv:2607.25049.
See the manual references for sources on hand posture, frictional contact, and grasp wrench spaces.







