# rsasaki0109/lidar_localization_ros2 architecture

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

- Interactive diagram: https://gitdiagram.com/rsasaki0109/lidar_localization_ros2
- Repository: https://github.com/rsasaki0109/lidar_localization_ros2

## Overview

lidar_localization_ros2 is a ROS 2 map-based 3D LiDAR localization system, usable standalone or with Nav2. Its principal workflow accepts a point-cloud map and sensor streams, initializes a pose (by whole-map search or a supplied estimate), predicts motion from odometry/IMU, matches scans to the map, and publishes localization for tracking and recovery. The graph also shows the documented global-search and Nav2 branches, plus the substantial prior-map GLIM experiment. Relationships in unsampled runtime areas are omitted; edges rely on the README or shown source/index references.

Main entry points: [`src/lidar_localization_node.cpp`](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/src/lidar_localization_node.cpp) (ROS localizer), [`src/component_alignment.cpp`](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/src/component_alignment.cpp) (Scan alignment), [`scripts/global_localization_node.py`](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/scripts/global_localization_node.py) (Global search node), [`scripts/quickstart.py`](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/scripts/quickstart.py) (Quickstart)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bringup["Bringup and ROS"]
  node_quickstart["Quickstart<br/>[quickstart.py]"]
  node_launch["ROS launch"]
end

subgraph group_tracking["Pose Tracking"]
  node_localizer["ROS localizer"]
  node_scan_alignment["Scan alignment"]
  node_alignment_policy["Alignment pipeline policy"]
  node_registration_tree["Registration target tree"]
  node_imu_smoother["IMU smoother"]
end

subgraph group_relocalization["Global Relocalization"]
  node_global_node["Global search node"]
  node_global_query["Global search query"]
  node_bbs_attempts["BBS attempts"]
  node_recovery["Recovery supervision"]
end

subgraph group_integration["Robot Integration"]
  node_nav2["Nav2 stack"]
end

subgraph group_experimental["Prior Map Experiment"]
  node_prior_localizer["GLIM prior localizer"]
  node_ply_loader["PLY map loader<br/>[ply_loader.hpp]"]
end

node_operator(("Operator"))
node_sensors(("LiDAR and IMU"))
node_odometry(("Odometry source"))

node_operator -->|"starts"| node_quickstart
node_sensors -->|"provides scans"| node_localizer
node_odometry -->|"predicts motion"| node_localizer
node_quickstart -->|"starts tracking"| node_localizer
node_launch -->|"launches"| node_localizer
node_localizer -.->|"matches scans"| node_scan_alignment
node_scan_alignment -->|"uses policy"| node_alignment_policy
node_scan_alignment -.->|"sets target"| node_registration_tree
node_imu_smoother -.->|"uses IMU data"| node_sensors
node_operator -->|"requests search"| node_global_node
node_global_node -.->|"queries candidates"| node_global_query
node_global_query -->|"builds attempts"| node_bbs_attempts
node_global_node -.->|"recovers pose"| node_recovery
node_localizer -->|"publishes map to odom"| node_nav2
node_prior_localizer -->|"loads map"| node_ply_loader

