Kris' Locomotion and Manipulation Planning Toolbox (Klamp't)

Klamp't is a cross-platform software package for modeling, simulating, planning, and optimization for complex robots, particularly for manipulation and locomotion tasks. It has been developed at Indiana University since 2009 primarily as a research platform, and has been used in classrooms beginning in 2013. It has been used in several real-world projects, including the Amazon Picking Challenge, TeamHubo in the DARPA Robotics Challenge, and was the platform for the IROS 2016 Robot Grasping and Manipulation Challenge simulation track.

Features

Modeling
  • Supports legged and fixed-based robots.
  • Built in models NASA ATHLETE, Rethink Robotics Baxter, AIST HRP-2, Willow Garage PR2, KAIST Hubo-II+, Robonaut 2, Staubli TX90, Puma 760, Robotiq Adaptive Gripper.
  • Forward and inverse kinematics, forward and inverse dynamics
  • Contact mechanics computations: force closure, support polygons, stability of rigid bodies and actuated robots
  • Keyframe poser and path editor
Simulation
  • Robust rigid body simulation with triangle mesh / triangle mesh collisions.
  • Simulation of PID controlled, torque controlled, and velocity controlled motors.
  • Simulation of various sensors including RGB+D cameras, laser sensors, gyroscopes, force/torque sensors, and accelerometers.
  • ROS bindings available for broadcasting simulation data and reading robot trajectory commands.
Planning
  • Many sampling-based motion planners implemented.
  • Motion planning on constrained manifolds.
  • Fast trajectory optimization routines.
  • Real-time motion planning routines.
  • Planning models are fully decoupled from simulation models, which helps simulate uncertainty.

Current version: 0.7

Languages: C++ and Python

Supported platforms: *nix environments, Windows, Mac OSX, and Windows through Cygwin.

What's new?

Version 0.7 introduces:

  • Improved simulation stability, including adaptive time stepping and instability detection/recovery.
  • The proprietary .tri geometry file format has been replaced with the Object File Format (OFF) for better compatibility with 3D modeling packages.
  • Simulated visual, depth, and laser range sensors are now fully supported.
  • ROS sensor simulation broadcasting is enabled in Klampt/IO/ROS.h.
  • World XML files can now be saved to disk.
  • Robot sensors and controllers can be attached directly to a robot model using the sensors / controller properties in the robot's .rob or .urdf file.
  • The motion planning structure in KrisLibrary has been completely revamped in preparation for support of optimal and kinodynamic planning, but this should be a mostly transparent change to Klamp't users.
  • The Python interface is now better organized. However, the module structure is incompatible with code developed for versions 0.6.2 and earlier. In particular, math modules (vectorops, so3, se3) are now in the klampt.math subpackage, and visualization modules (glprogram, glrobotprogram, etc) are now in the klampt.vis subpackage.
  • Custom Python simulations of sensors, actuators, and force appliers that work on fast simulation rates are easier to integrate with slower control loops in the klampt.sim.simulation module.
  • Revamped and enhanced Python visualization functionality in the klampt.vis module. Multiple windows, simultaneous viewports, trajectory visualization, custom in-visualization plotting, automatic viewport determination, and thumbnail saving are now supported.
  • Cartesian trajectory generation, file loading utilities are added to Python.

Media

Klamp't uses a robust contact generation scheme for mesh-mesh contact

Wheel turning on the PR2. Motion courtesy of Dmitry Berenson at WPI. Compare with the real robot.

Staubli TX90 throwing a block

Hubo-II+ walking on flat ground

Hubo-II+ being tipped over on uneven ground

Hubo-II+ climbing a ladder

Hubo-II+ switching feet, demonstrating force-torque sensing capabilities. Motion courtesy of Andy Park at Purdue University

Comparison of Klampt's contact generation method against the GIMPACT method used in ODE / Bullet

Downloading and Installing Klamp't

Building from source

Please follow the instructions for your system in the Install Klamp't tutorial or the Klamp't manual.

Precompiled binaries

Linux (64 bit) (up to date as of 3/30/2017)

Windows (32 bit) (up to date as of 3/30/2017). You must also install the x86 Visual Studio 2015 Runtime.

To compile your own C++ programs under Windows, you will need to 1) compile Boost, 2) clone Klampt and KrisLibrary from git, then 3) unpack the correct precompiled dependency libraries to the Klampt/Library folder:

