# atsushisakai/pythonrobotics architecture

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

- Interactive diagram: https://gitdiagram.com/atsushisakai/pythonrobotics
- Repository: https://github.com/atsushisakai/pythonrobotics

## Overview

1. This repository is a robotics algorithm cookbook, not a single application. The architecture is a set of mostly independent example programs grouped by robotics domain, plus a small amount of shared utility code, documentation, and tests. The primary boundary is the top-level domain folder: Localization, Mapping, SLAM, PathPlanning, PathTracking, ArmNavigation, AerialNavigation, Bipedal, MissionPlanning, and InvertedPendulum.

2. Most subsystems are self-contained demos. A typical module takes a simulated robot state, obstacle/map description, or sensor input, runs one algorithm, and then visualizes the result with Matplotlib. The runtime pattern is generally “scenario setup → algorithm computation → trajectory/estimate/path output → plotting/animation.”

3. The strongest internal reuse is in PathPlanning and PathTracking. PathPlanning contains many planners and trajectory generators, along with shared helpers for motion models, splines, heuristics, and vehicle geometry. PathTracking then consumes planned paths or reference trajectories and applies controllers such as Stanley, pure pursuit, LQR, MPC, and CGMRES. This creates a clear pipeline from planning to control.

4. Localization, Mapping, and SLAM form the perception side of the repo. Mapping modules build occupancy or feature maps from simulated range data or point clouds. Localization modules estimate pose from those maps or landmarks using histogram filters, particle filters, and Kalman-filter variants. SLAM modules combine both roles, estimating pose and map together, with ICP, EKF-SLAM, FastSLAM, and graph-based SLAM as separate implementations.

5. Many motion-planning algorithms are grouped by search model. Grid-based planners include BFS, DFS, Dijkstra, A*, D* and D* Lite. Sampling-based planners include RRT, RRT*, Informed RRT*, Batch Informed RRT*, PRM, and several car-specific variants such as Dubins and Reeds-Shepp. Hybrid and lattice-based planners bridge discrete search with vehicle kinematics, while time-based planners handle dynamic obstacles and safe intervals.

6. Several subpackages are reusable primitives rather than complete demos. Examples include PathPlanning/CubicSpline, BSplinePath, BezierPath, Catmull_RomSplinePath, DubinsPath, ReedsSheppPath, and utilities in utils/. These modules are typically imported by higher-level planners or trackers to generate smooth reference curves, interpolate trajectories, or compute geometry.

7. The repository also contains specialized robot domains outside mobile navigation. ArmNavigation covers inverse kinematics, point-to-point control, and obstacle avoidance for planar and 3D manipulators. AerialNavigation covers quadrotor trajectory following and rocket landing. Bipedal contains a planner for footstep modification with an inverted pendulum model. InvertedPendulum holds LQR and MPC controllers as control-theory examples.

8. MissionPlanning is a smaller orchestration layer with two behavior paradigms: behavior trees and state machines. These modules sit above low-level motion algorithms and model robot task logic rather than geometry or dynamics. The XML and case definitions indicate a task-execution layer that can select or sequence behaviors.

9. External inputs are minimal and mostly local to examples. Some planners and SLAM examples load sample data files such as lidar CSV, `.npy` obstacle/path arrays, `.csv` lookup tables, and a `.g2o` graph file. There is no central database or service dependency; data is embedded in example assets or generated procedurally inside each script.

10. The engineering surface around the algorithms is strong: Sphinx documentation under docs/, extensive per-module pytest coverage under tests/, and CI across Linux, macOS, and Windows via GitHub Actions plus CircleCI/AppVeyor. Code quality is enforced with mypy and ruff/pycodestyle-style checks. For an architecture diagram, the key picture is a documentation-driven monorepo of algorithm modules, with shared utilities at the bottom and many standalone demonstrations above them.

