# orocos/orocos_kinematics_dynamics architecture

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

- Interactive diagram: https://gitdiagram.com/orocos/orocos_kinematics_dynamics
- Repository: https://github.com/orocos/orocos_kinematics_dynamics

## Overview

##### Project type and purpose
- This is a domain-specific library project, not a client/server or full-stack app.
- The core is a RealTime-capable C++ kinematics and dynamics library (`orocos_kdl`), complemented by Python bindings (`python_orocos_kdl`).
- It targets robotics applications (ROS/catkin integration), providing forward/inverse kinematic solvers, motion representations, trajectory planning, and utilities.

##### File structure
- Top level:
- `.github/`, CI and Dependabot configs
- `CHANGELOG.md`, `README.md`
- `orocos_kdl/`: C++ core library
- `python_orocos_kdl/`: Python bindings via Pybind11
- orocos_kdl:
- `CMakeLists.txt` + `cmake/` modules → build configuration, dependency checks (Eigen3, PkgConfig)
- `src/` → core namespaces, modules for chains, frames, jacobians, solvers, trajectories, utilities
- `models/`, `examples/` → demonstration code
- `doc/` → Doxygen and LaTeX user manual
- `tests/` → unit tests group by functionality
- `debian/`, packaging manifests → Debian and ROS packaging
- python_orocos_kdl:
- `CMakeLists.txt`, `pybind11/` → binding configuration
- `PyKDL/` → C++ wrapper code mapping core API to Python
- `doc/`, `tests/` → Sphinx docs and pytest suites
- `package.xml`, `rosdoc.yaml` → ROS integration

##### Key README insights
- Emphasizes the importance of matching C++ and Python versions
- Recommends ROS/catkin installation
- Clarifies there will be no ROS Noetic release

##### Main components
a. C++ Core Library (`orocos_kdl`)
- Modules: Chain/Multi-body structures, Solvers (FK, IK, dynamics), Path & Trajectory, Frames & Transforms, Utilities (SVD, inertia)
- Build system: CMake + custom `cmake/Find*.cmake` scripts
- Packaging targets: Debian, ROS/catkin
b. Python Bindings (`python_orocos_kdl`)
- Pybind11 layer (`pybind11/`)
- Wrapper code (`PyKDL/`)
- Sphinx documentation
- Python test harness
c. External dependencies
- Eigen3 linear algebra, STL
- PkgConfig
- (Optional) ROS/catkin
d. Supporting artifacts
- Examples & Models (C++, MATLAB)
- Documentation (Doxygen, LaTeX, Sphinx)
- CI & Release (GitHub Actions, Dependabot)

##### Relationships and interactions
- The build pipeline (CMake) pulls in external libs (Eigen, PkgConfig), configures/compiles the core.
- The Python build invokes CMake, uses Pybind11 to wrap C++ symbols.
- At runtime: Python user calls functions → PyKDL layer → C++ core API → internal modules compute kinematics/dynamics → results flow back up.
- Examples link directly against the C++ core; ROS nodes or catkin packages may consume both libraries.
- Tests validate each module in isolation (unit tests) and cross-language integration (Python tests).

