Python API¶
The native bindings expose simulator operations. The contact planner uses those operations to generate and rank approach candidates. The MuJoCo exporter operates on a compiled MuJoCo model, and the numerical utilities operate on arrays or exported XML. GraspIt! has one main world per process. Use a process per independent native scene and a virtual X display for headless execution.
Native Bindings¶
Import graspit_python_wrapper.core.bindings and call initialize().
Construct World() and call world.init() before loading geometry.
Call world.clear() to remove the loaded robots and bodies.
Operation |
API |
|---|---|
Load geometry |
|
Read or set hand pose |
|
Read or set finger coordinates |
|
Read object pose |
|
Close the hand |
|
Check interpenetration |
|
Query link geometry |
|
Pose dictionaries provide a scalar-first quaternion quat_wxyz,
translation in millimeters, row-major rotation matrix, and homogeneous
transform. Joint coordinates are in radians. Link poses and vertices are
expressed in the world frame. Use chain -1 for the palm.
Construct Grasp(world, graspable_body_index=0) and call compute()
after placing and closing the hand. Read object_contact_geometry() for
points in millimeters and inward normals in the object frame.
epsilon_quality() and volume_quality() return the native GraspIt!
wrench-space metrics. Grasp.is_non_penetrating() reports the validity
of the grasp under GraspIt!’s grasp criteria. To query collision in the
world, call World.no_collision().
Contact Planner¶
Import ContactPlanner, HandFrame, and PlannerConfig from
graspit_python_wrapper.planning. Set the hand and object in the
world before constructing the planner. The planner captures the current
object pose and center of mass on construction.
from graspit_python_wrapper.planning import (
ContactPlanner,
HandFrame,
PlannerConfig,
)
frame = HandFrame(
approach_axis=(0, 0, 1),
finger_axis=(1, 0, 0),
grasp_center_mm=(0, 0, 65),
)
config = PlannerConfig(
approaches=[(0, 0, 1, 0), (0, 0, 1, 45), (0, 0, 1, 90)],
standoff_mm=80,
pose_sigma_mm=0.25,
pose_sigma_deg=0.5,
n_pose_samples=2,
friction_samples=[0.3, 0.6, 0.9],
tail_mass=0.5,
)
candidates = ContactPlanner(world, body_index=0, config=config, hand=frame).plan(top_k=2)
Each GraspCandidate contains the nominal hand pose, closed
coordinates, contacts, and sampled scores. to_dict() returns the
representation written by the CLI. The planning guide
defines the settings and returned arrays.
MuJoCo Exporter¶
Install the mjcf extra or mujoco>=3.1, then import from
graspit_python_wrapper.convert.mjcf_hand.
Function |
Result |
|---|---|
|
|
|
Path to the GraspIt! object XML. |
|
Independent MuJoCo hinge coordinates in GraspIt! order. |
Numerical Utilities¶
These modules can be imported from the source checkout without a native GraspIt! build when NumPy and SciPy are available.
graspit_python_wrapper.risk.lower_tail_mean(values, alpha=..., weights=...)averages the smallestalphaprobability mass of a quality distribution.risk.cvar(costs, alpha=..., weights=...)averages the largestalphamass of a cost distribution. Optional weights are normalized to sum to one.graspit_python_wrapper.kinematics.load_chains(robot_xml)reads Denavit–Hartenberg chains.link_poses(chains, dofs)returns palm-frame transforms keyed by(chain, link).graspit_python_wrapper.grasp.qualityprovidesbuild_grasp_matrix(),analyze_gws(), andcompute_task_wrench_quality(). The grasp matrix stores force components first and normalized torque components second. Supply the same moment origin and torque scale for the contact wrench generators and the required task wrenches.