Programming notes and tips

Common “gotchas”

  • A robot model’s configuration is used in many places as input and output! To guard against losing configuration, think of the robot’s configuration as a temporary variable. If you need to keep the configuration between computations, just store it before the computations, and restore it afterwards. The standard pattern (in Python) is:

    q = robot.getConfig()
    #... do stuff ...
  • The current configuration of a robot model does not have an effect on a real or simulated robot. To drive the actual robot, you must use the interface in its Robot Controller. To work with the current configuration of a real or simulated robot, the configuration must be read from the Robot Controller.

  • A robot model does not necessarily correspond to a real robot. Its kinematics, geometry, and limits need to be calibrated from the specifications of the real robot.

  • When performing multithreading, such as in the Python vis module, crashes can occur if locking is not performed properly to prevent simultaneous access to World Models.

  • Data can inadvertently “leak” from simulation to planning if a shared World Model is used, since the simulation will update the model for visualization. An easy way to get around such conflicts is simply to copy the world into separate planning and simulation worlds. (This is fast, since none of the geometry is actually copied.) The standard pattern (in Python) is:

    world = WorldModel()
    #... set up the model ...
    simWorld = world.copy()
    sim = Simulator(simWorld)
    planWorld = world   #no need to copy again
    planner = MyPlanner(planWorld)


  • Ask questions and report issues/bugs. This will help us make improvements to Klamp’t. If you write a piece of code that you think will be useful to others, consider making it a contribution to the library.
  • Practice self-documenting code. Name files, functions, classes, and variables descriptively. Comment as you go.
  • Use visual debugging to debug your algorithms. For many objects, you may call to pop up a window for editing.
  • Think statefully. Decompose your programs into algorithms, state, parameters, and data. State is what the algorithm changes during its running. Parameters are values that are given as input to the algorithm when it begins (arguments and settings), and they do not change during execution. Data is the static knowledge available to the algorithms and the information logged as a side effect of its execution.
  • When prototyping long action sequences, build in functionality to save and restore the state of your system at intermediate points.

Missing Python Features

The Python API is much cleaner and easier to work with than the C++ API. However, it does not contain all of the functionality of the C++ API. Missing features include:

  • Advanced IK constraint types
  • Trajectory optimization
  • Some contact processing algorithms
  • Robot reachability bound determination
  • Advanced force/torque balance solvers
  • Advanced motion planners (optimal planning with custom objective functions, kinodynamic planning, etc)
  • Direct access to a robot’s trajectory queue.

Useful Submodules

The Klamp’t Python API contains several submodules that are not discussed in detail in the manual. You may wish to look these over.

  • cartesian_trajectory: reliable methods for converting Cartesian space trajectories to joint space trajectories.
  • config: treats the configuration of multiple objects as a single flat configuration vector.
  • coordinates: a coordinate manager, similar to the ROS tf module.
  • create: helpers to create robots, geometric primitives, and piles of objects.
  • access: provides a more Pythonic way to access items in a world.
  • subrobot: defines SubRobotModel, a class that is RobotModel-like but only modifies selected degrees of freedom (e.g., an arm, a leg).
  • types: retrieves the type string for various Klamp’t objects.
  • cspaceutils: contains helpers for constructing composite CSpaces and slices of CSpaces.
  • settle: a convenience function to let objects fall under gravity and extract their equilibrium configurations.
  • simlog: simulation logging classes (used in SimpleSimulator)
  • simulation: a more full-featured simulation class than standard Simulation. Defines sensor and actuator emulators, sub-step force appliers, etc.