# ariarobotics/robotic-mapping architecture

> Architecture diagram of the GitHub repository ariarobotics/robotic-mapping, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ariarobotics/robotic-mapping
- Repository: https://github.com/ariarobotics/robotic-mapping

## Overview

1. This repository is a course monorepo, not a single application. The top level is split into:
   - course-wide documentation and lecture PDFs,
   - reusable resource/docs,
   - several self-contained C++ example projects under `code/cpp`.

2. The `lectures/` and `resources/` directories are the instructional layer. They contain the curriculum PDFs, setup guides, dataset lists, and tooling references. These files support the code projects but do not participate in runtime execution.

3. The `data/` directory at the repo root is a shared sample dataset area. It currently contains a KITTI sequence (`KITTI07`) used by the visual odometry examples. Individual subprojects also carry their own local `data/` folders, so data is intentionally scoped per project.

4. `code/cpp/competition` is a standalone CMake-based C++ exercise centered on synthetic image data. Its bundled assets include camera calibration, trajectories, image sequences, and timing data, which suggests a pipeline for evaluating mapping/localization performance against synthetic ground truth.

5. `code/cpp/features` is another isolated C++ project with its own `src/` and `data/` folders. Based on the name and course context, it is the front-end feature extraction/matching exercise, likely meant to consume images and produce feature-level outputs for later SLAM stages.

6. `code/cpp/visual-odometry` is a self-contained visual odometry module. Its data layout mirrors a classic VO pipeline: calibrated image sequence plus timestamps, with source files `vo_epipolar.cpp` and `vo_epipolar_noviz.cpp` indicating a core epipolar geometry pipeline and a non-visualization variant.

7. `code/cpp/lidar-odometry` is a separate lidar front-end example. It uses a sequence of PLY point clouds (`cloud_0.ply` through `cloud_4.ply`) and a single `main.cpp`, indicating a small odometry pipeline focused on scan-to-scan pose estimation from point clouds.

8. `code/cpp/lio-slam` is the most complete SLAM subsystem and is organized as a ROS2 workspace with multiple packages:
   - `scanmatcher` for lidar scan matching and front-end processing,
   - `graph_based_slam` for back-end optimization and loop-closure style graph refinement,
   - `lidarslam_msgs` for custom message definitions,
   - `Thirdparty/ndt_omp_ros2` for an embedded registration library.

9. The main data flow in `lio-slam` is front-end to back-end:
   - sensor/scan data is processed in `scanmatcher` (`image_projection.cpp`, `imu_preintegration.cpp`, `scanmatcher_component.cpp`),
   - outputs are turned into ROS messages using `lidarslam_msgs`,
   - those outputs feed `graph_based_slam` for global consistency and map refinement.
   The presence of `launch/` and `rviz/` folders shows the system is intended to be run and inspected as a live ROS2 graph.

10. `scanmatcher` contains build, install, and log artifacts inside its tree, which means the repository includes a snapshot of a built ROS2 workspace, not just source. For architecture diagrams, those generated directories should be treated as non-source outputs, not separate subsystems.

11. `Thirdparty/ndt_omp_ros2` is an embedded external dependency rather than course-authored code. It provides optimized NDT/GICP/OpenMP point-cloud registration implementations and ships with its own CMake, headers, sources, and test data (`.pcd` files). This is the main external algorithmic dependency in the SLAM stack.

12. Build/runtime tooling is split by subsystem:
   - the small examples use plain CMake,
   - the SLAM system uses ROS2 package manifests, launch files, YAML params, and RViz configs,
   - `.devcontainer/` folders appear in several projects for reproducible development environments.
   This means the repo supports both simple native builds and ROS2 workspace-style builds.

13. Across the repository, the main architectural boundary is between:
   - teaching material and datasets,
   - standalone algorithm exercises,
   - the integrated ROS2 SLAM stack.
   The course examples are intentionally modular so each front-end method can be studied independently before being combined in the full LIO/SLAM pipeline.

