slamplay: A CMake Wrapper Around the C++ SLAM Stack

The dependency wiring problem slamplay addresses

Anyone who has tried to build a SLAM prototype from scratch knows the first week is not spent on SLAM. It is spent getting g2o, gtsam, ceres, Eigen, Sophus, OpenCV and PCL to coexist, then discovering that the loop-closure code wants DBoW2 and the visualization wants Pangolin. slamplay's stated purpose is to collapse that work: it "installs and wires up, in a single CMake framework" the back-end frameworks, front-end tools, algebra and geometry libraries, visualization tools, loop-closure frameworks and deep learning runtimes the author considers central to the field.

The audience is visible in the README. Luigi Freda writes that he created the project for a computer vision class he taught and developed it in his free time, taking inspiration from repositories available on the web. That is the honest framing, and it should set expectations. This is a curated teaching tree with runnable examples, not a library with an API contract. If you are a student, a lecturer assembling lab material, or an engineer who wants a working reference implementation of, say, a laser-inertial odometry variant before writing your own, the repository is aimed at you. If you need a dependency with semantic versioning and a support window, it is not.

What the repository layout actually contains

The README's layout table is the most useful part of the documentation, because it tells you where the code lives rather than what it claims to do. Back-end examples sit in backend/ and cover g2o, gtsam, ceres and se-sync. Front-end vision and sensor examples sit in frontend/. Loop-closure place-recognition examples sit in loop_closure/. Semantic segmentation sits in semantics/. Dense and surfel mapping examples sit in dense_mapping/. Eigen and geometry tutorials sit in algebra_geometry/. Shared libraries, including the deep learning models and the lidar-IMU stack under ad/, sit in core/.

The split between core/ and full_slam/ matters. Building blocks for visual SLAM live under core/ in directories named features, features_dl and depth_dl, with camera model, stereo vision, motion estimation, triangulation and direct-method examples in frontend/. The stereo SLAM pipeline itself, with frontend, backend, visual odometry and map components, is in full_slam/vslam/. On the lidar side, core/ad/ holds laser_2d, laser_3d, imu, pointcloud and nav, with LIO variants named lio_iekf, lio_preinteg, NDT and LOAM-like under core/ad/laser_3d/. The mapping pipeline with frontend, loop closure, pose-graph optimization and localization fusion is in full_slam/lio_slam/. In other words, the repository is organized so that you can read one algorithm in isolation or run a whole pipeline, and the directory names are the index.

Building it: scripts, config.sh and the ROS question

The README gives a three-command path. Run ./install_dependencies.sh, then ./install_local_opencv.sh, then ./build.sh. It states the project is tested on Ubuntu 20.04, 22.04 and 24.04, and warns that the build takes a while. When it finishes you enter build/ and run examples.

config.sh defines the working environment and is sourced automatically by the install and build scripts. The one documented knob is OpenCV_DIR: setting it skips the local OpenCV install. The README explicitly does not recommend this, warning that mixed dependency versions can cause undefined behaviour and that features may be lost. That is a real constraint, not boilerplate. If you already have OpenCV on your system and are tempted to save build time, the project's own guidance is that you are trading correctness for convenience.

Data is separate from code. ./install_data.sh downloads images and videos into data/, and ./install_dl_models.sh fetches model weights. The TensorFlow C++ path, needed for HFNet according to the README, requires ./install_tensorflow_cc.sh, which the README says is long and must be run manually rather than as part of the main build.

The ROS situation is the design decision most likely to surprise people. No system ROS install is required. Examples that read .bag files use a minimal ROS1-compatible C++ subset vendored under thirdparty/ros/, described as librosbag.a plus message headers, with no catkin workspace and no distro ROS package dependency. Optional ROS-compat helpers live under ros/. The README points to thirdparty/ros/README.md for scope and limitations, which is where you should look if your bags use message types outside that subset. Container users are directed to a separate repository, luigifreda/rosdocker, for images with or without CUDA.

Running the two end-to-end pipelines

The vSLAM entry point is documented concretely. Edit config/vslam/kitti.yaml or config/vslam/euroc.yaml, then change into build/full_slam/apps/vslam and run ./run_vslam_kitti_stereo or ./run_vslam_euroc_stereo. Config files live in the top-level config/ folder and are compiled into the applications as CONFIG_DIR, so the YAML you edit is the YAML the binary reads, with no runtime search path to debug. The README also notes configs for lio_slam/ alongside vslam/ under config/.