To recompile the Klamp't Python bindings, you will need to get the dependencies above and then download and edit the following setup.py file

Documentation

Tutorials

Frequently Asked Questions

  1. How does Klamp't compare to other simulators / programming environments (like ROS, RAVE, Webots, etc)?

    The short answer: Klamp't is an all-in-one toolbox that specializes in robots with contact.

    Unlike ROS, Klamp't is not an architecture for sensing and control on distributed hardware. Klamp't provides tools for modeling, planning, and simulation of robots with contact that are intended primarily for research and rapid prototyping. Klamp't comes with ROS bindings for its simulator and for reading point clouds. Klamp't is more cross-platform and lighter weight.

    OpenRAVE is a similar library developed at CMU concurrently with Klamp't, but with a stronger focus on manipulation problems. OpenRAVE does not support legged robots. Moreover, simulation in OpenRAVE is often conflated with modeling and planning, whereas in Klamp't they are fully decoupled.

    Klamp't differs from other robot simulators (e.g., Gazebo, Webots, V-REP) because it has better collision handling that lets it handle complex contact phenomena between unstructured meshes and even point clouds. Other simulators typically require a robot and its environment to be composed of simple geometric primitives or convex polyhedra, while Klamp't works well with polygon soup or point clouds directly from a CAD program or a depth scanner. Other simulators typically have better visualizations and sensor simulation capabilities. Klamp't ignores the bells and whistles and focuses on stable, robust contact.

  2. I'm a robotics newbie, where should I start?

    Most beginners should start learning the Python API and going through the tutorials. Exercises from an introductory graduate course on robotics are provided in the Python/exercises folder which will help you become more familiar with 3D transformations, configuration spaces, feedback control, and motion planning.

  3. I was using version 0.6.x, how do I migrate my code to 0.7?

    If you are building from source, you will need to cleanly rebuild KrisLibrary and Klampt. Run git pull, then clear the CMakeCache.txt files from both KrisLibrary and Klampt, and download the new dependencies by running make-unpack deps in the Klampt/Library folder. Then rebuild as described in the tutorial.

    To migrate your own code that uses Klampt: If you are using C++, your code will be almost 100% compatible. If you are using Python, the main changes that most users will need to make are 1) to import math, IK, and planning routines from the appropriate submodules, and 2) account for the new visualization framework.

    The vectorops, so3, and se3 modules should no longer be imported from the klampt module, but from klampt.math. The ik module should be imported from klampt.model. And the cspace module should be imported from klampt.plan.

    For visualization, for backwards compatibility's sake you can import the desired GL[X]Program base class from klampt.vis.glprogram and use it essentially unchanged. But the preferred method is no longer to subclass "programs" that run alone, but rather to subclass plugins that get sent to the visualization module. In order to use this new structure, your visualization classes should inherit from the GLPluginInterface class, which is found in klampt.vis.glinterface. Or, you can inherit from GLWidgetPlugin, found in klampt.vis.glcommon.

    There are two major changes in visualization plugins/programs: 1) the specialfunc callback is no longer used to handle non-keyboard input. Instead, keyboardfunc is called with a descriptive string (e.g., "left" for the left arrow key, "f1" for F1). 2) the motionfunc callback now takes four arguments (x,y,dx,dy), in addition to self. Note that in order to take advantage of the new action system you can replace your keyboard dispatch function with a set of calls to self.add_action(func,description,key).

    If you wish to use the new plugin interface, your main function will no longer call program.run(). In lieu of this, you will call vis.setWindowTitle("my program title") and vis.run(program). You may need to add "from klampt import vis" at the top of your file.

  4. How do I import my robot?

    Klamp't uses a proprietary, simple ASCII format for defining robots (.rob files) and can also read from the URDF file format.

    However, for simulation, Klamp't will need some special motor parameters (servoP, servoI, servoD, dryFriction, viscousFriction) that are not present in the URDF format. There are two ways of accomplishing this: 1) use the URDFtoRob program and then edit the generated parameters in the .rob file, or 2) add the special klampt XML tag in the URDF. More details on this procedure can be found in Section 5.13 in the manual or the robot import tutorial.

    Some tips for successful URDFtoRob importing:

    • URDF contains separate visualization / collision geometry per link while Klamp't only uses a single geometry. To switch, toggle the useVisGeom setting in urdftorob.settings, or use_vis_geom attribute in the <klampt> URDF element.
    • If imported meshes looks strange, try setting the flipYZ flag to true in urdftorob.settings, or the flip_yz attribute in the <klampt> URDF element.
    • The mesh import/export paths can be set using urdftorob.settings or the package_root element in the <klampt> URDF element.
    • To avoid converting geometry to the native .tri format, set outputGeometryExtension to the empty string ("") in urdftorob.settings.
    • Dummy URDF links can safely be set to have 0 mass and inertia in the exported robot file. Zero-mass dummy links will not affect the simulation as long as they are fixed to a link with mass. You may also add the <link name="[link name]" physical="0"/> tag under the <klampt> element in the URDF file.
    • For trajectory optimization (including point-to-point motions via the manual posing widget in SimTest), it is important to set reasonable velocity and acceleration limits in the exported robot file.
    • Editing large .rob files is easiest in a spreadsheet program.
  5. How do I choose good motor constants for my robot simulation?

    This can be done by hand by tuning and "exercising" the robot in simulation. An automatic solution is given by the MotorCalibrate program, which will optimize the constants to match a dataset of sensed and commanded joint angles that you record while exercising the physical robot. Please consult its documentation for more details, and you may run ./MotorCalibrate Examples/motorcalibrate_baxter.settings as an example..

  6. How can I make the simulator faster?

    Simulation speed depends on several factors, including the number of rigid bodies, the complexity of the mesh geometry, and the complexity of contacting regions. Small robots with simple meshes may be simulated in super-real-time, while complex robots with very complex meshes might be 100x slower than real-time.

    Usually, the bottleneck is contact generation and reponse, and its cost can be reduced by simplifying the mesh geometry using a 3D modeling program (e.g., Blender), or by reducing the value of the contact clustering parameter, maxContacts.

  7. How can I test my robot's controller using the simulation tools in Klamp't?

    Klamp't can be used for simulation testing of robot behaviors in a variety of ways.

    Testing open-loop paths is straightforward: simply run the SimTest program with the starting robot state and the path as described in the tutorials.

    Testing feedback controllers usually requires writing a bit of "glue code" that translates native robot commands to Klamp't simulator commands, and translates Klamp't sensor data to native robot data. This is possible when robots have relatively straightforward actuators (e.g., PID controlled motors) and sensors of the built-in types. The easiest interface for doing so is the Python API. See Python/control/controller.py for more details, and see Python/control/roscontroller.py as an example that translates to and from ROS messages.

    To use the ROS bindings, see the tutorial.

    If your robot uses more complex actuators and sensors, these must be emulated in the simulation loop. Essentially, the emulator should duplicate the robot's communication protocols, actuator behavior, and sensors in simulation. You are responsible for providing such an emulation layer on top of Klamp't.

  8. How can I use Klamp't planning tools on my robot?

    Klamp't planners and utilities must be incorporated into your robot's software environment via a bit of "glue code".

    For example, a controller may invoke a Klamp't planner when it needs a new path. The planner reads in the robot state and environment and uses Klamp't subroutines to generate a path. A path can be serialized using the simple Linear Path format (an ASCII file containing lines of time / milestone pairs). The controller can read the paths and send them to the robot using your desired communication protocol.

    Direct robot control can be achieved using a mechanism in Interface/UserInterface.h, employed in the UserTrials program. These interfaces read in user input, call a real-time planner, and then send the resulting path to a MotionQueueInterface object. In UserTrials, the interface sends the path to a simulated robot. But by overloading the MotionQueueInterface class with a custom subclass that communicates with your robot, you can control your robot directly. (We have code available for Staubli 6DOF robots, please contact us if you are interested.)

  9. How should I get help using Klamp't?

    Please subscribe to the Klamp't Google group and use the forum and/or mailing list.

  10. How should I acknowledge Klamp't in my publications?

    For the Klamp't simulator, please cite K. Hauser. Robust Contact Generation for Robot Simulation with Unstructured Meshes. International Symposium on Robotics Research, December 2013.

    For the trajectory time-scaling subroutines, please cite K. Hauser. Fast Interpolation and Time-Optimization on Implicit Contact Submanifolds. In proceedings of Robotics: Science and Systems (RSS), Berlin, Germany, June 2013.

    For general usage, please cite the Klamp't manual.