Main entry points: [`README.md`](https://github.com/ariarobotics/robotic-mapping/blob/main/README.md) (Course repo), [`code/cpp/lio-slam`](https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/lio-slam) (LIO-SLAM), [`code/cpp/visual-odometry`](https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/visual-odometry) (Visual odometry), [`code/cpp/lio-slam/scanmatcher`](https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/lio-slam/scanmatcher) (Scanmatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_instruct["Instructional"]
  node_n_lectures["Lectures<br/>course PDFs"]
  node_n_resources["Resources<br/>course docs"]
end

subgraph group_g_shared["Shared Data"]
  node_n_shared_data[("KITTI07<br/>shared dataset")]
end

subgraph group_g_examples["Standalone C++"]
  node_n_competition["Competition<br/>CMake exercise"]
  node_n_competition_src["Competition core<br/>evaluation app<br/>[competition.cpp]"]
  node_n_features["Features<br/>feature pipeline"]
  node_n_features_src["Feature code<br/>feature front-end<br/>[features.cpp]"]
  node_n_vo["Visual odometry<br/>VO module"]
  node_n_vo_epi["Epipolar VO<br/>visual odometry<br/>[vo_epipolar.cpp]"]
  node_n_vo_noviz["VO no-viz<br/>visual odometry"]
  node_n_lidar_vo["Lidar odometry<br/>scan odometry"]
  node_n_lidar_main["Lidar main<br/>odometry entry<br/>[main.cpp]"]
end

subgraph group_g_lio["ROS2 LIO-SLAM"]
  node_n_lio["LIO-SLAM<br/>ROS2 workspace"]
  node_n_scanmatcher["Scanmatcher<br/>SLAM front-end"]
  node_n_graph_slam["Graph SLAM<br/>SLAM back-end"]
  node_n_msgs["Lidar msgs<br/>ROS2 msgs"]
  node_n_ndt["NDT OMP<br/>third-party reg"]
end

node_n_readme["Course repo<br/>monorepo entry<br/>[README.md]"]

node_n_readme -->|"documents"| node_n_lectures
node_n_readme -->|"references"| node_n_resources
node_n_readme -->|"includes"| node_n_competition
node_n_readme -->|"includes"| node_n_features
node_n_readme -->|"includes"| node_n_vo
node_n_readme -->|"includes"| node_n_lidar_vo
node_n_readme -->|"includes"| node_n_lio
node_n_competition -->|"builds"| node_n_competition_src
node_n_features -->|"builds"| node_n_features_src
node_n_vo -->|"core"| node_n_vo_epi
node_n_vo -.->|"variant"| node_n_vo_noviz
node_n_vo -->|"uses"| node_n_shared_data
node_n_lidar_vo -->|"builds"| node_n_lidar_main
node_n_lio -->|"front-end"| node_n_scanmatcher
node_n_lio -->|"back-end"| node_n_graph_slam
node_n_lio -->|"messages"| node_n_msgs
node_n_lio -->|"depends on"| node_n_ndt
node_n_scanmatcher -->|"publishes"| node_n_msgs
node_n_scanmatcher -->|"feeds"| node_n_graph_slam
node_n_scanmatcher -->|"registers"| node_n_ndt
node_n_lio -.->|"shares data"| node_n_shared_data

click node_n_readme "https://github.com/ariarobotics/robotic-mapping/blob/main/README.md"
click node_n_lectures "https://github.com/ariarobotics/robotic-mapping/tree/main/lectures"
click node_n_resources "https://github.com/ariarobotics/robotic-mapping/tree/main/resources"
click node_n_shared_data "https://github.com/ariarobotics/robotic-mapping/tree/main/data/KITTI07"
click node_n_competition "https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/competition"
click node_n_competition_src "https://github.com/ariarobotics/robotic-mapping/blob/main/code/cpp/competition/src/competition.cpp"
click node_n_features "https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/features"
click node_n_features_src "https://github.com/ariarobotics/robotic-mapping/blob/main/code/cpp/features/src/features.cpp"
click node_n_vo "https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/visual-odometry"
click node_n_vo_epi "https://github.com/ariarobotics/robotic-mapping/blob/main/code/cpp/visual-odometry/src/vo_epipolar.cpp"
click node_n_vo_noviz "https://github.com/ariarobotics/robotic-mapping/blob/main/code/cpp/visual-odometry/src/vo_epipolar_noviz.cpp"
click node_n_lidar_vo "https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/lidar-odometry"
click node_n_lidar_main "https://github.com/ariarobotics/robotic-mapping/blob/main/code/cpp/lidar-odometry/src/main.cpp"
click node_n_lio "https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/lio-slam"
click node_n_scanmatcher "https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/lio-slam/scanmatcher"
click node_n_graph_slam "https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/lio-slam/graph_based_slam"
click node_n_msgs "https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/lio-slam/lidarslam_msgs"
click node_n_ndt "https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/lio-slam/Thirdparty/ndt_omp_ros2"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_lectures,node_n_resources toneBlue
class node_n_shared_data toneAmber
class node_n_competition,node_n_competition_src,node_n_features,node_n_features_src,node_n_vo,node_n_vo_epi,node_n_vo_noviz,node_n_lidar_vo,node_n_lidar_main toneMint
class node_n_lio,node_n_scanmatcher,node_n_graph_slam,node_n_msgs,node_n_ndt toneRose
class node_n_readme toneNeutral
```

## Components

### Instructional

Course-wide lectures and setup resources.

- [Lectures](https://github.com/ariarobotics/robotic-mapping/tree/main/lectures): course PDFs · Curriculum slides and lab handouts for the course. · `lectures`
- [Resources](https://github.com/ariarobotics/robotic-mapping/tree/main/resources): course docs · Setup notes, dataset lists, and tooling references. · `resources`

### Shared Data

Repository-level datasets used across examples.

- [KITTI07](https://github.com/ariarobotics/robotic-mapping/tree/main/data/KITTI07): shared dataset · Repository-level sample KITTI sequence used by VO examples. · `data/KITTI07`

### Standalone C++

Self-contained CMake exercises and front-end examples.

- [Competition](https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/competition): CMake exercise · Synthetic-image mapping/localization exercise with bundled assets. · `code/cpp/competition`
- [Competition core](https://github.com/ariarobotics/robotic-mapping/blob/main/code/cpp/competition/src/competition.cpp): evaluation app · Main executable for synthetic competition data processing. · `code/cpp/competition/src/competition.cpp`
- [Features](https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/features): feature pipeline · Standalone feature extraction and matching exercise. · `code/cpp/features`
- [Feature code](https://github.com/ariarobotics/robotic-mapping/blob/main/code/cpp/features/src/features.cpp): feature front-end · Feature-processing implementation for the course exercise. · `code/cpp/features/src/features.cpp`
- [Visual odometry](https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/visual-odometry): VO module · Self-contained epipolar visual odometry example. · `code/cpp/visual-odometry`
- [Epipolar VO](https://github.com/ariarobotics/robotic-mapping/blob/main/code/cpp/visual-odometry/src/vo_epipolar.cpp): visual odometry · Core epipolar geometry pipeline for monocular VO. · `code/cpp/visual-odometry/src/vo_epipolar.cpp`
- [VO no-viz](https://github.com/ariarobotics/robotic-mapping/blob/main/code/cpp/visual-odometry/src/vo_epipolar_noviz.cpp): visual odometry · Headless variant of the epipolar VO pipeline. · `code/cpp/visual-odometry/src/vo_epipolar_noviz.cpp`
- [Lidar odometry](https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/lidar-odometry): scan odometry · Small point-cloud odometry example over a short sequence. · `code/cpp/lidar-odometry`
- [Lidar main](https://github.com/ariarobotics/robotic-mapping/blob/main/code/cpp/lidar-odometry/src/main.cpp): odometry entry · Single executable driving the lidar odometry pipeline. · `code/cpp/lidar-odometry/src/main.cpp`

### ROS2 LIO-SLAM

Integrated ROS2 workspace for lidar-inertial SLAM.

- [LIO-SLAM](https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/lio-slam): ROS2 workspace · Integrated lidar-inertial SLAM system with live launch and visualization. · `code/cpp/lio-slam`
- [Scanmatcher](https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/lio-slam/scanmatcher): SLAM front-end · ROS2 package for scan matching, projection, and IMU preintegration. · `code/cpp/lio-slam/scanmatcher`
- [Graph SLAM](https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/lio-slam/graph_based_slam): SLAM back-end · ROS2 package for global optimization and map refinement. · `code/cpp/lio-slam/graph_based_slam`
- [Lidar msgs](https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/lio-slam/lidarslam_msgs): ROS2 msgs · Custom message definitions connecting SLAM components. · `code/cpp/lio-slam/lidarslam_msgs`
- [NDT OMP](https://github.com/ariarobotics/robotic-mapping/tree/main/code/cpp/lio-slam/Thirdparty/ndt_omp_ros2): third-party reg · Embedded external dependency for optimized point-cloud registration. · `code/cpp/lio-slam/Thirdparty/ndt_omp_ros2`

### Other components

- [Course repo](https://github.com/ariarobotics/robotic-mapping/blob/main/README.md): monorepo entry · Top-level repository overview and navigation. · `README.md`

## Connections

- Course repo → Lectures: documents · Course overview points to instructional material.
- Course repo → Resources: references · Top-level repo guidance references setup resources.
- Course repo → Competition: includes · Repository contains standalone C++ exercises.
- Course repo → Features: includes · Repository contains standalone C++ exercises.
- Course repo → Visual odometry: includes · Repository contains standalone C++ exercises.
- Course repo → Lidar odometry: includes · Repository contains standalone C++ exercises.
- Course repo → LIO-SLAM: includes · Repository contains integrated ROS2 SLAM stack.
- Competition → Competition core: builds · CMake exercise centers on a single executable source.
- Features → Feature code: builds · Feature exercise centers on its main source file.
- Visual odometry → Epipolar VO: core · Primary visual odometry implementation.
- Visual odometry → VO no-viz: variant · Non-visualization variant of the same pipeline.
- Visual odometry → KITTI07: uses · Uses the shared KITTI sequence from the repo root.
- Lidar odometry → Lidar main: builds · Single-file odometry pipeline entry point.
- LIO-SLAM → Scanmatcher: front-end · Scan matching package handles sensor processing.
- LIO-SLAM → Graph SLAM: back-end · Graph optimization package handles global consistency.
- LIO-SLAM → Lidar msgs: messages · Custom ROS2 messages connect workspace components.
- LIO-SLAM → NDT OMP: depends on · Embedded third-party registration library.
- Scanmatcher → Lidar msgs: publishes · Front-end outputs are encoded as ROS messages.
- Scanmatcher → Graph SLAM: feeds · Front-end outputs flow into back-end optimization.
- Scanmatcher → NDT OMP: registers · Scan matching relies on optimized point-cloud registration.
- LIO-SLAM → KITTI07: shares data · Course dataset is reused across examples in the repo.
