# cartographer-project/cartographer architecture

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

- Interactive diagram: https://gitdiagram.com/cartographer-project/cartographer
- Repository: https://github.com/cartographer-project/cartographer

## Overview

##### Overall Project Type and Purpose
- Cartographer is meant to perform real‐time SLAM. It receives high-volume sensor inputs (e.g., LIDAR, IMU, cameras) and fuses that sensor data to generate maps and estimate trajectories on the fly.
- The system is designed for varied platforms and sensor configurations. It includes real-time local processing and, in some modules, cloud integration (as evident in directories like cartographer/cloud).

##### Key Components
a. Sensor Input & Preprocessing:
- Sensor data sources (e.g., IMU, LIDAR, camera) feeding into the system.
- Sensor module (refer to cartographer/sensor and its subdirectories) for data aggregation, filtering, and initial preprocessing.
b. Data Transformation:
- A module for handling coordinate transformations (cartographer/transform). This component is crucial in aligning sensor data and converting between coordinate systems.
c. Local Mapping & Trajectory Building:
- That there is a clear separation between 2D and 3D mapping functionalities.
d. Global Optimization & Pose Graph:
- A block for global optimization (pose graph optimization) that refines the map and fuses local trajectories. The directories under cartographer/mapping/internal/pose_graph and optimization clearly indicate this role.
e. IO and Serialization:
- Modules concerned with data input/output and persistence (cartographer/io). This covers functionalities like reading/writing proto streams (for pbstream) and interfacing with file systems.
f. Cloud and Server Integration:
- A dedicated module is visible under cartographer/cloud, which supports cloud-based map building and client-server interactions.
- This part may also include integration with external monitoring (e.g., Prometheus metrics as seen in cartographer/cloud/metrics).
g. Build and Configuration Infrastructure:
- The system also involves various build configurations (Bazel, CMake, Dockerfiles) and testing frameworks.

##### Interactions and Data Flow
- Finally, indicate how the output can be used by a Map Builder Server (cloud integration) or written to disk via the IO modules.

##### Architectural Patterns and Design Principles
- The design clearly separates concerns by dividing the system into modules handling sensor integration, geometric transformation, local SLAM processing, and global map optimization.
- It also employs an extensible structure (with dedicated directories for cloud, configuration, testing, and third-party libraries) that supports modular reusability and testing.
- The use of separate configuration files (e.g., Lua configuration files under configuration_files) highlights the emphasis on flexibility and ease of customization.

##### Relevant Technologies / Frameworks
- Containerization: Dockerfiles indicate deployment in isolated environments.
- Protocol Buffers: Many proto files across mapping, cloud, and sensor directories indicate a heavy reliance on protobufs for data serialization.
- External integrations: Prometheus for metrics and a potential ROS integration (though the primary repository now is not actively maintained for ROS) can be mentioned.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Main Components
    sensor["Sensor Input & Preprocessing"]:::sensor
    transform["Data Transformation"]:::transform

    subgraph "Local Mapping & Trajectory Building"
        map2d["Mapping 2D"]:::mapping
        map2d_int["Mapping 2D Internal"]:::mapping
        map3d["Mapping 3D"]:::mapping
        map3d_int["Mapping 3D Internal"]:::mapping
    end

    subgraph "Global Optimization & Pose Graph"
        pose_cc["Pose Graph CC"]:::globalOpt
        pose_h["Pose Graph Header"]:::globalOpt
        optimization["Optimization"]:::globalOpt
    end

    io["IO & Serialization"]:::io
    cloud["Cloud Integration"]:::cloud

    subgraph "Build & Configuration Infrastructure"
        config["Configuration Files"]:::infra
        cmake["CMakeLists.txt"]:::infra
        bazel["BUILD.bazel"]:::infra
        bazelci[".bazelci"]:::infra
        github[".github"]:::infra
        docker["Dockerfile.*"]:::infra
    end

    %% Data Flow Connections
    sensor --> transform
    transform --> map2d
    transform --> map3d
    map2d --> map2d_int
    map3d --> map3d_int
    map2d_int --> optimization
    map3d_int --> optimization
    optimization --> pose_cc
    optimization --> pose_h
    pose_cc --> io
    pose_h --> io
    io --> cloud
    %% Feedback Loops
    pose_cc -- "feedback" --> map2d
    pose_h -- "feedback" --> map3d

    %% Support Infrastructure (dashed connections)
    sensor --- config
    transform --- config
    optimization --- cmake
    io --- bazel
    cloud --- docker

    %% Click Events
    click sensor "https://github.com/cartographer-project/cartographer/tree/master/cartographer/sensor"
    click transform "https://github.com/cartographer-project/cartographer/tree/master/cartographer/transform"
    click map2d "https://github.com/cartographer-project/cartographer/tree/master/cartographer/mapping/2d"
    click map2d_int "https://github.com/cartographer-project/cartographer/tree/master/cartographer/mapping/internal/2d"
    click map3d "https://github.com/cartographer-project/cartographer/tree/master/cartographer/mapping/3d"
    click map3d_int "https://github.com/cartographer-project/cartographer/tree/master/cartographer/mapping/internal/3d"
    click pose_cc "https://github.com/cartographer-project/cartographer/blob/master/cartographer/mapping/pose_graph.cc"
    click pose_h "https://github.com/cartographer-project/cartographer/blob/master/cartographer/mapping/pose_graph.h"
    click optimization "https://github.com/cartographer-project/cartographer/tree/master/cartographer/mapping/internal/optimization"
    click io "https://github.com/cartographer-project/cartographer/tree/master/cartographer/io"
    click cloud "https://github.com/cartographer-project/cartographer/tree/master/cartographer/cloud"
    click config "https://github.com/cartographer-project/cartographer/tree/master/configuration_files"
    click cmake "https://github.com/cartographer-project/cartographer/blob/master/CMakeLists.txt"
    click bazel "https://github.com/cartographer-project/cartographer/blob/master/BUILD.bazel"
    click bazelci "https://github.com/cartographer-project/cartographer/blob/master/.bazelci"
    click github "https://github.com/cartographer-project/cartographer/blob/master/.github"
    click docker "https://github.com/cartographer-project/cartographer/blob/master/Dockerfile.*"

    %% Styles
    classDef sensor fill:#f9d5d3,stroke:#cc3333,stroke-width:2px;
    classDef transform fill:#fbe7a1,stroke:#f08a24,stroke-width:2px;
    classDef mapping fill:#c0e0de,stroke:#347474,stroke-width:2px;
    classDef globalOpt fill:#d6b3ff,stroke:#5b53a0,stroke-width:2px;
    classDef io fill:#e2f0cb,stroke:#86b300,stroke-width:2px;
    classDef cloud fill:#b3d4fc,stroke:#0e73ce,stroke-width:2px;
    classDef infra fill:#e6e6e6,stroke:#666666,stroke-width:2px;

    class sensor sensor;
    class transform transform;
    class map2d,map2d_int,map3d,map3d_int mapping;
    class pose_cc,pose_h,optimization globalOpt;
    class io io;
    class cloud cloud;
    class config,cmake,bazel,bazelci,github,docker infra;
```
