How atsushisakai/pythonrobotics works
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 Path Planning · PathTracking Path Tracking · InvertedPendulum Pendulum Control · SLAM SLAM
Components 18
Perception
Mapping, localization, and SLAM algorithms for estimating state from sensed data.
- Localization · Pose-estimation examples using histogram, particle, and Kalman-filter variants.
Localization - Mapping · Occupancy-grid, point-cloud, and feature-based mapping examples.
Mapping - SLAM · 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 · Large family of planners and trajectory generators, from grid search to sampling and lattice methods.
PathPlanning - Search Planners · Grid-based and heuristic planners such as BFS, DFS, Dijkstra, A*, D*, and Theta*.
- Sampling Planners · RRT, PRM, and related random or informed sampling planners.
- Vehicle Planners · Dubins, Reeds-Shepp, Hybrid A*, lattice, Frenet, LQR, MPC, and time-aware planning.
- Spline Utils · Reusable curve and path primitives used to smooth or parameterize plans.
Control
Path tracking, arm, aerial, bipedal, and pendulum control examples.
- Path Tracking · Controllers that track planned paths or references, including Stanley, pure pursuit, LQR, MPC, and CGMRES.
PathTracking - Mission Planning · Behavior-tree and state-machine orchestration above low-level motion behaviors.
MissionPlanning - Arm Navigation · Inverse kinematics, point-to-point control, and obstacle avoidance for planar and 3D arms.
ArmNavigation - Aerial Navigation · Quadrotor trajectory following and rocket landing examples.
AerialNavigation - Bipedal · Footstep planning using an inverted-pendulum model.
Bipedal - Pendulum Control · LQR and MPC examples for the inverted pendulum benchmark.
InvertedPendulum
Support
Shared utilities, documentation, tests, and CI surface around the cookbook.
- PythonRobotics · Repository of mostly independent robotics algorithm demonstrations organized by domain.
- Docs · Tutorial and module documentation that organizes and explains the examples.
docs - Tests · Per-module coverage for algorithms, utilities, and style/type checks.
tests - Utils · Common angle and plotting helpers reused across examples.
utils
Connections 26
- 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.