click node_quickstart "https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/scripts/quickstart.py"
click node_launch "https://github.com/rsasaki0109/lidar_localization_ros2/tree/main/launch"
click node_localizer "https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/src/lidar_localization_node.cpp"
click node_scan_alignment "https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/src/component_alignment.cpp"
click node_alignment_policy "https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/include/lidar_localization/alignment_pipeline_policy.hpp"
click node_registration_tree "https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/include/lidar_localization/registration_target_search_tree.hpp"
click node_imu_smoother "https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/include/lidar_localization/imu_gtsam_smoother.hpp"
click node_global_node "https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/scripts/global_localization_node.py"
click node_global_query "https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/scripts/global_localization_query.py"
click node_bbs_attempts "https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/scripts/make_bbs_relocalization_attempts.py"
click node_recovery "https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/scripts/reinitialization_supervisor_node.py"
click node_nav2 "https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/launch/nav2_navigation.launch.py"
click node_prior_localizer "https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/experiments/glim_prior_map_localizer/src/prior_map_localizer.cpp"
click node_ply_loader "https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/experiments/glim_prior_map_localizer/include/glim_prior_map_localizer/ply_loader.hpp"

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_quickstart,node_launch toneBlue
class node_localizer,node_scan_alignment,node_alignment_policy,node_registration_tree,node_imu_smoother toneAmber
class node_global_node,node_global_query,node_bbs_attempts,node_recovery toneMint
class node_nav2 toneRose
class node_prior_localizer,node_ply_loader,node_operator,node_sensors,node_odometry toneIndigo
```

## Components

### Bringup and ROS

- [Quickstart](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/scripts/quickstart.py): `scripts/quickstart.py`
- [ROS launch](https://github.com/rsasaki0109/lidar_localization_ros2/tree/main/launch): `launch`

### Pose Tracking

- [ROS localizer](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/src/lidar_localization_node.cpp): `src/lidar_localization_node.cpp`
- [Scan alignment](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/src/component_alignment.cpp): `src/component_alignment.cpp`
- [Alignment pipeline policy](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/include/lidar_localization/alignment_pipeline_policy.hpp): `include/lidar_localization/alignment_pipeline_policy.hpp`
- [Registration target tree](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/include/lidar_localization/registration_target_search_tree.hpp): `include/lidar_localization/registration_target_search_tree.hpp`
- [IMU smoother](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/include/lidar_localization/imu_gtsam_smoother.hpp): `include/lidar_localization/imu_gtsam_smoother.hpp`

### Global Relocalization

- [Global search node](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/scripts/global_localization_node.py): `scripts/global_localization_node.py`
- [Global search query](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/scripts/global_localization_query.py): `scripts/global_localization_query.py`
- [BBS attempts](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/scripts/make_bbs_relocalization_attempts.py): `scripts/make_bbs_relocalization_attempts.py`
- [Recovery supervision](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/scripts/reinitialization_supervisor_node.py): `scripts/reinitialization_supervisor_node.py`

### Robot Integration

- [Nav2 stack](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/launch/nav2_navigation.launch.py): `launch/nav2_navigation.launch.py`

### Prior Map Experiment

- [GLIM prior localizer](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/experiments/glim_prior_map_localizer/src/prior_map_localizer.cpp): `experiments/glim_prior_map_localizer/src/prior_map_localizer.cpp`
- [PLY map loader](https://github.com/rsasaki0109/lidar_localization_ros2/blob/main/experiments/glim_prior_map_localizer/include/glim_prior_map_localizer/ply_loader.hpp): `experiments/glim_prior_map_localizer/include/glim_prior_map_localizer/ply_loader.hpp`

### Other components

- **Operator**
- **LiDAR and IMU**
- **Odometry source**

## Connections

- Operator → Quickstart: starts (evidence: `README.md`)
- LiDAR and IMU → ROS localizer: provides scans (evidence: `README.md`)
- Odometry source → ROS localizer: predicts motion (evidence: `README.md`)
- Quickstart → ROS localizer: starts tracking (evidence: `README.md`)
- ROS launch → ROS localizer: launches (evidence: `README.md`)
- ROS localizer → Scan alignment: matches scans
- Scan alignment → Alignment pipeline policy: uses policy (evidence: `include/lidar_localization/alignment_pipeline_policy.hpp`)
- Scan alignment → Registration target tree: sets target
- IMU smoother → LiDAR and IMU: uses IMU data
- Operator → Global search node: requests search (evidence: `README.md`)
- Global search node → Global search query: queries candidates
- Global search query → BBS attempts: builds attempts (evidence: `scripts/global_localization_query.py`)
- Global search node → Recovery supervision: recovers pose
- ROS localizer → Nav2 stack: publishes map to odom (evidence: `README.md`)
- GLIM prior localizer → PLY map loader: loads map (evidence: `experiments/glim_prior_map_localizer/src/prior_map_localizer.cpp`)