##### Architectural patterns and design principles
- Modular monolith: clear separation by functionality (chains, solvers, paths, utilities).
- Layered abstraction:
- Low-level math/utility → core algorithms → user APIs → Python wrapper/ROS interface → end applications.
- Build-time dependency injection using CMake and pkg‐config.
- Extensibility via well-defined C++ headers and namespace organization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    ExternalDeps["External Dependencies:\nEigen3, PkgConfig, ROS/catkin"]:::external

    %% Build Configuration
    subgraph "Build Configuration" 
        direction TB
        CMakeLists["CMakeLists.txt"]:::build
        FindEigen3["FindEigen3.cmake"]:::build
        FindPkgConfig["FindPkgConfig.cmake"]:::build
    end

    %% Packaging Targets
    Packaging["Packaging Targets:\nDebian & ROS/catkin"]:::build

    %% C++ Core Library
    subgraph "C++ Core Library (orocos_kdl)" 
        direction TB
        ChainModule["Chain & Multi-body Structures"]:::cpp_core
        FKSolvers["Forward Kinematics Solvers"]:::cpp_core
        IKSolvers["Inverse Kinematics Solvers"]:::cpp_core
        DynamicsSolvers["Dynamics & Inertia Solvers"]:::cpp_core
        PathTraj["Path & Trajectory Planning"]:::cpp_core
        Frames["Frames & Transforms"]:::cpp_core
        Utilities["Utilities (SVD, LDL, misc)"]:::cpp_core
    end

    %% Supporting Artifacts
    subgraph "Supporting Artifacts"
        direction TB
        Models["Robot Models & DH definitions"]:::cpp_core
        Examples["Examples & MATLAB demos"]:::cpp_core
        CPPTests["C++ Unit Tests"]:::cpp_core
        CPPDoc["Documentation:\nDoxygen & LaTeX"]:::cpp_core
    end

    %% Python Bindings
    subgraph "Python Bindings (python_orocos_kdl)"
        direction TB
        PybindConfig["Pybind11 Configuration"]:::python
        PyKDL["C++-to-Python Wrapper (PyKDL)"]:::python
        PyDoc["Python Documentation\n(Sphinx)"]:::python
        PyTests["Python Test Suite (pytest)"]:::python
    end

    %% Consumers
    PythonUser["Python User"]:::python
    CppExamples["C++ Example Consumers"]:::cpp_core
    PythonTestsRunner["Integration Tests"]:::python

    %% Relationships
    ExternalDeps -->|used by| CMakeLists
    ExternalDeps -->|used by| FindEigen3
    ExternalDeps -->|used by| FindPkgConfig

    CMakeLists -->|configures| ChainModule
    CMakeLists -->|configures| FKSolvers
    CMakeLists -->|configures| IKSolvers
    CMakeLists -->|configures| DynamicsSolvers
    CMakeLists -->|configures| PathTraj
    CMakeLists -->|configures| Frames
    CMakeLists -->|configures| Utilities

    Packaging -->|packages| ChainModule
    Packaging -->|packages| FKSolvers
    Packaging -->|packages| IKSolvers

    ChainModule --> Models
    ChainModule --> Examples
    FKSolvers --> CPPTests
    IKSolvers --> CPPTests
    DynamicsSolvers --> CPPTests
    PathTraj --> CPPTests
    Frames --> CPPTests
    Utilities --> CPPTests

    CMakeLists -->|builds| PybindConfig
    PybindConfig -->|wraps API| PyKDL
    PyKDL -->|invokes| ChainModule
    PyKDL -->|invokes| FKSolvers
    PyKDL -->|invokes| IKSolvers
    PyKDL -->|invokes| DynamicsSolvers
    PyKDL -->|invokes| PathTraj
    PyKDL -->|invokes| Frames
    PyKDL -->|invokes| Utilities

    PyKDL --> PyTests
    PyKDL --> PyDoc

    PythonUser -->|calls| PyKDL
    CppExamples -->|link against| ChainModule
    CppExamples -->|link against| FKSolvers

    %% Click Events
    click ChainModule "https://github.com/orocos/orocos_kinematics_dynamics/blob/master/orocos_kdl/src/chain.cpp"
    click FKSolvers "https://github.com/orocos/orocos_kinematics_dynamics/blob/master/orocos_kdl/src/chainfksolverpos_recursive.cpp"
    click IKSolvers "https://github.com/orocos/orocos_kinematics_dynamics/blob/master/orocos_kdl/src/chainiksolvervel_pinv.hpp"
    click DynamicsSolvers "https://github.com/orocos/orocos_kinematics_dynamics/blob/master/orocos_kdl/src/chaindynparam.cpp"
    click PathTraj "https://github.com/orocos/orocos_kinematics_dynamics/blob/master/orocos_kdl/src/path.cpp"
    click Frames "https://github.com/orocos/orocos_kinematics_dynamics/blob/master/orocos_kdl/src/frames.cpp"
    click Utilities "https://github.com/orocos/orocos_kinematics_dynamics/tree/master/orocos_kdl/src/utilities/"
    click CMakeLists "https://github.com/orocos/orocos_kinematics_dynamics/blob/master/orocos_kdl/CMakeLists.txt"
    click FindEigen3 "https://github.com/orocos/orocos_kinematics_dynamics/blob/master/orocos_kdl/cmake/FindEigen3.cmake"
    click FindPkgConfig "https://github.com/orocos/orocos_kinematics_dynamics/blob/master/orocos_kdl/cmake/FindPkgConfig.cmake"
    click Packaging "https://github.com/orocos/orocos_kinematics_dynamics/tree/master/orocos_kdl/debian/"
    click CPPDoc "https://github.com/orocos/orocos_kinematics_dynamics/tree/master/orocos_kdl/doc/"
    click Examples "https://github.com/orocos/orocos_kinematics_dynamics/tree/master/orocos_kdl/examples/"
    click Models "https://github.com/orocos/orocos_kinematics_dynamics/tree/master/orocos_kdl/models/"
    click CPPTests "https://github.com/orocos/orocos_kinematics_dynamics/tree/master/orocos_kdl/tests/"
    click PybindConfig "https://github.com/orocos/orocos_kinematics_dynamics/tree/master/python_orocos_kdl/pybind11/"
    click PyKDL "https://github.com/orocos/orocos_kinematics_dynamics/tree/master/python_orocos_kdl/PyKDL/"
    click PyDoc "https://github.com/orocos/orocos_kinematics_dynamics/tree/master/python_orocos_kdl/doc/"
    click PyTests "https://github.com/orocos/orocos_kinematics_dynamics/tree/master/python_orocos_kdl/tests/"
    click ExternalDeps "https://github.com/orocos/orocos_kinematics_dynamics/blob/master/orocos_kdl/package.xml"
    click ExternalDeps "https://github.com/orocos/orocos_kinematics_dynamics/blob/master/python_orocos_kdl/package.xml"

    %% Styles
    classDef cpp_core fill:#D0E6FF,stroke:#4A90E2,color:#003366;
    classDef build fill:#E2F0D9,stroke:#6DA34D,color:#3D6C25;
    classDef python fill:#FFE6CC,stroke:#F5A623,color:#7A4000;
    classDef external fill:#F0F0F0,stroke:#999999,color:#666666;
```
