Scene loaders

Rapier provides companion crates converting some popular robotics formats into the rigid-bodies, the colliders, and the joints they contain. Note that these crates are 3D only, and that they are released separately from rapier3d itself.

URDF

The rapier3d-urdf crate loads the Unified Robot Description Format used by the ROS community. A robot is read from a URDF file (or from a string), and is then inserted into the sets either with impulse joints or with multibody joints.

info

Robotics generally care a lot about joint violation. Then inserting the model using multibody joints is strongly recommended since they guarantee the absence of joint violation by encoding the locked degrees of freedom into the equations of motion directly instead of relying on the constraints solver (which might not converge).

let mut world = PhysicsWorld::new();

// Read the robot, then insert its links and joints into the world.
let (robot, _) = UrdfRobot::from_file("robot.urdf", UrdfLoaderOptions::default(), None)?;
let handles = robot.insert_using_multibody_joints(
    &mut world.bodies,
    &mut world.colliders,
    &mut world.multibody_joints,
    Default::default(),
);
println!("The robot has {} links.", handles.links.len());

warning

The meshes referenced by an URDF file are only loaded if the corresponding cargo feature of the crate is enabled: stl for the .stl files, collada for the .dae files, and wavefront for the .obj files. Note that a joint inserted as a multibody joint is reset to its neutral position, i.e., all of its coordinates are zero.

MJCF

The rapier3d-mjcf crate loads the MJCF XML format of MuJoCo. We recommend browsing the MuJoCo Menagerie repository which contains many MJCF models.

let mut world = PhysicsWorld::new();

// Read the model, then insert its bodies and joints into the world.
let (robot, _model) = MjcfRobot::from_file("robot.xml", MjcfLoaderOptions::default())?;
robot.insert_using_impulse_joints(
    &mut world.bodies,
    &mut world.colliders,
    &mut world.impulse_joints,
);

note

Note that MJCF sometimes describes a whole simulation and not only a scene, therefore some of its elements have no equivalent in Rapier, and some others are approximated.

Meshes

The rapier3d-meshloader crate builds shapes from the usual mesh files, which is what both the MJCF and URDF loaders use internally. It is useful on its own whenever the collision geometry of a scene comes from an asset file rather than from primitive shapes. The formats it reads are selected by its cargo features: stl, collada, and wavefront. Each mesh of the file becomes one shape, converted as selected by the MeshConverter:

let mut world = PhysicsWorld::new();

// Every mesh of the file becomes one shape, converted here into its convex hull.
let shapes = load_from_path("asset.obj", &MeshConverter::ConvexHull, Vector::splat(1.0))?;
for shape in shapes.into_iter().flatten() {
    world.insert_collider(ColliderBuilder::new(shape.shape).position(shape.pose), None);
}