# ethz-asl/maplab architecture

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

- Interactive diagram: https://gitdiagram.com/ethz-asl/maplab
- Repository: https://github.com/ethz-asl/maplab

## Overview

##### Project type and purpose
- This is **maplab 2.0**, a modular C++ research framework for visual-inertial multi-session and multi-robot mapping, with both command-line and ROS‐based applications (ROVIOLI, maplab-node, maplab-server-node), algorithm libraries, data structures, back-end services, and visualization.

##### High-level architectural layers
- Layer 1: **Hardware & External Services**
- Sensors (camera, IMU, LiDAR) via ROS topics or rosbag
- External “building blocks” (ROVIO, HNSW, PMVS, Docker/ROS master)
- Layer 2: **Core Libraries**
- aslam_cv2 (camera models, frames, detectors, trackers, geometric vision)
- common modules (vio-common, maplab-common, console-common, message-flow, serialization, resources)
- algorithms (feature-tracking, triangulation, dense reconstruction, IMU integration, loop closure, map optimization/sparsification/anchoring)
- Layer 3: **Map Data Structures**
- -structure packages: sensors, posegraph, localization-summary, vi-map
- backend: map-resources, map-manager for on-disk caching and I/O
- Layer 4: **Applications & Plugins**
- console apps (maplab-console, console-plugins) for interactive workflows
- ROS nodes (rovioli, maplab-node, maplab-server-node) for online VIO, mapping, multi-robot coordination
- maplab-launch (preconfigured launch files and sensor calibration data)
- Layer 5: **Visualization & Tools**
- visualization library (RViz plugins, plotters)
- tools (resource-importer, CSV export, test apps)
- deploy (Dockerfiles, scripts, CI)

##### Main components and interactions
a. **Sensor Input → ROVIO / Synchronizer Flow**
- ROS topics or rosbag → imu-camera-synchronizer → ROVIOLI node
- Produces odometry estimates, feature tracks
b. **Feature Tracking & Map Building**
- feature-tracking pipeline → landmark triangulation → stream-map-builder (online)
c. **Loop Closure & Optimization**
- loop closure modules detect matches → loop-closure-handler → map-optimization builds optimization problem → solver (Ceres)
d. **Map Storage & Management**
- vi-map data structure stored via map-resources → map-manager for caching and retrieval
e. **Console & Plugins**
- maplab-console orchestrates operations via message-flow bus → loads map, invokes plugins (dense-recon, sparsification, optimization) → writes out updated map
f. **Visualization**
- visualization sink publishes markers to RViz → user inspects trajectories, landmarks, map quality

##### Architectural patterns and principles
- **Layered modularity**: clear separation between perception, algorithms, data, back-end, and UI
- **Plugin system**: console plugins and ROS nodes loaded dynamically via shared libraries and gflags
- **Message bus**: common/message-flow for in-process pub/sub abstraction
- **Protobuf & YAML**: for serialization (maplab-common, aslam-serialization) and configuration
- **CMake/Catkin**: each module uses its own CMakeLists and package.xml to express dependencies

