# px4/px4-matrix architecture

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

- Interactive diagram: https://gitdiagram.com/px4/px4-matrix
- Repository: https://github.com/px4/px4-matrix

## Overview

##### Project Type & Purpose
- This is a header-only template-based matrix library written in C++.
- Its primary goal is to provide efficient compile-time size checking and perform various matrix math operations, conversion routines (Euler angles, DCM, Quaternion, Axis Angle), filtering, and integration.
- It is not a full-stack application but rather a well-structured mathematical library designed for embedded or performance-critical environments (e.g., as used within the PX4 Autopilot).

##### Key Components to Highlight
a. Core Math Components:
- Fundamental types: Scalar, Vector, and Matrix (including specialized forms like SquareMatrix, Vector2, Vector3).
- Conversion and Representation: Euler, Dcm, Quaternion, AxisAngle.
b. Auxiliary Math Utilities:
- Filtering: Provided via matrix/filter.hpp (e.g., kalman_correct).
- Integration: Provided via matrix/integration.hpp (e.g., integrate_rk4 function).
- Additional mathematical routines and helper functions in math.hpp, helper_functions.hpp, etc.
c. Testing & Examples:
d. Build & Configuration:
- CMake configuration files (CMakeLists.txt and test/CMakeLists.txt) that drive the build and test processes.
- CI workflows in the .github directory indicating automated testing.

##### Architectural Patterns and Design Principles
- That the library employs compile-time constraints (template-based design) ensuring safety and efficiency.
- Point out that the separation between fundamental math operations, conversion routines, and auxiliary algorithms follows single responsibility and clean modular separation.
- Demonstrate that the design facilitates reusability (e.g., the same Matrix class is reused within filtering and integration routines).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Math Components
    subgraph "Core Math Components"
        A1["Matrix"]
        A2["SquareMatrix"]
        A3["Vector"]
        A4["Vector2"]
        A5["Vector3"]
        A6["Scalar"]
    end

    %% Representations & Conversions
    subgraph "Representations & Conversions"
        B1["Euler"]
        B2["Quaternion"]
        B3["Dcm"]
        B4["Axis Angle"]
    end

    %% Auxiliary Utilities
    subgraph "Auxiliary Utilities"
        C1["Filtering"]
        C2["Integration"]
        C3["Math Utils"]
        C4["Helper Functions"]
    end

    %% Testing & Documentation
    subgraph "Testing & Documentation"
        D1["Test Suite"]
        D2["Documentation"]
    end

    %% Build & CI Configuration
    subgraph "Build & CI Configuration"
        E1["CMake Configuration"]
        E2["CI Workflows"]
    end

    %% Relationships - Data Flow & Dependencies
    A1 -->|"conversion"| B1
    B1 <-->|"conversion"| B2
    B2 <-->|"conversion"| B3
    A1 -->|"uses"| C1
    A1 -->|"uses"| C2
    D1 -->|"validates"| A1
    D1 -->|"validates"| B1
    D1 -->|"validates"| C1
    E1 -->|"builds"| D1
    E2 -->|"triggers"| D1

    %% Click Events for Core Math Components
    click A1 "https://github.com/px4/px4-matrix/blob/master/matrix/Matrix.hpp"
    click A2 "https://github.com/px4/px4-matrix/blob/master/matrix/SquareMatrix.hpp"
    click A3 "https://github.com/px4/px4-matrix/blob/master/matrix/Vector.hpp"
    click A4 "https://github.com/px4/px4-matrix/blob/master/matrix/Vector2.hpp"
    click A5 "https://github.com/px4/px4-matrix/blob/master/matrix/Vector3.hpp"
    click A6 "https://github.com/px4/px4-matrix/blob/master/matrix/Scalar.hpp"

    %% Click Events for Representations & Conversions
    click B1 "https://github.com/px4/px4-matrix/blob/master/matrix/Euler.hpp"
    click B2 "https://github.com/px4/px4-matrix/blob/master/matrix/Quaternion.hpp"
    click B3 "https://github.com/px4/px4-matrix/blob/master/matrix/Dcm.hpp"
    click B4 "https://github.com/px4/px4-matrix/blob/master/matrix/AxisAngle.hpp"

    %% Click Events for Auxiliary Utilities
    click C1 "https://github.com/px4/px4-matrix/blob/master/matrix/filter.hpp"
    click C2 "https://github.com/px4/px4-matrix/blob/master/matrix/integration.hpp"
    click C3 "https://github.com/px4/px4-matrix/blob/master/matrix/math.hpp"
    click C4 "https://github.com/px4/px4-matrix/blob/master/matrix/helper_functions.hpp"

    %% Click Events for Testing & Documentation
    click D1 "https://github.com/px4/px4-matrix/tree/master/test"
    click D2 "https://github.com/px4/px4-matrix/blob/master/doc/euler_gimbal_lock.ipynb"

    %% Click Events for Build & CI Configuration
    click E1 "https://github.com/px4/px4-matrix/blob/master/CMakeLists.txt"
    click E2 "https://github.com/px4/px4-matrix/blob/master/.github/workflows/test.yml"

    %% Class Definitions for Color Coding
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef conversion fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef utility fill:#FFFACD,stroke:#000,stroke-width:1px;
    classDef testing fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef build fill:#D3D3D3,stroke:#000,stroke-width:1px;

    class A1,A2,A3,A4,A5,A6 core;
    class B1,B2,B3,B4 conversion;
    class C1,C2,C3,C4 utility;
    class D1,D2 testing;
    class E1,E2 build;
```
