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

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.

Changelog for package gtsam2mrpt_serial

0.2.0 (2026-02-21)

• Modernize and fix style
• fix build in new gtsam
• Add devcontainer for Rolling
• Add build farm badges
• Update README.md
• clarify license
• build depend: fix missing ones
• reorganize files for proper finding headers downstream
• Update as a colcon package
• fix newer gtsam version API
• Add .so version numbers
• tighter tests
• more correct cmake export
• Update README.md
• doc images
• more tests and profiling
• refactor unit tests
• First working version (requires mod gtsam)
• Progress with noise models
• Update README.md
• Delete azure-pipelines.yml
• Update README.md
• Serialization of basic values
• Update cmake.yml
• Create cmake.yml
• depends
• initial commit with basic structure
• Initial commit
• Contributors: Jose Luis Blanco-Claraco