README

Distro	Build dev	Build releases	Stable version
ROS 2 Humble (Ubuntu 22.04)		amd64 · arm64
ROS 2 Jazzy (Ubuntu 24.04)		amd64 · arm64
ROS 2 Kilted (Ubuntu 24.04)		amd64 · arm64
ROS 2 Rolling (Ubuntu 24.04)		amd64 · arm64

gtsam2mrpt_serial

A C++ library providing a bidirectional serialization bridge between GTSAM and mrpt-serialization.

Serialize and deserialize GTSAM data structures — including NonlinearFactorGraph and Values — to and from any mrpt I/O stream (files, sockets, pipes) with optional transparent compression.

Features

• Fast — benchmarks show roughly half the wall-clock time of GTSAM’s native Boost binary serialization for mid-sized graphs (see Performance).

• Portable — the binary format is stable across machine architectures, endianness, word sizes, and operating systems, unlike Boost serialization.

• Versioned — a version tag is embedded in every serialized object so that future library releases can read files produced by older ones.

• Compressed — transparent .gz and .zstd compression is available via mrpt::io::CCompressedOutputStream at no extra cost to the caller.

• Stream-agnostic — works with any stream in mrpt-io: local files, TCP sockets, named pipes, in-memory buffers, and more.

Requirements

• C++17 or newer (required by MRPT).

• MRPT ≥ 2.4: install via sudo apt install libmrpt-dev (Ubuntu 22.04+), via the ROS 2 packages listed in the table above, or follow the MRPT install guide.

• GTSAM: build from source or install from the official PPA.

Supported types

Category	Types
Values	Pose2, Pose3, Point2, Point3, Rot2, Rot3
Factors	PriorFactor<T>, BetweenFactor<T> for all value types above
Noise models	Gaussian, Diagonal, Isotropic, Constrained, Unit, Robust (with all built-in m-estimators)

Usage

Include the single header and use the << / >> stream operators:

#include <gtsam2mrpt_serial/serialize.h>
#include <mrpt/io/CCompressedOutputStream.h>
#include <mrpt/serialization/CArchive.h>

using namespace gtsam2mrpt_serial;

// --- Serialize ---
gtsam::NonlinearFactorGraph graph = /* ... */;
gtsam::Values               initial = /* ... */;

mrpt::io::CCompressedOutputStream f("graph.mrpt.zstd");
auto arch = mrpt::serialization::archiveFrom(f);
arch << graph << initial;

// --- Deserialize ---
mrpt::io::CCompressedInputStream f2("graph.mrpt.zstd");
auto arch2 = mrpt::serialization::archiveFrom(f2);

gtsam::NonlinearFactorGraph graph2;
gtsam::Values               initial2;
arch2 >> graph2 >> initial2;

For a more complete example, see gtsam2mrpt_serial/tests/main.cpp.

Installation

From ROS 2 packages (recommended)

sudo apt install ros-$ROS_DISTRO-gtsam2mrpt-serial

From source

mkdir -p ~/ros2_ws/src && cd ~/ros2_ws/src
git clone https://github.com/MRPT/gtsam2mrpt_serial.git
cd ~/ros2_ws
colcon build --packages-select gtsam2mrpt_serial

Performance

Profiling against GTSAM’s native Boost binary serialization on an Intel Core i7-6700HQ @ 2.60 GHz (Ubuntu 20.04, Boost 1.71, MRPT 2.4.4) shows approximately 2× faster serialization and deserialization for mid-sized factor graphs. The time axis below is logarithmic.

Serialization

Deserialization

Benchmarking code: gtsam2mrpt_serial/tests/main.cpp.

License

Released under the 3-clause BSD license.