# cra-ros-pkg/robot_localization architecture

> Architecture diagram of the GitHub repository cra-ros-pkg/robot_localization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cra-ros-pkg/robot_localization
- Repository: https://github.com/cra-ros-pkg/robot_localization

## Overview

##### Project Type and Purpose
- Type: A ROS (Robot Operating System) C++ package providing nonlinear state‐estimation nodes (EKF, UKF, NavSat transform).
- Purpose: Fuse multiple sensor inputs (IMU, odometry, GPS, etc.) into a consistent robot state estimate, expose that estimate via ROS topics, tf, and services.

##### File Structure
- /robot_localization: Core filter libraries (FilterBase, EKF, UKF, utilities).
- src: Node entry points (ekf_node.cpp, ukf_node.cpp, navsat_transform_node.cpp, listener nodes).
- launch: ROS 2 Python‐based launch files for each node and examples.
- params: YAML parameter files per node.
- srv: Service definitions (e.g., FromLL, ToLL, GetState).
- test: Unit and integration tests (bag playback, node launch tests).
- doc: Sphinx documentation and examples.

##### README for Insights
- Core functionality: nonlinear state estimation nodes.
- External dependencies: ROS, geometry_msgs, sensor_msgs, tf2, etc.
- Integration points: nodes subscribe to sensor topics, publish state, broadcast tf, provide services for coordinate conversions.

##### Main Components and Their Interactions
1) Sensor interfaces (external ROS topics: /imu/data, /odom, /gps/fix, etc.)
2) Filter library (FilterBase, EKF, UKF, NavSatTransform)
3) ROS Node wrappers (ekf_node, ukf_node, navsat_transform_node, listener node)
4) Parameter server (YAML files loaded at node startup)
5) ROS infrastructure (roscore, tf2, topics, services)
6) Output interfaces (PoseStamped topic, nav_msgs/Odometry, tf2 frames)
7) Services for datum and coordinate conversion (FromLL, ToLL, SetDatum, GetState)

- Sensors → ROS Topics → Filter Node (subscriber callbacks)
- Parameter Server → Node (on startup)
- Filter Node → Filter Library (calls into EKF/UKF classes)
- Filter Library → State Estimate → Node publishes to:
– /odometry topic
– tf2 (broadcast frames)
- Node offers ROS Services → Clients can call coordinate‐conversion or reset datum
- NavSatTransform Node → communicates with filter nodes or external nodes via topics/services

##### Architectural Patterns & Design Principles
- Modularity: clear separation between filtering algorithms (library code) and ROS interface (nodes).
- Extensibility: new filters or measurement models can be added under include/robot_localization.
- Configuration‐driven: use of YAML params in params/ directory to configure measurement frequency, covariances, frames.
- Testability: comprehensive unit tests (gtests) and integration tests (ROS bag playback).