Main entry points: [`PathPlanning`](https://github.com/atsushisakai/pythonrobotics/tree/master/PathPlanning) (Path Planning), [`PathTracking`](https://github.com/atsushisakai/pythonrobotics/tree/master/PathTracking) (Path Tracking), [`InvertedPendulum`](https://github.com/atsushisakai/pythonrobotics/tree/master/InvertedPendulum) (Pendulum Control), [`SLAM`](https://github.com/atsushisakai/pythonrobotics/tree/master/SLAM) (SLAM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core_perception["Perception"]
  node_localization["Localization<br/>state estimation"]
  node_mapping["Mapping<br/>map building"]
  node_slam["SLAM<br/>simultaneous localization and mapping"]
end

subgraph group_core_planning["Planning"]
  node_path_planning["Path Planning<br/>motion planning"]
  node_planning_search["Search Planners<br/>graph search"]
  node_planning_sampling["Sampling Planners<br/>sampling-based planning"]
  node_planning_kinodynamic["Vehicle Planners<br/>kinodynamic planning"]
  node_planning_splines["Spline Utils<br/>trajectory primitives"]
end

subgraph group_core_control["Control"]
  node_path_tracking["Path Tracking<br/>trajectory control"]
  node_mission_planning["Mission Planning<br/>task logic"]
  node_arm_navigation["Arm Navigation<br/>manipulator control"]
  node_aerial_navigation["Aerial Navigation<br/>flight control"]
  node_bipedal["Bipedal<br/>legged planning"]
  node_inverted_pendulum["Pendulum Control<br/>control theory"]
end

subgraph group_support["Support"]
  node_root["PythonRobotics<br/>cookbook monorepo"]
  node_docs["Docs"]
  node_tests["Tests<br/>pytest suite"]
  node_utils["Utils<br/>shared helpers"]
end

node_root -->|"documents"| node_docs
node_root -->|"validates"| node_tests
node_root -->|"shares"| node_utils
node_root -->|"contains"| node_localization
node_root -->|"contains"| node_mapping
node_root -->|"contains"| node_slam
node_root -->|"contains"| node_path_planning
node_root -->|"contains"| node_path_tracking
node_root -->|"contains"| node_mission_planning
node_root -->|"contains"| node_arm_navigation
node_root -->|"contains"| node_aerial_navigation
node_root -->|"contains"| node_bipedal
node_root -->|"contains"| node_inverted_pendulum
node_mapping -->|"feeds map state"| node_slam
node_localization -->|"provides pose"| node_slam
node_path_planning -->|"includes"| node_planning_search
node_path_planning -->|"includes"| node_planning_sampling
node_path_planning -->|"includes"| node_planning_kinodynamic
node_path_planning -->|"uses"| node_planning_splines
node_planning_splines -->|"supplies reference"| node_path_tracking
node_path_planning -->|"hands off path"| node_path_tracking
node_path_tracking -->|"supports behaviors"| node_mission_planning
node_arm_navigation -->|"reuses planning"| node_path_planning
node_aerial_navigation -->|"uses trajectories"| node_path_planning
node_bipedal -->|"models dynamics"| node_inverted_pendulum
node_inverted_pendulum -->|"shares control ideas"| node_path_tracking

click node_docs "https://github.com/atsushisakai/pythonrobotics/tree/master/docs"
click node_tests "https://github.com/atsushisakai/pythonrobotics/tree/master/tests"
click node_utils "https://github.com/atsushisakai/pythonrobotics/tree/master/utils"
click node_localization "https://github.com/atsushisakai/pythonrobotics/tree/master/Localization"
click node_mapping "https://github.com/atsushisakai/pythonrobotics/tree/master/Mapping"
click node_slam "https://github.com/atsushisakai/pythonrobotics/tree/master/SLAM"
click node_path_planning "https://github.com/atsushisakai/pythonrobotics/tree/master/PathPlanning"
click node_path_tracking "https://github.com/atsushisakai/pythonrobotics/tree/master/PathTracking"
click node_mission_planning "https://github.com/atsushisakai/pythonrobotics/tree/master/MissionPlanning"
click node_arm_navigation "https://github.com/atsushisakai/pythonrobotics/tree/master/ArmNavigation"
click node_aerial_navigation "https://github.com/atsushisakai/pythonrobotics/tree/master/AerialNavigation"
click node_bipedal "https://github.com/atsushisakai/pythonrobotics/tree/master/Bipedal"
click node_inverted_pendulum "https://github.com/atsushisakai/pythonrobotics/tree/master/InvertedPendulum"

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_localization,node_mapping,node_slam toneBlue
class node_path_planning,node_planning_search,node_planning_sampling,node_planning_kinodynamic,node_planning_splines toneAmber
class node_path_tracking,node_mission_planning,node_arm_navigation,node_aerial_navigation,node_bipedal,node_inverted_pendulum toneMint
class node_root,node_docs,node_tests,node_utils toneRose
```

## Components

### Perception

Mapping, localization, and SLAM algorithms for estimating state from sensed data.

- [Localization](https://github.com/atsushisakai/pythonrobotics/tree/master/Localization): state estimation · Pose-estimation examples using histogram, particle, and Kalman-filter variants. · `Localization`
- [Mapping](https://github.com/atsushisakai/pythonrobotics/tree/master/Mapping): map building · Occupancy-grid, point-cloud, and feature-based mapping examples. · `Mapping`
- [SLAM](https://github.com/atsushisakai/pythonrobotics/tree/master/SLAM): simultaneous localization and mapping · Algorithms that estimate pose and map together, including ICP, EKF-SLAM, FastSLAM, and graph SLAM. · `SLAM`

### Planning

Path planning and trajectory generation examples, from search to kinodynamic planners.

- [Path Planning](https://github.com/atsushisakai/pythonrobotics/tree/master/PathPlanning): motion planning · Large family of planners and trajectory generators, from grid search to sampling and lattice methods. · `PathPlanning`
- **Search Planners**: graph search · Grid-based and heuristic planners such as BFS, DFS, Dijkstra, A*, D*, and Theta*.
- **Sampling Planners**: sampling-based planning · RRT, PRM, and related random or informed sampling planners.
- **Vehicle Planners**: kinodynamic planning · Dubins, Reeds-Shepp, Hybrid A*, lattice, Frenet, LQR, MPC, and time-aware planning.
- **Spline Utils**: trajectory primitives · Reusable curve and path primitives used to smooth or parameterize plans.

### Control

Path tracking, arm, aerial, bipedal, and pendulum control examples.

- [Path Tracking](https://github.com/atsushisakai/pythonrobotics/tree/master/PathTracking): trajectory control · Controllers that track planned paths or references, including Stanley, pure pursuit, LQR, MPC, and CGMRES. · `PathTracking`
- [Mission Planning](https://github.com/atsushisakai/pythonrobotics/tree/master/MissionPlanning): task logic · Behavior-tree and state-machine orchestration above low-level motion behaviors. · `MissionPlanning`
- [Arm Navigation](https://github.com/atsushisakai/pythonrobotics/tree/master/ArmNavigation): manipulator control · Inverse kinematics, point-to-point control, and obstacle avoidance for planar and 3D arms. · `ArmNavigation`
- [Aerial Navigation](https://github.com/atsushisakai/pythonrobotics/tree/master/AerialNavigation): flight control · Quadrotor trajectory following and rocket landing examples. · `AerialNavigation`
- [Bipedal](https://github.com/atsushisakai/pythonrobotics/tree/master/Bipedal): legged planning · Footstep planning using an inverted-pendulum model. · `Bipedal`
- [Pendulum Control](https://github.com/atsushisakai/pythonrobotics/tree/master/InvertedPendulum): control theory · LQR and MPC examples for the inverted pendulum benchmark. · `InvertedPendulum`

### Support

Shared utilities, documentation, tests, and CI surface around the cookbook.

- **PythonRobotics**: cookbook monorepo · Repository of mostly independent robotics algorithm demonstrations organized by domain.
- [Docs](https://github.com/atsushisakai/pythonrobotics/tree/master/docs): Sphinx docs · Tutorial and module documentation that organizes and explains the examples. · `docs`
- [Tests](https://github.com/atsushisakai/pythonrobotics/tree/master/tests): pytest suite · Per-module coverage for algorithms, utilities, and style/type checks. · `tests`
- [Utils](https://github.com/atsushisakai/pythonrobotics/tree/master/utils): shared helpers · Common angle and plotting helpers reused across examples. · `utils`

## Connections

- PythonRobotics → Docs: documents · Repository documentation describes the example modules and how to run them.
- PythonRobotics → Tests: validates · The test suite covers the cookbook examples and shared utilities.
- PythonRobotics → Utils: shares · Common helpers are reused across many modules.
- PythonRobotics → Localization: contains · Top-level perception domain.
- PythonRobotics → Mapping: contains · Top-level perception domain.
- PythonRobotics → SLAM: contains · Top-level perception domain.
- PythonRobotics → Path Planning: contains · Top-level planning domain.
- PythonRobotics → Path Tracking: contains · Top-level tracking domain.
- PythonRobotics → Mission Planning: contains · Top-level task-execution domain.
- PythonRobotics → Arm Navigation: contains · Top-level manipulator domain.
- PythonRobotics → Aerial Navigation: contains · Top-level aerial domain.
- PythonRobotics → Bipedal: contains · Top-level legged domain.
- PythonRobotics → Pendulum Control: contains · Top-level control example domain.
- Mapping → SLAM: feeds map state · Mapping outputs are reused by SLAM formulations in the perception stack.
- Localization → SLAM: provides pose · Localization methods mirror the pose-estimation half of SLAM.
- Path Planning → Search Planners: includes · Search-based planners form one major planner family.
- Path Planning → Sampling Planners: includes · Sampling-based planners form one major planner family.
- Path Planning → Vehicle Planners: includes · Kinodynamic and vehicle-aware planners bridge search with dynamics.
- Path Planning → Spline Utils: uses · Spline and curve primitives are reused to build smooth reference paths.
- Spline Utils → Path Tracking: supplies reference · Tracking controllers consume planned or smoothed trajectories.
- Path Planning → Path Tracking: hands off path · Planned paths are typically consumed by tracking controllers.
- Path Tracking → Mission Planning: supports behaviors · High-level behavior layers can invoke lower-level motion control.
- Arm Navigation → Path Planning: reuses planning · Some arm examples use search or RRT-style planners for obstacle avoidance.
- Aerial Navigation → Path Planning: uses trajectories · Flight examples follow generated paths and reference trajectories.
- Bipedal → Pendulum Control: models dynamics · Bipedal planning is based on an inverted pendulum abstraction.
- Pendulum Control → Path Tracking: shares control ideas · Control-oriented examples overlap with trajectory regulation concepts.
