A light-weight and extensible C++ library for trajectory optimization for legged robots.

A base-set of variables, costs and constraints that can be combined and extended to formulate trajectory optimization problems for legged systems. These implementations have been used to generate a variety of motions such as monoped hopping, biped walking, or a complete quadruped trotting cycle, while optimizing over the gait and step durations in less than 100ms (paper).

Features:
:heavy_check_mark: Intuitive and efficient formulation of variables, cost and constraints using Eigen.
:heavy_check_mark: ifopt enables using the high-performance solvers Ipopt and Snopt.
:heavy_check_mark: Elegant rviz visualization of motion plans using xpp.
:heavy_check_mark: ROS/catkin integration (optional).
:heavy_check_mark: Light-weight (~6k lines of code) makes it easy to use and extend.

Install • Run • Develop • Contribute • Publications • Authors

Install

The easiest way to install is through the ROS binaries:

sudo apt-get install ros-<ros-distro>-towr-ros

In case these don’t yet exist for your distro, there are two ways to build this code from source:

• Option 1: core library and hopper-example with pure CMake.
• Option 2 (recommended): core library & GUI & ROS-rviz-visualization built with catkin and ROS.

Building with CMake

• Install dependencies CMake, Eigen, Ipopt:

  sudo apt-get install cmake libeigen3-dev coinor-libipopt-dev
  

Install ifopt, by cloning the repo and then: cmake .. && make install on your system.

• Build towr:

  git clone https://github.com/ethz-adrl/towr.git && cd towr/towr
  mkdir build && cd build
  cmake .. -DCMAKE_BUILD_TYPE=Release
  make
  sudo make install # copies files in this folder to /usr/local/*
  # sudo xargs rm < install_manifest.txt # in case you want to uninstall the above
  

• Test (hopper_example.cc): Generates a motion for a one-legged hopper using Ipopt

  ./towr-example # or ./towr-test if gtest was found
  

• Use: You can easily customize and add your own constraints and variables to the optimization problem. Herefore, add the following to your CMakeLists.txt:

  find_package(towr 1.2 REQUIRED)
  add_executable(main main.cpp) # Your custom variables, costs and constraints added to TOWR
  target_link_libraries(main PUBLIC towr::towr) # adds include directories and libraries
  

Building with catkin

We provide a ROS-wrapper for the pure cmake towr library, which adds a keyboard interface to modify goal state and motion types as well as visualizes the produces motions plans in rviz using xpp.

• Install dependencies CMake, catkin, Eigen, Ipopt, ROS, xpp, ncurses, xterm:

  sudo apt-get install cmake libeigen3-dev coinor-libipopt-dev libncurses5-dev xterm
  sudo apt-get install ros-<ros-distro>-desktop-full ros-<ros-distro>-xpp
  

• Build workspace:

  cd catkin_workspace/src
  git clone https://github.com/ethz-adrl/ifopt.git
  git clone https://github.com/ethz-adrl/towr.git
  cd ..
  catkin_make_isolated -DCMAKE_BUILD_TYPE=Release # or `catkin build`
  source ./devel_isolated/setup.bash
  

• Use: Include in your catkin project by adding to your CMakeLists.txt

  add_compile_options(-std=c++11)
  find_package(catkin COMPONENTS towr) 
  include_directories(${catkin_INCLUDE_DIRS})
  target_link_libraries(foo ${catkin_LIBRARIES})
  

Add the following to your package.xml:

  <package>
    <depend>towr</depend>
  </package>
  

Run

Launch the program using

  roslaunch towr_ros towr_ros.launch  # debug:=true  (to debug with gdb)
  

Click in the xterm terminal and hit ‘o’.

Information about how to tune the paramters can be found here.

Develop

Library overview

• The relevant classes and parameters to build on are collected modules.
• A nice graphical overview as UML can be seen here.
• The doxygen documentation provides helpful information for developers.

Problem formulation

• This code formulates the variables, costs and constraints using ifopt, so it makes sense to briefly familiarize with the syntax using this example.
• A minimal towr example without ROS, formulating a problem for a one-legged hopper, can be seen here and is great starting point.
• We recommend using the ROS infrastructure provided to dynamically visualize, plot and change the problem formulation. To define your own problem using this infrastructure, use this example as a guide.

Add your own variables, costs and constraints

• This library provides a set of variables, costs and constraints to formulate the trajectory optimization problem. An example formulation of how to combine these is given, however, this formulation can probably be improved. To add your own e.g. constraint-set, define a class with it’s values and derivatives, and then add it to the formulation nlp.AddConstraintSet(your_custom_constraints); as shown here.

Add your own robot

• Want to add your own robot to towr? Start here.
• To visualize that robot in rviz, see xpp.

Contribute

We love pull request, whether its new constraint formulations, additional robot models, bug fixes, unit tests or updating the documentation. Please have a look at CONTRIBUTING.md for more information.
See here the list of contributors who participated in this project.

Projects using towr

• https://github.com/popi-mkx3/popi_project

Publications

All publications underlying this code can be found here. The core paper is:

@article{winkler18,
  author    = {Winkler, Alexander W and Bellicoso, Dario C and 
               Hutter, Marco and Buchli, Jonas},
  title     = {Gait and Trajectory Optimization for Legged Systems 
               through Phase-based End-Effector Parameterization},
  journal   = {IEEE Robotics and Automation Letters (RA-L)},
  year      = {2018},
  month     = {July},
  pages     = {1560-1567},
  volume    = {3},
  doi       = {10.1109/LRA.2018.2798285},
}

A broader overview of the topic of Trajectory optimization and derivation of the Single-Rigid-Body Dynamics model used in this work: DOI 10.3929/ethz-b-000272432

Authors

Alexander W. Winkler - Initial Work/Maintainer

The work was carried out at the following institutions:

Contributing to towr

Thanks for taking the time to contribute! :tada::+1:

We are grateful to anyone who decides to actively engage in this project. This project and everyone participating in it is governed by the Code of Conduct. By participating, you are expected to uphold this code.

Question or Issue?

• ROS Answers: If you want to ask a general usage question, please do this at ROS Answers using the tag towr. Asking there has the following advantages:

  • There are many more people reading questions there so your chances on getting an answer and in a timely manner are much higher.
  • In the future other users will search there for similar problems and can find your question and the potential answers.

• Issue tracker: In case you want to report bugs, request features or anything closely related to the code.

How Can I Contribute?

Unsure where to begin? You can start by looking through these issues:

• Good first issues - issues which should only require a few lines of code, and a test or two.
• Authors recommendations - advanced issues that can possibly bring great improvement.

Further ideas might include:

• add cool terrains/height-maps
• add different robot models
• enhance the user interface
• add additional constraints
• improve performance
• improve documentation

Please follow the Google Style Guide when writing your C++ Code for this project.

Submitting a pull request

Please create a pull request from your forked repo to the master branch.

• Keep pull requests small, focussing on one specific issue.
• Describe concisely what you are solving and reference the corresponding issue.
• Include weblinks to relevant information.
• Include screenshots and animated GIFs in your pull request whenever possible.

We are performing automatic pull request testing, so if these fail, please read through the log and update your pull request.