trajopt: sequential convex optimization for ROS motion planning

A planner that formulates the whole trajectory as one optimisation

trajopt is described as an optimizing path planner for ROS, and the useful way to read that is as a contrast with sampling planners. A sampling planner proposes configurations and checks them; trajopt instead writes the whole path as a mathematical program and hands it to a numerical solver. The problem it addresses in ROS is the one where a robot has to reach a goal while respecting joint velocity limits, avoiding collisions and optimising several objectives at once. The audience is industrial robotics developers working inside the Tesseract ecosystem, and the consortium support level badge reflects that origin. The upstream project is under the tesseract-robotics organisation, the code is C++, and the package names follow the ROS convention of a trailing separator, so the planner appears under the name trajopt.

Sequential convex optimization with a penalty method on top

The mechanism has three layers and it is worth taking them one at a time. The first is sequential convex optimization, which is how trajopt solves the motion planning problem: rather than tackling a non-convex problem in one shot, it linearises around the current trajectory and re-solves, repeatedly, until the solution settles. The second is a penalty method used to optimise for joint velocities while satisfying a set of constraints, which is how the hard feasibility requirements are folded into the objective rather than treated separately. The third is the inner layer, which uses convex solvers able to solve linearly constrained quadratic problems. The result is that a hard problem is decomposed into a sequence of tractable ones. The cost of this design is that the outer loop adds iterations, and the quality of the answer depends on the inner solver behaving well at each step.

Five convex solvers with very different licences

The solver choice is the most consequential decision you make, and the project is unusually clear about the licensing. BPMPD is an interior point method bundled in the distribution but free for non-commercial use only. OSQP, which uses ADMM, and PIQP, a proximal interior point method, are both BSD2 licensed and one of them is the default. qpOASES is an active set method under LGPL 2.1. Gurobi supports simplex and interior point or parallel barrier, and needs a licence and a system installation. Bundling and fetching differ too: BPMPD ships with the package, OSQP, qpOASES and PIQP are pulled automatically from their source distribution when needed, and Gurobi has to be installed separately with a GUROBI_HOME variable defined at build time. For a commercial deployment that last distinction is not a detail, since a non-commercial-only solver in a shipped product is a legal question you have to answer before release.

convex_solver and AUTO_SOLVER decide which backend runs

A problem selects its solver through the convex_solver setting, and the default is AUTO_SOLVER. The automatic mode uses the solver named by the TRAJOPT_CONVEX_SOLVER environment variable if that variable is set, and otherwise falls back to the first available of GUROBI, OSQP, QPOASES, BPMPD and PIQP, in that order. The accepted values for both the setting and the environment variable are GUROBI, OSQP, QPOASES, BPMPD, PIQP and AUTO_SOLVER. The practical implication is that two machines with the same configuration file can solve the same problem with different solvers, since availability decides the outcome in automatic mode. Pinning convex_solver explicitly, or setting the environment variable on your build and runtime machines, is what makes a result reproducible.

The examples moved to tesseract_ros2, so start there

The most useful pointer in the documentation is that the example package is no longer part of this repository and is maintained in ros-industrial-consortium/tesseract_ros2, under the name tesseract_ros_examples. There is also an industrial training module that covers trajopt through a pick and place application, and it is linked from the documentation. The pick and place example is recommended as the starting point because it shows a complete end-to-end process, and the documentation explains why the code is long: it sets up and solves two problems, the pick and the place, and it attaches and detaches objects in Tesseract. It uses the Tesseract trajopt planner, which simplifies some of the problem setup. If you are starting from zero, read the pick and place launch file first rather than the low-level API.

The launch file itself is invoked with the roslaunch command on the tesseract_ros_examples package, for example `roslaunch tesseract_ros_examples pick_and_place_example.launch`.

Each example isolates one planner capability

The remaining examples are more useful as demonstrations of specific capabilities than as a progression. The basic Cartesian example shows how to use trajopt directly rather than through the higher level planner, and it performs collision checking against an octomap generated from a point cloud, which is the part most people need to get working first. The glass upright example keeps the end effector orientation upright while avoiding a collision, which demonstrates how competing costs and constraints combine. The car seat demo needs an external package, the Motoman driver cloned into the workspace, and shows planning with external axes and redundancy. The puzzle piece examples show a collaborative robot deburring a puzzle piece, one case with a fixed grinder and one with extra axes.

Build flags decide what you compile in

The build is controlled by CMake options that switch on whole subsystems, and this is worth understanding before your first compile. Clang-Tidy analysis is off unless you pass the TRAJOPT_ENABLE_CLANG_TIDY option, and the documentation notes the same option is enabled automatically when that CMake argument is passed, so the two are the same switch. Tests are gated behind TRAJOPT_ENABLE_TESTING. The documentation is not consistent about the spelling of that second flag, describing it once as TRAJOPT_ENABLE_TESTING and once as TRAJOPT_ENABLE_TESTING_ALL, and a catkin tools user is told to pass the first one with a forced CMake reconfigure. Benchmarks have their own pair of options, one to build the Google benchmark suite and another to run the benchmarks at compile time and write the results to a json file in the build directory. The documentation is also where the sphinx sources for the branch documentation live.

The branch documentation is a separate build, run from the gh_pages directory:

cd gh_pages
sphinx-build . output

The output is written to gh_pages/output, and the documentation notes that the index page is opened from there.

Repository layout, maintenance and the licensing question

The tree shows the shape of the project. The trajopt directory holds the planner itself, trajopt_common holds shared utilities, trajopt_ext holds extensions, trajopt_ifopt holds the interface to the ifopt optimisation framework, trajopt_optimizers holds the convex backends, and trajopt_sco holds the sequential convex optimization code. There is a ci directory, a docker directory, a gh_pages directory for the branch documentation, and formatting configuration with clang-format, clang-tidy and cmake-format plus editor run configurations. The repository is not archived, and the last push was on 2026-10-13. The tagged releases are 0.33.0 from 2025-10-28, 0.34.4 from 2026-02-18 and 0.35.0 from 2026-05-28, so the version has not moved since May 2026 even though commits continue. On licensing, the project carries badges for Apache 2.0 and BSD 2-Clause in its documentation, while the licence field on the repository is listed as unknown, so read the LICENSE file in the tree rather than relying on a badge.

Editorial conclusion

Adopt trajopt if you build manipulation stacks on ROS and need a planner that handles joint velocity limits, collisions and multiple competing costs in one formulation, and if you are already using the Tesseract ecosystem around it. Do not adopt it for a pick-and-place task you could solve with a simpler sampling planner, and do not plan around its examples living here, because they have moved to the tesseract_ros2 repository. Before you start, decide which convex solver you will use, since the licensing differs sharply between the bundled BPMPD, the free BSD2 options and the commercial Gurobi, and confirm that a GUROBI_HOME variable is set if you pick Gurobi.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. tesseract-robotics/trajopt on GitHub