Features

• Supports legged and fixed-based robots.
• Supports URDF robot file format.
• Wide range of geometry support with triangle meshes, point clouds, implicit surfaces, occupancy grids, heightmaps, and geometric primitives
• Forward and inverse kinematics, forward and inverse dynamics
• Contact mechanics computations: force closure, support polygons, stability of rigid bodies and actuated robots
• Integration with Numpy, JSON, ROS 1, Open3D, trimesh, PyTorch, Casadi, and Sympy

• Easy visualization with OpenGL, Jupyter notebooks, and Rerun.io
• Unified interface to simulated and physical robots.
• Smooth motion generation and Cartesian control plugins to add to your own robot's controllers.
• Extrinsic calibration tools.
• Workspace calculation tools.
• Comprehensive file I/O for visual browsing, editing, and programming with reusable assets (joint poses, trajectories, etc).

• Robust rigid body simulation with triangle mesh / triangle mesh collisions, mesh / point cloud collisions, and more.
• 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 are 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 evaluate behavior under errors and uncertainty.

Current version: 0.10.0

Languages: C++ and Python

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

Version 0.10.0 is a major update, with some API-breaking changes:

• New geometry types OccupancyGrid and Heightmap. The VolumeGrid data structure is deprecated but aliases to ImplicitSurface. Heightmap can represent orthographic heightmaps (e.g., elevation maps) as well as depth maps coming from RGB-D cameras. Many more proximity queries are implemented / accelerated.
• Viewport data structure now accepts non-square pixels and non-centered focal points, making it compatible with calibrated camera intrinsics. API breaking change; to resize viewports and keep the FOV and relative center, use Viewport.resize(w,h).
• C++ API: Breaking changes to KrisLibrary Geometry API, now reflected in KrisLibrary 0.2 and later. Older builds of Klampt will need to pull KrisLibrary branch 0.1.
• C++ API: Renamed Merge to Union for all geometries. Added Merge function that merges a single geometry into the current geometry's representation.
• Python API: many more setters / getters to make access more Pythonic, i.e., treating WorldModel.robots / RobotModel.sensors as Python tuples.
• Python API: Upgraded to support PyQt6, deprecated PyQt4. Changed to using QOpenGLWidget for visualization, which may introduce visualization bugs as we work through the kinks. Klampt windows can now be run in concert with OpenCV visualizations, although only in single-threaded (vis.loop / vis.run) mode (see opencvtest.py). Also, when simulating sensors and showing them in matplotlib, vis.scene().window.makeCurrent() / doneCurrent() needs to be called (see sensor_matplotlib.py). For example, grabbing depth maps from the viewport is no longer supported. However, you can still get depth maps from SimRobotSensors.
• Python API: Geometry3D data objects now use Numpy accessors. Also, they now support zero copying for setting and getting data, making large geometry updates much faster! You may also use PointCloud.getColors/setColors, TriangleMesh.triangleNormals/vertexNormals.
• Python API: Renamed SimRobotSensor to SensorModel. SensorModel.name()/type() are changed to attributes SensorModel.name/type.
• Python API: klampt.model.sensing API change. No longer need robot argument to functions. Rely on SensorModel to get sensor transforms.
• Python API: Added Geometry3D merge function that can be used for SDF and heightmap fusion.
• Python API: Added Rerun.io visualization frontend. Try vis.init('Rerun'). Unsupported functions: multi-window, coordinates module items, ContactPoints, Holds.
• Python API: can control draw order of transparent objects with draw_order attribute.
• Python API: Text and plots are drawn at a more sensible size (points rather than pixels) for high-resolution screens.
• Klampt-examples: moved "boring" C++ tests to the Klampt-examples/Cpp/testing folder. Moved "boring" Python tests to the Klampt-examples/Python3/testing/pytest folder and made compatible with pytest. Broke test files that had multiple selectable tests into individual tests.
• Various bug fixes.

Media

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:

• Linux
• Windows
• Mac OSX
• Jupyter notebook
• Docker

Precompiled binaries

Windows (32 bit) (up to date as of 12/1/2023). You must also install the x86 Visual Studio 2015 Runtime.

• Win32 Klamp't applications, static library (VS 2015 build) and C++ headers.

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

• Klamp't Python Manual and API Documentation
• Klamp't C++ Manual
• Klamp't C++ API
• KrisLibrary C++ API

Frequently Asked Questions

