# Cartographer Overview

Cartographer is a system that provides real-time simultaneous localization and mapping (SLAM) in 2D and 3D across multiple platforms and sensor configurations. It is designed to build globally consistent maps from sensor data using a combination of local submap construction and global loop closure optimization.

## Core Architecture

The library is organized into three main components:

### 1. Mapping (`cartographer/mapping`)

The mapping component implements the SLAM algorithm's core logic:

- **MapBuilder** — The top-level entry point that wires together trajectory builders (for local submaps) and a pose graph (for global loop closure).
- **TrajectoryBuilder** — Constructs local submaps from sensor data using scan matching. Separate implementations exist for 2D and 3D.
- **PoseGraph** — Maintains the global map by optimizing trajectory poses using constraints from loop closure detection and scan matching.
- **Submaps** — Probabilistic grid representations (2D probability grids, 3D hybrid grids) that store local map data.
- **Scan Matching** — Multiple algorithms: Ceres-based optimization, real-time correlative scan matching, and fast correlative scan matching (both 2D and 3D).

### 2. Sensor (`cartographer/sensor`)

The sensor component handles sensor data representation and processing:

- **Data Types** — Range data (origin, returns, misses), point clouds, IMU data, odometry data, landmark data, and fixed-frame pose data.
- **Collation** — Multi-queue and trajectory-based collation for synchronizing data from multiple sensors.
- **Filters** — Voxel filtering for point cloud downsampling.
- **Range Data Transforms** — Coordinate transformation and cropping utilities.

### 3. Common (`cartographer/common`)

Shared utilities and infrastructure:

- **Time** — Universal Time Scale (UTS) timestamp representation with 100ns resolution.
- **Lua Parameter Dictionary** — Configuration system using Lua scripts for hierarchical parameter management.
- **Thread Pool** — Background thread management for computationally intensive tasks.
- **Math Utilities** — Common mathematical functions and types.
- **Task System** — Asynchronous task execution framework.
- **Configuration File Resolver** — Loads and resolves Lua configuration files with includes.

## Configuration System

Cartographer uses Lua configuration files for all tunable parameters. The configuration hierarchy:

```
map_builder.lua          # Top-level: selects 2D/3D, background threads, pose graph
├── trajectory_builder_2d.lua   # 2D local SLAM parameters
├── trajectory_builder_3d.lua   # 3D local SLAM parameters
├── pose_graph.lua              # Global optimization parameters
└── trajectory_builder.lua      # Shared trajectory builder settings
```

Key configuration areas:
- **Local SLAM**: Voxel filtering, scan matching (Ceres, correlative), motion filtering, submap parameters
- **Global SLAM**: Constraint builder (loop closure detection), optimization problem (Ceres), global sampling

## Data Flow

```
Sensor Data → Collator → TrajectoryBuilder → Local Submaps
                                    ↓
                              PoseGraph ← Constraints (loop closure)
                                    ↓
                            Optimized Global Map
```

## Supported Platforms

- **2D SLAM**: Planar laser scanners, possibly with IMU and odometry
- **3D SLAM**: 3D lidars (Velodyne, Ouster, etc.), possibly with IMU and odometry
- **Multi-session**: Supports multiple trajectories, map merging, and serialization/deserialization

## Key Design Principles

1. **Separation of local and global SLAM** — Local trajectory builders operate independently; pose graph handles global consistency.
2. **Probabilistic submaps** — Grids store occupancy probabilities, enabling robust scan matching.
3. **Configurable via Lua** — All parameters exposed through hierarchical Lua configuration.
4. **Serialization support** — Full state (submaps, trajectories, constraints) can be saved and loaded.
5. **Multi-threaded** — Background threads for scan matching and optimization.

## Cross-References

- [cartographer_ros Overview](../cartographer_ros/cartographer_ros/overview.md) — ROS 2 integration package
- [cartographer_ros_msgs](../cartographer_ros/cartographer_ros_msgs/index.md) — ROS message and service definitions
- [cartographer_rviz](../cartographer_ros/cartographer_rviz/index.md) — RViz visualization plugin

## Contents

```{toctree}
:maxdepth: 2
:caption: Cartographer Documentation

quickstart
mapping/map_builder
mapping/map_builder_interface
mapping/trajectory_builder_interface
mapping/pose_graph_interface
mapping/submaps
mapping/2d/map_limits
mapping/2d/probability_grid
mapping/2d/submap_2d
mapping/3d/hybrid_grid
mapping/3d/range_data_inserter_3d
mapping/3d/submap_3d
mapping/internal/2d/local_trajectory_builder_2d
mapping/internal/2d/scan_matching/ceres_scan_matcher_2d
mapping/internal/2d/scan_matching/fast_correlative_scan_matcher_2d
mapping/internal/2d/scan_matching/real_time_correlative_scan_matcher_2d
mapping/internal/3d/local_trajectory_builder_3d
mapping/internal/3d/scan_matching/ceres_scan_matcher_3d
mapping/internal/3d/scan_matching/fast_correlative_scan_matcher_3d
mapping/internal/constraints/constraint_builder
mapping/internal/optimization/optimization_problem_interface
mapping/internal/imu_based_pose_extrapolator
mapping/internal/motion_filter
mapping/proto/serialization
mapping/proto/submap
mapping/proto/map_builder_options
sensor/range_data
sensor/data
sensor/imu_data
sensor/odometry_data
sensor/fixed_frame_pose_data
sensor/landmark_data
sensor/point_cloud
sensor/compressed_point_cloud
sensor/collator_interface
sensor/internal/ordered_multi_queue
sensor/internal/collator
sensor/internal/dispatchable
sensor/internal/trajectory_collator
sensor/internal/voxel_filter
common/time
common/lua_parameter_dictionary
common/thread_pool
common/configuration_file_resolver
configuration_files/map_builder
configuration_files/trajectory_builder_2d
configuration_files/trajectory_builder_3d
configuration_files/pose_graph
configuration_files/trajectory_builder
```