Mapping output defaults to the results/ directory, and the repository ships screenshots of KITTI visual odometry, EuRoC VO, LIO SLAM, LIO localization, a direct-method feature tracking example, point cloud visualization, DepthAnythingV2 output and Segment Anything output on KITTI. Those images are the only evidence of behaviour available here. No benchmark numbers, accuracy tables or runtime figures are given in the material, and the README does not claim any. If you need to know how the stereo pipeline scores on KITTI, you will have to run it yourself. The documentation tells you how to start it, not how well it performs.

The deep learning layer and its version coupling

The frontend and semantics folders are marked in the README as C++ tools based on TensorRT, tensorflow_cc and onnxruntime, with SuperPoint, SuperGlue, Depth-Anything, HFNet and Segment-Anything named as examples. Each of those runtimes brings its own compatibility matrix, and the README does not flatten them into one. It points to a separate GPU_support.md file for "tested configurations" of the CUDA ecosystem, and to a separate tensorflow_cc repository for the TensorFlow path.

This is the part of the project with the shortest shelf life. CUDA, cuDNN and TensorRT versions move faster than the rest of the SLAM stack, and a repository that pins them in one CMake tree inherits that churn. The install_dl_models.sh script downloads weights, which means the examples depend on external hosting that the repository does not control. None of this is a flaw in the design, but it does mean the deep learning examples are the most likely to break first and the hardest to fix without reading GPU_support.md closely. If your interest is purely geometric SLAM, you can ignore this layer entirely and the build gets simpler.

What slamplay is not, and what to use instead

slamplay is not a SLAM library. There is no single header you include, no documented API surface, and no release in the material provided. It is a set of examples plus the CMake glue that makes them compile together. That distinction determines when it is the wrong tool. If you want to add pose-graph optimization to an existing product, pulling in gtsam or ceres directly gives you a maintained upstream, documentation written by its own authors, and a version you can pin. Going through slamplay adds a layer whose job is to make examples run on Ubuntu, not to serve as a stable interface.

Compared with a full framework such as ORB-SLAM, the difference in approach is structural. ORB-SLAM is a pipeline you run and, if you wish, modify. slamplay is a collection of building blocks and reference implementations, with the pipelines in full_slam/ sitting alongside isolated examples for triangulation, the direct method, NDT or IEKF-based LIO. It is closer to a lab manual than to a product. That is the right shape for learning, and the wrong shape for shipping.

The licence is the other concrete gap. The repository metadata supplied here lists the licence as unknown, and the README's table of contents has a License section whose contents are not included in the material available. Before you copy any file from this repository into your own codebase, find and read that section and any licence file in the tree. This article cannot tell you what terms apply, and it should not be treated as legal advice.

Maintenance cost and who should adopt it

The cost profile follows from the design. A single CMake tree that vendors or builds g2o, gtsam, ceres, se-sync, OpenCV, PCL, Eigen, Sophus, cholmod, Pangolin, imgui, rerun, DBoW2, DBoW3, iBoW, TensorRT, tensorflow_cc, libtorch and onnxruntime has a long first build and a long rebuild whenever any one of them moves. The README acknowledges the build time. The TensorFlow C++ step is called out as long enough that it must be run manually. The local OpenCV install is recommended even when a system copy exists, which adds time to every clean build.

Upgrade cost is concentrated in the deep learning layer and in the vendored ROS subset. The former tracks the CUDA ecosystem through GPU_support.md. The latter is a minimal ROS1-compatible library under thirdparty/ros/, so any bag containing message types outside that subset is out of scope by construction, as thirdparty/ros/README.md is said to describe. Neither of these is a bug. They are the boundaries of what the project chose to support.

Adopt slamplay for coursework, for self-study, or as a source of readable reference implementations of specific algorithms. Do not adopt it as a build dependency for production SLAM. Before committing to it, read the License section, check GPU_support.md against your driver and toolkit versions, and decide whether the TensorFlow C++ path is needed at all, since skipping it removes the longest manual install step.

Editorial conclusion

Adopt slamplay if you are learning C++ SLAM or preparing course material and want g2o, gtsam, ceres, OpenCV, PCL, Sophus, Pangolin and the deep learning runtimes already wired into one CMake tree with runnable examples. Do not adopt it as a runtime dependency for a product: the repository defines no release, no versioned interface and no published licence, and the README itself frames it as a collection of tools for playing and experimenting. Verify the licence file before you copy any code, check that the CUDA, cuDNN and TensorRT combination you have matches the tested matrix in GPU_support.md, and confirm whether the TensorFlow C++ path is worth the manual install_tensorflow_cc.sh step for your use case. If you only need pose-graph optimization, taking gtsam or ceres directly is less work than building this tree.

Official sources

1. Issues
2. luigifreda/slamplay on GitHub
3. README