##### Technologies/Frameworks to Annotate
- CMakeLists.txt / ament/Catkin build
- ROS (roscpp, roscpp nodelets if used)
- tf2 for transforms
- geometry_msgs, nav_msgs, sensor_msgs
- YAML parameters, launch.py for ROS 2

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Sensors Cluster
    subgraph "Sensors" 
        direction TB
        IMU["/imu/data"]:::topic
        ODOM["/odom"]:::topic
        GPS["/gps/fix"]:::topic
    end

    %% Parameter Server
    subgraph "Parameter Server" 
        direction TB
        EKF_YAML[(ekf.yaml)]:::config
        UKF_YAML[(ukf.yaml)]:::config
        NAVSAT_YAML[(navsat_transform.yaml)]:::config
        DUAL_EXAMPLE_YAML[(dual_ekf_navsat_example.yaml)]:::config
    end

    %% ROS Node Wrappers
    subgraph "ROS Nodes" 
        direction TB
        EKF_NODE["ekf_node"]:::rosnode
        UKF_NODE["ukf_node"]:::rosnode
        NAVSAT_NODE["navsat_transform_node"]:::rosnode
        LISTENER_NODE["robot_localization_listener_node"]:::rosnode
    end

    %% Filter Library
    subgraph "Filter Library" 
        direction TB
        FILTER_BASE["FilterBase"]:::library
        EKF_LIB["EKF"]:::library
        UKF_LIB["UKF"]:::library
        NAVSAT_LIB["NavSatTransform"]:::library
        UTIL_LIB["FilterUtilities"]:::library
    end

    %% TF2 & Output Interface
    subgraph "Output Interfaces"
        direction TB
        ODOMETRY["/odometry/filtered"]:::topic
        POSE["/pose/filtered"]:::topic
        TF2["tf2 Broadcast"]:::service
    end

    %% Services
    subgraph "Services" 
        direction TB
        FROMLL["FromLL"]:::service
        TOLL["ToLL"]:::service
        SETDATUM["SetDatum"]:::service
        GETSTATE["GetState"]:::service
    end

    %% Launch Files (optional dashed)
    subgraph "Launch Files" 
        direction TB
        EKF_LAUNCH["ekf.launch.py"]:::infra
        UKF_LAUNCH["ukf.launch.py"]:::infra
        NAVSAT_LAUNCH["navsat_transform.launch.py"]:::infra
        DUAL_LAUNCH["dual_ekf_navsat_example.launch.py"]:::infra
    end

    %% Data Flows
    IMU -->|"subscribe"| EKF_NODE
    ODOM -->|"subscribe"| EKF_NODE
    GPS -->|"subscribe"| NAVSAT_NODE

    EKF_NODE -->|"calls"| FILTER_BASE
    EKF_NODE -->|"calls"| EKF_LIB
    UKF_NODE -->|"calls"| FILTER_BASE
    UKF_NODE -->|"calls"| UKF_LIB
    NAVSAT_NODE -->|"calls"| NAVSAT_LIB

    FILTER_BASE -->|"utilizes"| UTIL_LIB

    EKF_NODE -->|"/odometry/filtered"| ODOMETRY
    EKF_NODE -->|"/pose/filtered"| POSE
    EKF_NODE -->|"broadcast"| TF2

    NAVSAT_NODE -->|"/odometry/filtered"| ODOMETRY
    NAVSAT_NODE -->|"broadcast"| TF2

    NAVSAT_NODE -->|offers| FROMLL
    NAVSAT_NODE -->|offers| TOLL
    NAVSAT_NODE -->|offers| SETDATUM
    NAVSAT_NODE -->|offers| GETSTATE

    %% Parameter injection
    EKF_YAML --> EKF_NODE
    UKF_YAML --> UKF_NODE
    NAVSAT_YAML --> NAVSAT_NODE
    DUAL_EXAMPLE_YAML --> NAVSAT_NODE

    %% Listener to filter nodes
    LISTENER_NODE -->|"forwards sensor data"| EKF_NODE
    LISTENER_NODE -->|"forwards sensor data"| UKF_NODE

    %% Launch triggers nodes
    EKF_LAUNCH --> EKF_NODE
    UKF_LAUNCH --> UKF_NODE
    NAVSAT_LAUNCH --> NAVSAT_NODE
    DUAL_LAUNCH --> NAVSAT_NODE

    %% Click Events for Filter Library
    click FILTER_BASE "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/include/robot_localization/filter_base.hpp"
    click FILTER_BASE "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/src/filter_base.cpp"
    click EKF_LIB "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/include/robot_localization/ekf.hpp"
    click EKF_LIB "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/src/ekf.cpp"
    click UKF_LIB "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/include/robot_localization/ukf.hpp"
    click UKF_LIB "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/src/ukf.cpp"
    click NAVSAT_LIB "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/include/robot_localization/navsat_transform.hpp"
    click NAVSAT_LIB "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/src/navsat_transform.cpp"
    click UTIL_LIB "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/include/robot_localization/filter_utilities.hpp"
    click UTIL_LIB "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/src/filter_utilities.cpp"

    %% Click Events for ROS Node Wrappers
    click EKF_NODE "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/src/ekf_node.cpp"
    click UKF_NODE "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/src/ukf_node.cpp"
    click NAVSAT_NODE "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/src/navsat_transform_node.cpp"
    click LISTENER_NODE "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/src/robot_localization_listener_node.cpp"

    %% Click Events for Parameter Server
    click EKF_YAML "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/params/ekf.yaml"
    click UKF_YAML "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/params/ukf.yaml"
    click NAVSAT_YAML "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/params/navsat_transform.yaml"
    click DUAL_EXAMPLE_YAML "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/params/dual_ekf_navsat_example.yaml"

    %% Click Events for Services
    click FROMLL "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/srv/FromLL.srv"
    click TOLL "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/srv/ToLL.srv"
    click GETSTATE "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/srv/GetState.srv"
    click SETDATUM "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/srv/SetDatum.srv"

    %% Click Events for Launch Files
    click EKF_LAUNCH "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/launch/ekf.launch.py"
    click UKF_LAUNCH "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/launch/ukf.launch.py"
    click NAVSAT_LAUNCH "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/launch/navsat_transform.launch.py"
    click DUAL_LAUNCH "https://github.com/cra-ros-pkg/robot_localization/blob/rolling-devel/launch/dual_ekf_navsat_example.launch.py"

    %% Styles
    classDef rosnode fill:#cce5ff,stroke:#004085,color:#004085;
    classDef library fill:#d4edda,stroke:#155724,color:#155724;
    classDef config fill:#fff3cd,stroke:#856404,color:#856404,stroke-dasharray: 5 5;
    classDef topic fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef service fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef infra fill:#d1ecf1,stroke:#0c5460,color:#0c5460,stroke-dasharray: 5 5;
```
