Porting code from MRPT 2.x to MRPT 3.0

Porting guide: MRPT 2.x → MRPT 3.0

This guide documents every breaking change in MRPT 3.0 and shows how to migrate code written against MRPT 2.x.

It is organized so that you read it top-to-bottom once, then use it as a reference:

Why MRPT 3.0? — rationale for the refactoring.
Migration checklist — the fast path; start here.
Build system — CMake packages, targets, and removed headers.
Namespaces & renames — mrpt::opengl → mrpt::viz.
Cross-cutting API patterns — mechanical changes that recur across many classes (return-by-value, std::optional, scoped enums, coordinate/option aggregates). Most edits fall under one of these four.
Module-by-module changes — specifics that are not covered by a generic pattern.
Removed APIs — a single lookup table.
Porting ROS 2 nodes — for downstream packages that used mrpt_ros.

Conventions used below. Code blocks are always labeled // MRPT 2.x: (old) and // MRPT 3.0: (new). APIs marked *(deprecated)* still compile with a warning; APIs marked *(removed)* do not exist anymore and must be changed.

Note for Python users. Pybind11 binding conventions live in the repository AGENTS.md, not here. This guide covers the C++ API only.

</blockquote>

Why MRPT 3.0? — Advantages of the refactoring

Modular colcon-based build. Each MRPT module (mrpt_core, mrpt_math, mrpt_poses, mrpt_viz, …) is an independent colcon package with its own CMakeLists.txt. No ROS dependency is required — plain colcon is the meta-build tool — enabling faster incremental builds and independent versioning.
Clean namespace separation. The scene-graph / 3-D visualization API now lives in mrpt::viz, while mrpt::opengl is reserved for low-level GPU rendering internals (shaders, FBOs, textures). This shrinks the public API surface and makes it easier to learn.
Modern C++ API. Output-reference parameters replaced by std::optional returns or return-by-value, raw coordinate pairs replaced by TPixelCoord, integer channel arguments replaced by the TImageChannels enum, and scoped enum class types throughout.
Less legacy code. Octree rendering settings, sparse matrices, old feature matching, CColouredPointsMap, and other rarely-used APIs were removed, reducing maintenance burden and binary size.

Migration checklist

A typical port touches these steps in order. Each links to its detailed section.

CMakeLists.txt — rename mrpt-foo → mrpt_foo in find_package, and mrpt::foo → mrpt::mrpt_foo in target_link_libraries. Optionally adopt mrpt_add_executable(). See Build system.
Headers — replace #include <mrpt/opengl/Foo.h> with #include <mrpt/viz/Foo.h> for scene-graph classes; keep mrpt/opengl/ only for the low-level rendering classes. See Namespaces.
Namespaces — replace mrpt::opengl:: → mrpt::viz:: and opengl:: → viz:: (including using namespace). See Namespaces.
Class names — COpenGLScene → Scene, COpenGLViewport → Viewport, CRenderizable → CVisualObject. See Namespaces.
Drawing calls — convert textOut(x, y, …), line(x0, y0, x1, y1, …), filledRectangle(…) to TPixelCoord / brace-init. See §4 Coordinate & option aggregates.
Output-reference calls — replace foo(out) with out = foo() for the modernized methods. See §1 Return-by-value.
** bool -returning queries** — adopt the std::optional versions. See §2 std::optional.
Enum arguments — replace integer/ bool flags with the new scoped enums and option structs. See §3 Scoped enums.
Removed APIs — delete or replace calls listed in Removed APIs.
Build & iterate — colcon build --packages-up-to mrpt_<module>, then fix remaining errors.

Build system

Package and target renaming

The two mechanical rules cover almost all CMake edits:

MRPT 2.x

MRPT 3.0

Removed header Replacement ============== =========================================

Individual CMake compile definition (below) Module-specific config headers (e.g. from

Class / header Header ================== ======

(low-level GL API) ================== ======

Class renames

MRPT 2.x

MRPT 3.0

API MRPT 3.0 form === =====================

returns the matrix returns the matrix

returns the submatrix returns the object

Old name (still valid) New name ====================== ========

Removed API Notes / replacement =========== ==================================

Removed (a few classes moved to Use Eigen sparse matrices Use Removed Octree rendering removed Octree rendering removed Octree API removed Octree API removed Octree API removed Octree API removed Use individual Use a CMake compile definition Use module-specific config headers

Example package.xml diff:

 <package format="3">
   <name>my_ros_node</name>
-  <depend>mrpt_libmath</depend>
-  <depend>mrpt_libposes</depend>
-  <depend>mrpt_libmaps</depend>
-  <depend>mrpt_libtclap</depend>
+  <depend>mrpt_math</depend>
+  <depend>mrpt_poses</depend>
+  <depend>mrpt_maps</depend>
+  <depend>cli11</depend>
 </package>

<tt>CMakeLists.txt</tt> — <tt>find_package</tt> and targets

Same two mechanical rules as the Build system section (find_package(mrpt-<X>) → find_package(mrpt_<X>); mrpt::<X> → mrpt::mrpt_<X>):

-find_package(mrpt-math   REQUIRED)
-find_package(mrpt-poses  REQUIRED)
-find_package(mrpt-maps   REQUIRED)
-find_package(mrpt-tclap  REQUIRED)
+find_package(mrpt_math   REQUIRED)
+find_package(mrpt_poses  REQUIRED)
+find_package(mrpt_maps   REQUIRED)
+find_package(CLI11       REQUIRED)

 add_executable(my_node src/main.cpp)
 target_link_libraries(my_node PRIVATE
-  mrpt::math
-  mrpt::poses
-  mrpt::maps
-  mrpt::tclap
+  mrpt::mrpt_math
+  mrpt::mrpt_poses
+  mrpt::mrpt_maps
+  CLI11::CLI11
 )

Dropped: <tt>mrpt-tclap</tt> / <tt>mrpt_libtclap</tt>

MRPT 3.x no longer vendors TCLAP. Code using #include <mrpt/3rdparty/tclap/CmdLine.h> must migrate to an external CLI library. The recommended replacement is CLI11 (single-header, packaged as libcli11-dev on Ubuntu, rosdep key cli11):

// MRPT 2.x (TCLAP via the removed mrpt_libtclap):
#include <mrpt/3rdparty/tclap/CmdLine.h>
TCLAP::CmdLine cmd("my tool", ' ', "1.0");
TCLAP::ValueArg<std::string> arg_in("i", "input", "input file", true, "", "file", cmd);
cmd.parse(argc, argv);
const std::string in = arg_in.getValue();

// MRPT 3.0 (CLI11):
#include <CLI/CLI.hpp>
CLI::App app{"my tool"};
std::string in;
app.add_option("-i,--input", in, "input file")->required();
CLI11_PARSE(app, argc, argv);