##### Detailed capture of essential elements
- **map-structure hierarchy** (sensors → posegraph → vi-map → summary) feeding into backend
- **console-common/message-flow** as a bus backbone connecting console and plugins
- With **technology labels**: C++, Protobuf, gflags, glog, OpenMP, ROS Melodic, Docker

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: Hardware & External Services
    subgraph "Layer 1: Hardware & External Services"
        direction TB
        Sensors["Sensors (Camera, IMU, LiDAR)"]:::external
        Rosbag["rosbag"]:::external
        IMUCamSync["imu-camera-synchronizer"]:::external
    end

    %% Layer 2: Core Libraries
    subgraph "Layer 2: Core Libraries"
        direction TB
        %% ASLAM CV2
        ASLAMCV2["aslam_cv2"]:::lib
        %% Common modules
        VIOCommon["common/vio-common"]:::lib
        MaplabCommon["common/maplab-common"]:::lib
        ConsoleCommon["common/console-common"]:::lib
        MsgFlow["common/message-flow"]:::lib
        AslamSer["common/aslam-serialization"]:::lib
        ResourcesCommon["common/resources-common"]:::lib
        DenseRecCommon["common/dense-reconstruction-common"]:::lib
        %% Algorithms
        FT["algorithms/feature-tracking"]:::lib
        LT["algorithms/landmark-triangulation"]:::lib
        DepthInt["algorithms/dense-reconstruction/depth_integration"]:::lib
        StereoDR["algorithms/dense-reconstruction/stereo-dense-reconstruction"]:::lib
        IMUInt["algorithms/imu-integrator-rk4"]:::lib
        subgraph "Loop Closure Modules"
            direction TB
            LCH["algorithms/loopclosure/loop-closure-handler"]:::lib
            MBL["algorithms/loopclosure/matching-based-loopclosure"]:::lib
            DP["algorithms/loopclosure/descriptor-projection"]:::lib
            VT["algorithms/loopclosure/vocabulary-tree"]:::lib
            LCCommon["algorithms/loopclosure/loopclosure-common"]:::lib
        end
        MO["algorithms/map-optimization"]:::lib
        MS["algorithms/map-sparsification"]:::lib
        MA["algorithms/map-anchoring"]:::lib
        SMB["algorithms/online-map-builders"]:::lib
        VMDI["algorithms/vi-map-data-import-export"]:::lib
        VMH["algorithms/vi-map-helpers"]:::lib
        CET["algorithms/ceres-error-terms"]:::lib
    end

    %% Layer 3: Map Data Structures
    subgraph "Layer 3: Map Data Structures"
        direction TB
        MSensors["map-structure/sensors"]:::lib
        PoseGraph["map-structure/posegraph"]:::lib
        LocSum["map-structure/localization-summary-map"]:::lib
        VIMap["map-structure/vi-map"]:::lib
        MR["backend/map-resources"]:::backend
        MM["backend/map-manager"]:::backend
    end

    %% Layer 4: Applications & Plugins
    subgraph "Layer 4: Applications & Plugins"
        direction TB
        ROVIOLI["ROVIOLI Node"]:::app
        MLNode["maplab-node"]:::app
        ServerNode["maplab-server-node"]:::app
        ConsoleApp["maplab-console"]:::app
        Plugins["console-plugins"]:::plugin
        Launch["maplab-launch"]:::app
    end

    %% Layer 5: Visualization & Tools
    subgraph "Layer 5: Visualization & Tools"
        direction TB
        Viz["visualization library & RViz sinks"]:::ui
        CSV["tools/csv-export"]:::app
        Importer["tools/resource-importer"]:::app
        Deploy["deploy"]:::backend
    end

    %% Data Flow Connections
    Sensors -->|"IMU+Image"| IMUCamSync -->|"synced data"| ROVIOLI
    Rosbag --> IMUCamSync
    ROVIOLI -->|"feature tracks"| FT -->|"landmarks"| LT -->|"online map"| SMB
    SMB --> MS
    SMB --> LCH
    LCH -->|"loop constraints"| MO --> CET
    VIMap --> MR --> MM
    ConsoleApp -->|pub/sub| MsgFlow -->|invokes| Plugins
    Plugins -.-> DepthInt
    Plugins -.-> StereoDR
    Plugins -.-> MS
    Plugins -.-> MA
    Plugins -.-> MO
    MsgFlow --> ConsoleCommon
    ConsoleApp --> VMDI --> VIMap
    Launch --> ROVIOLI
    Launch --> MLNode
    Launch --> ServerNode
    MLNode --> FT
    ServerNode --> MsgFlow
    Viz --> RViz["RViz"]:::ui
    CSV --> MM
    Importer --> MR

    %% Click Events
    click ROVIOLI "https://github.com/ethz-asl/maplab/tree/master/applications/rovioli"
    click MLNode "https://github.com/ethz-asl/maplab/tree/master/applications/maplab-node"
    click ServerNode "https://github.com/ethz-asl/maplab/tree/master/applications/maplab-server-node"
    click ConsoleApp "https://github.com/ethz-asl/maplab/tree/master/applications/maplab-console"
    click Plugins "https://github.com/ethz-asl/maplab/tree/master/console-plugins"
    click FT "https://github.com/ethz-asl/maplab/tree/master/algorithms/feature-tracking"
    click LT "https://github.com/ethz-asl/maplab/tree/master/algorithms/landmark-triangulation"
    click DepthInt "https://github.com/ethz-asl/maplab/tree/master/algorithms/dense-reconstruction/depth_integration"
    click StereoDR "https://github.com/ethz-asl/maplab/tree/master/algorithms/dense-reconstruction/stereo-dense-reconstruction"
    click IMUInt "https://github.com/ethz-asl/maplab/tree/master/algorithms/imu-integrator-rk4"
    click LCH "https://github.com/ethz-asl/maplab/tree/master/algorithms/loopclosure/loop-closure-handler"
    click MBL "https://github.com/ethz-asl/maplab/tree/master/algorithms/loopclosure/matching-based-loopclosure"
    click DP "https://github.com/ethz-asl/maplab/tree/master/algorithms/loopclosure/descriptor-projection"
    click VT "https://github.com/ethz-asl/maplab/tree/master/algorithms/loopclosure/vocabulary-tree"
    click LCCommon "https://github.com/ethz-asl/maplab/tree/master/algorithms/loopclosure/loopclosure-common"
    click MO "https://github.com/ethz-asl/maplab/tree/master/algorithms/map-optimization"
    click MS "https://github.com/ethz-asl/maplab/tree/master/algorithms/map-sparsification"
    click MA "https://github.com/ethz-asl/maplab/tree/master/algorithms/map-anchoring"
    click SMB "https://github.com/ethz-asl/maplab/tree/master/algorithms/online-map-builders"
    click VMDI "https://github.com/ethz-asl/maplab/tree/master/algorithms/vi-map-data-import-export"
    click VMH "https://github.com/ethz-asl/maplab/tree/master/algorithms/vi-map-helpers"
    click CET "https://github.com/ethz-asl/maplab/tree/master/algorithms/ceres-error-terms"
    click ASLAMCV2 "https://github.com/ethz-asl/maplab/tree/master/aslam_cv2"
    click VIOCommon "https://github.com/ethz-asl/maplab/tree/master/common/vio-common"
    click MaplabCommon "https://github.com/ethz-asl/maplab/tree/master/common/maplab-common"
    click ConsoleCommon "https://github.com/ethz-asl/maplab/tree/master/common/console-common"
    click MsgFlow "https://github.com/ethz-asl/maplab/tree/master/common/message-flow"
    click AslamSer "https://github.com/ethz-asl/maplab/tree/master/common/aslam-serialization"
    click ResourcesCommon "https://github.com/ethz-asl/maplab/tree/master/common/resources-common"
    click DenseRecCommon "https://github.com/ethz-asl/maplab/tree/master/common/dense-reconstruction-common"
    click MR "https://github.com/ethz-asl/maplab/tree/master/backend/map-resources"
    click MM "https://github.com/ethz-asl/maplab/tree/master/backend/map-manager"
    click MSensors "https://github.com/ethz-asl/maplab/tree/master/map-structure/sensors"
    click PoseGraph "https://github.com/ethz-asl/maplab/tree/master/map-structure/posegraph"
    click LocSum "https://github.com/ethz-asl/maplab/tree/master/map-structure/localization-summary-map"
    click VIMap "https://github.com/ethz-asl/maplab/tree/master/map-structure/vi-map"
    click Launch "https://github.com/ethz-asl/maplab/tree/master/maplab-launch"
    click Viz "https://github.com/ethz-asl/maplab/tree/master/visualization"
    click CSV "https://github.com/ethz-asl/maplab/tree/master/tools/csv-export"
    click Importer "https://github.com/ethz-asl/maplab/tree/master/tools/resource-importer"
    click Deploy "https://github.com/ethz-asl/maplab/tree/master/deploy"

    %% Styles
    classDef lib fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef app fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20
    classDef backend fill:#ffe0b2,stroke:#e65100,color:#e65100
    classDef ui fill:#e1bee7,stroke:#4a148c,color:#4a148c
    classDef plugin stroke-dasharray: 5 5,fill:#ffffff,stroke:#ff8f00,color:#ff8f00
    classDef external fill:#cfd8dc,stroke:#607d8b,color:#37474f
```
