Features
- 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
- 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.
- 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.8.1
Languages: C++ and Python
Supported platforms: *nix environments, Windows, and Mac OSX.
Version 0.8.1 introduces:
- Integration with Jupyter Notebook.
- Improved build system for Python, allowing easy installation via pip install python.
- Cleaner file structure, with C++ files in the Cpp directory.
- Cleaned up documentation, separating C++ and Python docs. Sphinx is now used for Python docs.
- Added Python utility programs (klampt_browse, klampt_sim, klampt_path, klampt_thumbnail).
- Improvements support Python visualization on Mac.
- Upgraded to PyQt5. PyQt4 is still supported for now.
- Geometry conversions exposed in Python via the convert function.
- Improved usage of some graphics card resources for streaming point clouds.
- Support for LOG4CXX logging.
- Removed dependencies on Boost and upgraded to C++11.
- Removed dependencies on GLUT and GLUI. (Some examples still need to be upgraded to Qt.)
- Cleaned up some cruft in KrisLibrary.
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
Quick start (Python API only)
- pip install klampt
- (optional) git clone https://github.com/krishauser/Klampt-examples
Complete-package installation tutorials are available for:
Precompiled binaries
Windows (32 bit) (up to date as of 1/6/2018). You must also install the x86 Visual Studio 2015 Runtime.
To compile your own C++ programs under Windows, you will need to 1) clone Klampt and KrisLibrary from git, then 3) unpack the correct precompiled dependency libraries to the Klampt/Library folder:
- Win32 dependency libraries, Visual Studio 2015, Debug build
- Win32 dependency libraries, Visual Studio 2015, Release build
- x64 dependency libraries, Visual Studio 2015, Debug build
- x64 dependency libraries, Visual Studio 2015, Release build
Documentation
Frequently Asked Questions
-
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.
-
I'm a robotics newbie, where should I start?
Most beginners should start learning the Python API and going through the examples in the manual. Exercises from an introductory graduate course on robotics are provided in the Klampt-examples/Python/exercises folder. An open-source textbook, Robotic Systems is being prepared, which will help you become more familiar with 3D transformations, configuration spaces, feedback control, and motion planning.
-
I was using version 0.6.x, how do I migrate my code to 0.8.x?
If you are using C++, the main changes that you will need to make is that everything is upgraded to use C++11, and you should prepend "Klampt/" to all of your Klampt includes. Item 1 means that the KrisLibrary SmartPointer class is being deprecated in favor of shared_ptr, and all Klampt classes have switched to using shared_ptr.
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.
-
I was using version 0.7, how do I migrate my code to 0.8.x?
If you are using C++, the main changes that you will need to make is that everything is upgraded to use C++11, and you should prepend "Klampt/" to all of your Klampt includes. Item 1 means that the KrisLibrary SmartPointer class is being deprecated in favor of shared_ptr, and all Klampt classes have switched to using shared_ptr.
If you are using Python, you will probably not need to change anything, as the API is 99% compatible between versions.
-
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 the Klampt manual and 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.
-
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..
-
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.
-
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 custom control documentation.
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.
-
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.)
-
I noticed a bug! How should I report it?
Please report the issue on the Klampt Github Issues page, and we'll get right on it.
-
How should I get help using Klamp't?
Please use the Klamp't forum at https://gitq.com/krishauser/Klampt.
-
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.