# brukg/pose-ekf-slam architecture

> Architecture diagram of the GitHub repository brukg/pose-ekf-slam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brukg/pose-ekf-slam
- Repository: https://github.com/brukg/pose-ekf-slam

## Overview

##### Project type and purpose
- This is a ROS (Robot Operating System) package (C++ + Python) implementing an Extended Kalman Filter for pose-SLAM using odometry and LiDAR.
- Purpose: subscribe to odom and laser scans, run EKF-SLAM backend, publish estimated pose and map data.

##### File structure
Top level:
– CMakeLists.txt & package.xml: ROS build and meta-information
– launch/pekf_slam.launch.py: ROS2 launch script (brings up nodes, parameter server)
– params/param.yaml: EKF and topic parameters
– include/pekf_slam/*.hpp & src/*.cpp:
- pekf_slam.hpp / utils.hpp – core EKF logic and helpers
- pekf_slam.cpp – core algorithm implementation
- pekf_slam_node.cpp – ROS node wrapper (subscriptions, publishers)
– scripts/scan2pc.py: Python helper converting LaserScan → PointCloud2

##### README for additional insights
- Confirms odom + lidar inputs, EKF approach, and simulation results.

##### Main components
A. ROS Master / ROS Domain
– Manages node registration, parameter server (loads params/param.yaml)
B. Sensor interfaces
– /odom topic publisher (robot base odometry)
– /scan topic publisher (LiDAR scan)
– scan2pc.py node (optional helper)
C. pekf_slam_node
– Subscribes to /odom and /scan (or /pointcloud if using scan2pc)
– Loads parameters from ROS param server
– Calls core EKF module
– Publishes estimated pose (e.g. /ekf_pose) and map updates (if implemented)
– Broadcasts TF transforms (map → odom → base_link)
D. Core EKF library
– State prediction & update, covariance propagation
– Utility functions (data conversions, noise models)
E. Visualization / Storage (external)
– RViz or custom plot subscriber
– Optional file logging or bag recording

##### Relationships & interactions
- Sensors → Topics → pekf_slam_node → EKF module → Publishers → Visualization
- Parameter server feeds config to node at startup
- scan2pc.py (Python script) transforms LaserScan → PointCloud2 if needed—feeds into the same or parallel data stream

##### Architectural patterns & design principles
– ROS pub/sub decoupling: each component is a node with well-defined topics
– Separation of concerns: core SLAM algorithm (pekf_slam.hpp/.cpp) is independent of ROS
– Parameterization via YAML and launch file for flexible tuning
– Modular helper scripts (scan2pc.py) for preprocessing

##### Technologies & frameworks
- ROS2 (implied by .launch.py)
- C++17 for performance-critical EKF
- Python3 for quick prototyping (scan2pc)
- CMake build system & ament (or catkin)
- YAML for configuration

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Metadata
    subgraph "Build & Metadata"
        CM["CMakeLists.txt"]:::ext
        PKG["package.xml"]:::ext
        README["README.md"]:::ext
    end

    %% ROS Runtime
    subgraph "ROS Runtime"
        RM["ROS Master / Domain"]:::node
        LAUNCH["Launch Script<br/>(pekf_slam.launch.py)"]:::node
        PARAMFILE["param.yaml"]:::util
        PS["Parameter Server"]:::node
        ODOM["Odom Publisher<br/>(sensor_msgs/Odometry)"]:::sensor
        LIDAR["LiDAR Publisher<br/>(sensor_msgs/LaserScan)"]:::sensor
        SCAN2PC["scan2pc.py"]:::node
    end

    %% SLAM Core
    subgraph "SLAM Core"
        NS["pekf_slam_node"]:::node
        EKF["Core EKF Library"]:::core
        UTIL["Utils Module"]:::util
    end

    %% Visualization & Storage
    subgraph "Visualization & Storage"
        RVIZ["RViz / Plot Subscriber"]:::ext
        BAG["Bag Recording / Logging"]:::ext
    end

    %% Data Flows & Relationships
    RM --> PS
    LAUNCH --> RM
    LAUNCH --> PS
    PS --> PARAMFILE
    PARAMFILE --> PS
    PS --> NS
    ODOM -->|"/odom"| NS
    LIDAR -->|"/scan"| NS
    LIDAR -->|"/scan"| SCAN2PC
    SCAN2PC -->|"/pointcloud"| NS
    NS -->|"calls EKF"| EKF
    EKF --> UTIL
    NS -->|"/ekf_pose, map"| RVIZ
    NS -->|"/ekf_pose"| BAG
    NS -->|"TF Broadcasts"| RVIZ

    %% Click Events
    click CM "https://github.com/brukg/pose-ekf-slam/blob/main/CMakeLists.txt"
    click PKG "https://github.com/brukg/pose-ekf-slam/blob/main/package.xml"
    click README "https://github.com/brukg/pose-ekf-slam/blob/main/README.md"
    click LAUNCH "https://github.com/brukg/pose-ekf-slam/blob/main/launch/pekf_slam.launch.py"
    click PARAMFILE "https://github.com/brukg/pose-ekf-slam/blob/main/params/param.yaml"
    click SCAN2PC "https://github.com/brukg/pose-ekf-slam/blob/main/scripts/scan2pc.py"
    click NS "https://github.com/brukg/pose-ekf-slam/blob/main/src/pekf_slam_node.cpp"
    click NS "https://github.com/brukg/pose-ekf-slam/blob/main/include/pekf_slam/pekf_slam_node.hpp"
    click EKF "https://github.com/brukg/pose-ekf-slam/blob/main/src/pekf_slam.cpp"
    click EKF "https://github.com/brukg/pose-ekf-slam/blob/main/include/pekf_slam/pekf_slam.hpp"
    click UTIL "https://github.com/brukg/pose-ekf-slam/blob/main/include/pekf_slam/utils.hpp"

    %% Styles
    classDef node fill:#ADD8E6,stroke:#000;
    classDef sensor fill:#FFA500,stroke:#000;
    classDef core fill:#90EE90,stroke:#000;
    classDef util fill:#DA70D6,stroke:#000;
    classDef ext fill:#D3D3D3,stroke:#000;
```