1. How does Klamp't compare to other robotics software packages (like ROS, Drake, MuJoCo, RAVE, Webots, etc)?

   The short answer: Klamp't is an all-in-one toolbox that handles all of the essentials with a convenient Pythonic interface.

   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.

   Compared to Drake, Klampt is Python-first and makes it especially easy to work with sensor data and geometry, visualizations, and create your own robot controllers. It lacks the powerful optimization functions of Drake and its simulation engine hasn't been maintained for a while.

   MuJoCo focuses on fast and approximate simulation, whereas Klampt offers many more modeling, planning, control, and visualization tools useful for working with real robots.

   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. Klamp't visualization doesn't support shadows.

2. 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, will help you become more familiar with 3D transformations, configuration spaces, feedback control, and motion planning.

3. I was using 0.9.x, how do I migrate my code to 0.10?

   C++:.

   • Almost no changes, unless you are using the internals of the AnyGeometry3D / AnyCollisionGeometry3D classes.

   Python:

   • If you were manipulating the data classes in Geometry3D, you will now need to use their Numpy properties and accessor methods.
   • If you were using depth screenshots, they have been removed due to deprecations in PyQt5 which were finally removed in PyQt6. You will need to set up a SensorModel camera (type "CameraSensor") instead.
   • SimRobotSensor and VolumeGrid names will be deprecated in a future version. Start using SensorModel and ImplicitSurface or OccupancyGrid to indicate the voxel meanings.
   • Klampt 0.9 deprecated functions have been removed.
4. How do I import my robot?

   Klamp't reads from the URDF file format. It also uses a proprietary, simple ASCII format for defining robots (.rob files) which is much less verbose.

   For physics simulation, Klamp't will need some special motor parameters (servoP, servoI, servoD, dryFriction, viscousFriction) that are not present in the URDF format. We recommend that you 1) add the special klampt XML tag in the URDF, or 2 run the URDFtoRob program and then edit the generated parameters in the .rob file. More details on this procedure can be found in the Klampt manual and the robot import tutorial.

   Some tips for successful URDF tagging and/or 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 controller motion generation and trajectory optimization, it is very important to set reasonable velocity and acceleration limits in the exported robot file.
   • SimTest allows you to tune joint PID constants and friction parameters during simulation by selecting "Window > Drivers" from the menu.
   • 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. The SimTest program has a window for tuning constants (Window > Drivers) while the simulation is running; a general strategy is to turn up damping or friction until the robot doesn't oscillate, and then turn up stiffness to track the setpoint about as well as your physical system does. 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 behavior code using a Klamp't simulation?

   Klamp't can be used for simulation testing of robot behaviors in a variety of ways. There are two main steps: 1) tuning the simulation engine to match the real world as closely as possible, and 2) matching the interface between the behavior and simulated robot to the interface between the behavior and the real robot.

   Simulation tuning requires customizing the default rigid body simulator by setting up object models and surface parameters, and then adding forces, joints, etc. between objects in the world during the simulation loop. You may also add robot sensors to the simulation to imitate cameras, force sensors, etc. Klampt has a number of built-in sensor types, including RGB cameras, RGB-D cameras, laser rangefinders, force/torque sensors, IMUs, etc. If your robot uses more complex actuators and sensors, you must implement emulators for these items in the simulation loop. Essentially, an emulator tries to duplicate the robot's motor controller software, actuator behavior, and sensors given complete access to the simulation state.

   To match the interface between the behavior and the real robot, we provide the Robot Interface Layer in the Python API which is a unified interface to real and simulated robots. You should write (or find) an RIL subclass for both the real and simulated robots such that they behave similarly when addressed using the klampt_control utility. Simulation RILs for position-controlled and velocity-controlled robots are built-in to Klampt. See the control documentation for more details

   To connect ROS behaviors to a Klamp't simulator, see klampt/control/blocks/io/roscontroller.py. To connect Python behavior using Klampt's RIL to a ROS robot, use klampt/control/blocks/io/rosinterface.py.

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 behavior 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. Then it calls klampt.model.trajectory.execute_path given the Klamp't RIL controller for your robot. (Python API) Paths are sent to your robot as piecewise linear or piecewise cubic curves if you have implemented the Robot Interface Layer of the Python API. See the control documentation for more details

   Direct robot control in C++ 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. 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.

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

    Please use the Klamp't forum at https://gitq.com/krishauser/Klampt.

11. 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.