# jakobthumm/sara-shield architecture

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

- Interactive diagram: https://gitdiagram.com/jakobthumm/sara-shield
- Repository: https://github.com/jakobthumm/sara-shield

## Overview

1. **Repository purpose**
   - SaRA-shield is a C++ safety library for human-robot interaction.
   - Its core job is to estimate reachable sets for the human and robot, then decide whether the robot trajectory must be slowed or stopped before a collision becomes possible.

2. **Top-level architectural style**
   - The repo is primarily a **native C++ library** built with CMake.
   - It also exposes a **Python binding layer** through pybind11, so the same safety logic can be used from Python-based workflows and tests.

3. **Core safety orchestration**
   - The central module is `safety_shield`, which appears to coordinate the end-to-end safety decision flow.
   - This layer likely consumes motion/measurement inputs, invokes reachability and verification logic, and outputs a safety-constrained action such as “continue”, “slow down”, or “stop”.

4. **Motion and trajectory subsystem**
   - `motion`, `path`, `long_term_traj`, `trajectory_utils`, and `long_term_traj` represent the robot-side motion model and planned trajectory handling.
   - These pieces turn robot commands or planned paths into forms that can be analyzed over time for safety guarantees.

5. **Human and robot reachability subsystem**
   - `human_reach` and `robot_reach` are the main analysis modules for reachable-set computation.
   - The README states these rely on the external **SaRA** submodule, which is the key reachability engine used to model future human and robot states.

6. **State estimation and measurement handling**
   - `measurement_handler` and `kalman_filter` form the sensing/estimation boundary.
   - This layer converts raw or noisy observations into a filtered state estimate that can feed the reachability analysis, especially for dynamic human motion.

7. **Verification and safety decision logic**
   - `verify`, `verify_iso`, and `verification_utils` implement the collision-risk evaluation step.
   - This is where human and robot reachable sets are compared and a safety condition is derived, likely including geometric or temporal separation checks.

8. **Configuration and scenario data**
   - The `config/` directory contains YAML files for multiple robot platforms and human-reach scenarios.
   - These configs define robot parameters, trajectory parameters, and test scenarios, which makes the library adaptable across platforms like iiwa, Panda, Sawyer, UR5e, Jaco, Kinova, Schunk, and others.

9. **External dependencies and boundaries**
   - The repo vendors several third-party components under `external/`: **SaRA**, **LongTermPlanner**, **pybind11**, **spdlog**, and **yaml-cpp**.
   - This means the safety logic is not standalone: it depends on external reachability and planning libraries plus YAML parsing and logging infrastructure.

10. **Debug and visualization tooling**
   - Several `src/*debug*.cc` programs suggest standalone executables for scenario exploration and troubleshooting.
   - `rviz_marker.h` indicates support for visualization markers, likely for inspecting safety states in a robotics visualization workflow.

11. **Python integration boundary**
   - `bindings/safety_shield_bindings.cpp` is the bridge from C++ into Python.
   - The Python tests in `tests/bindings/` exercise this API, which implies the binding layer mirrors core library concepts rather than reimplementing them.

12. **Validation strategy**
   - The repo has both C++ tests under `tests/src/` and Python tests under `tests/bindings/`.
   - This dual test layout suggests the maintainers validate both the native safety algorithms and the Python-facing API contract.

13. **Supporting scripts and asset generation**
   - `scripts/urdf_capsule_generation.py` is a support tool for producing collision geometry from robot descriptions.
   - That points to a geometry-preprocessing step in the workflow, likely used to approximate robot links for reachability or collision checking.

14. **How the data flows end-to-end**
   - In typical use, configuration and robot parameters define the scenario, measurements are filtered, reachable sets are computed for human and robot, the verification layer checks for potential collision, and the `safety_shield` orchestrator turns that into a runtime safety action.

Main entry points: [`safety_shield/include/safety_shield/safety_shield.h`](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/safety_shield.h) (Safety shield), [`safety_shield/tests/src`](https://github.com/jakobthumm/sara-shield/tree/main/safety_shield/tests/src) (C++ tests), [`safety_shield/bindings/safety_shield_bindings.cpp`](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/bindings/safety_shield_bindings.cpp) (Python API), [`safety_shield/include/safety_shield/motion.h`](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/motion.h) (Motion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_safety_shield["Safety shield<br/>orchestrator<br/>[safety_shield.h]"]
  node_motion["Motion<br/>robot kinematics<br/>[motion.h]"]
  node_path["Path<br/>[path.h]"]
  node_long_term_traj["Long-term traj<br/>trajectory model<br/>[long_term_traj.h]"]
  node_trajectory_utils["Traj utils<br/>trajectory helpers<br/>[trajectory_utils.h]"]
  node_measurement_handler["Measurements<br/>sensor boundary"]
  node_kalman_filter["Kalman filter<br/>state estimator<br/>[kalman_filter.h]"]
  node_human_reach["Human reach<br/>reachability<br/>[human_reach.h]"]
  node_robot_reach["Robot reach<br/>reachability<br/>[robot_reach.h]"]
  node_verify["Verify<br/>risk check<br/>[verify.h]"]
  node_verify_iso["ISO verify<br/>safety rule<br/>[verify_iso.h]"]
  node_verification_utils["Verify utils<br/>verification helpers"]
end

subgraph group_interop["Interop"]
  node_bindings["Python API<br/>pybind11 bridge"]
end

subgraph group_data["Scenario data"]
  node_config_utils["Config utils<br/>config loader<br/>[config_utils.h]"]
end

subgraph group_ext["External deps"]
  node_sa_ra["SaRA<br/>external reachability engine"]
  node_ltp["LongTermPlanner<br/>external planner"]
  node_yaml_cpp["yaml-cpp<br/>external parser"]
  node_spdlog["spdlog<br/>external logging"]
end

subgraph group_tests["Tests"]
  node_cpp_tests["C++ tests<br/>native tests"]
  node_py_tests["Python tests<br/>binding tests"]
end

subgraph group_tools["Tooling"]
  node_debug_tools["Debug tools<br/>executables<br/>[debug.cc]"]
  node_urdf_capsule_generation["Capsule gen<br/>geometry script"]
end

node_safety_shield -->|"uses"| node_motion
node_safety_shield -->|"plans"| node_long_term_traj
node_safety_shield -->|"consumes"| node_measurement_handler
node_safety_shield -->|"checks"| node_human_reach
node_safety_shield -->|"checks"| node_robot_reach
node_safety_shield -->|"decides"| node_verify
node_safety_shield -.->|"optionally uses"| node_verify_iso
node_motion -->|"builds on"| node_path
node_motion -->|"uses"| node_trajectory_utils
node_long_term_traj -->|"extends"| node_path
node_long_term_traj -->|"integrates"| node_ltp
node_measurement_handler -->|"filters"| node_kalman_filter
node_kalman_filter -.->|"parametrized by"| node_config_utils
node_human_reach -->|"depends on"| node_sa_ra
node_robot_reach -->|"depends on"| node_sa_ra
node_verify -->|"uses"| node_verification_utils
node_verify_iso -->|"uses"| node_verification_utils
node_config_utils -->|"parses with"| node_yaml_cpp
node_config_utils -.->|"logs with"| node_spdlog
node_bindings -->|"exposes"| node_safety_shield
node_bindings -->|"exposes"| node_motion
node_bindings -->|"exposes"| node_long_term_traj
node_bindings -.->|"validated by"| node_cpp_tests
node_cpp_tests -.->|"covers"| node_safety_shield
node_cpp_tests -.->|"covers"| node_human_reach
node_cpp_tests -.->|"covers"| node_robot_reach
node_cpp_tests -.->|"covers"| node_verify
node_py_tests -.->|"covers"| node_bindings
node_debug_tools -.->|"exercise"| node_safety_shield
node_urdf_capsule_generation -.->|"supports"| node_robot_reach

click node_safety_shield "https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/safety_shield.h"
click node_motion "https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/motion.h"
click node_path "https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/path.h"
click node_long_term_traj "https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/long_term_traj.h"
click node_trajectory_utils "https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/trajectory_utils.h"
click node_measurement_handler "https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/measurement_handler.h"
click node_kalman_filter "https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/kalman_filter.h"
click node_human_reach "https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/human_reach.h"
click node_robot_reach "https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/robot_reach.h"
click node_verify "https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/verify.h"
click node_verify_iso "https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/verify_iso.h"
click node_verification_utils "https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/verification_utils.h"
click node_config_utils "https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/config_utils.h"
click node_bindings "https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/bindings/safety_shield_bindings.cpp"
click node_sa_ra "https://github.com/jakobthumm/sara-shield/tree/main/safety_shield/external/SaRA"
click node_ltp "https://github.com/jakobthumm/sara-shield/tree/main/safety_shield/external/LongTermPlanner"
click node_yaml_cpp "https://github.com/jakobthumm/sara-shield/tree/main/safety_shield/external/yaml-cpp"
click node_spdlog "https://github.com/jakobthumm/sara-shield/tree/main/safety_shield/external/spdlog"
click node_cpp_tests "https://github.com/jakobthumm/sara-shield/tree/main/safety_shield/tests/src"
click node_py_tests "https://github.com/jakobthumm/sara-shield/tree/main/safety_shield/tests/bindings"
click node_debug_tools "https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/src/debug.cc"
click node_urdf_capsule_generation "https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/scripts/urdf_capsule_generation.py"

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_safety_shield,node_motion,node_path,node_long_term_traj,node_trajectory_utils,node_measurement_handler,node_kalman_filter,node_human_reach,node_robot_reach,node_verify,node_verify_iso,node_verification_utils toneBlue
class node_bindings toneAmber
class node_config_utils toneMint
class node_sa_ra,node_ltp,node_yaml_cpp,node_spdlog toneRose
class node_cpp_tests,node_py_tests toneIndigo
class node_debug_tools,node_urdf_capsule_generation toneTeal
```

## Components

### Core library

Native C++ safety shielding and analysis components.

- [Safety shield](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/safety_shield.h): orchestrator · Top-level runtime coordinator that turns analysis into safety actions. · `safety_shield/include/safety_shield/safety_shield.h`
- [Motion](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/motion.h): robot kinematics · Robot motion representation and state evolution helpers. · `safety_shield/include/safety_shield/motion.h`
- [Path](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/path.h): trajectory path · Planned path representation used by motion and trajectory logic. · `safety_shield/include/safety_shield/path.h`
- [Long-term traj](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/long_term_traj.h): trajectory model · Long-horizon trajectory handling for safety evaluation. · `safety_shield/include/safety_shield/long_term_traj.h`
- [Traj utils](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/trajectory_utils.h): trajectory helpers · Utility layer for trajectory construction and transformation. · `safety_shield/include/safety_shield/trajectory_utils.h`
- [Measurements](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/measurement_handler.h): sensor boundary · Consumes raw observations and prepares state estimates for analysis. · `safety_shield/include/safety_shield/measurement_handler.h`
- [Kalman filter](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/kalman_filter.h): state estimator · Filtering and estimation logic for noisy measurements. · `safety_shield/include/safety_shield/kalman_filter.h`
- [Human reach](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/human_reach.h): reachability · Human reachable-set computation and scenario-specific reach analysis. · `safety_shield/include/safety_shield/human_reach.h`
- [Robot reach](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/robot_reach.h): reachability · Robot reachable-set computation for the planned motion. · `safety_shield/include/safety_shield/robot_reach.h`
- [Verify](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/verify.h): risk check · Primary collision-risk evaluation and safety decision logic. · `safety_shield/include/safety_shield/verify.h`
- [ISO verify](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/verify_iso.h): safety rule · ISO-oriented verification path for standard-driven safety checks. · `safety_shield/include/safety_shield/verify_iso.h`
- [Verify utils](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/verification_utils.h): verification helpers · Shared geometry and comparison helpers used by verification code. · `safety_shield/include/safety_shield/verification_utils.h`

### Interop

Python bindings and the interface layer into C++.

- [Python API](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/bindings/safety_shield_bindings.cpp): pybind11 bridge · C++ binding layer exposing the safety shield to Python. · `safety_shield/bindings/safety_shield_bindings.cpp`

### Scenario data

Configuration and motion-relevant inputs used to parameterize runs.

- [Config utils](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/include/safety_shield/config_utils.h): config loader · Parses and normalizes YAML-based scenario and robot parameters. · `safety_shield/include/safety_shield/config_utils.h`

### External deps

Vendored third-party libraries and reachability/planning engines.

- [SaRA](https://github.com/jakobthumm/sara-shield/tree/main/safety_shield/external/SaRA): external reachability engine · Vendored reachability engine used by human and robot reach analysis. · `safety_shield/external/SaRA`
- [LongTermPlanner](https://github.com/jakobthumm/sara-shield/tree/main/safety_shield/external/LongTermPlanner): external planner · Vendored planner library supporting long-horizon trajectory logic. · `safety_shield/external/LongTermPlanner`
- [yaml-cpp](https://github.com/jakobthumm/sara-shield/tree/main/safety_shield/external/yaml-cpp): external parser · Vendored YAML parsing library for configuration loading. · `safety_shield/external/yaml-cpp`
- [spdlog](https://github.com/jakobthumm/sara-shield/tree/main/safety_shield/external/spdlog): external logging · Vendored logging library used for runtime diagnostics. · `safety_shield/external/spdlog`

### Tests

Native and Python test coverage for library behavior.

- [C++ tests](https://github.com/jakobthumm/sara-shield/tree/main/safety_shield/tests/src): native tests · C++ unit tests covering the core safety modules. · `safety_shield/tests/src`
- [Python tests](https://github.com/jakobthumm/sara-shield/tree/main/safety_shield/tests/bindings): binding tests · Python tests validating the exposed API and bindings. · `safety_shield/tests/bindings`

### Tooling

Debug programs and supporting scripts.

- [Debug tools](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/src/debug.cc): executables · Standalone debug and scenario exploration programs. · `safety_shield/src/debug.cc`
- [Capsule gen](https://github.com/jakobthumm/sara-shield/blob/main/safety_shield/scripts/urdf_capsule_generation.py): geometry script · Script for generating capsule collision geometry from robot descriptions. · `safety_shield/scripts/urdf_capsule_generation.py`

## Connections

- Safety shield → Motion: uses · Coordinates robot motion state for safety evaluation.
- Safety shield → Long-term traj: plans · Evaluates longer-horizon trajectories before execution.
- Safety shield → Measurements: consumes · Starts from filtered measurements and scenario state.
- Safety shield → Human reach: checks · Compares human future states against the robot trajectory.
- Safety shield → Robot reach: checks · Computes robot future occupancy for collision analysis.
- Safety shield → Verify: decides · Produces the final continue/slow/stop decision.
- Safety shield → ISO verify: optionally uses · Can apply ISO-oriented verification rules.
- Motion → Path: builds on · Motion uses path abstractions as its geometric/temporal basis.
- Motion → Traj utils: uses · Depends on trajectory helpers for transformation and interpolation.
- Long-term traj → Path: extends · Represents longer trajectories as path-aware motion over time.
- Long-term traj → LongTermPlanner: integrates · Leverages the external planner for long-horizon trajectory logic.
- Measurements → Kalman filter: filters · Uses Kalman filtering to stabilize noisy measurements.
- Kalman filter → Config utils: parametrized by · Filter behavior is driven by loaded scenario parameters.
- Human reach → SaRA: depends on · Uses the external reachability engine for future human states.
- Robot reach → SaRA: depends on · Uses the external reachability engine for future robot states.
- Verify → Verify utils: uses · Shares geometric and separation checks through helper routines.
- ISO verify → Verify utils: uses · Reuses verification helpers for standard-based checks.
- Config utils → yaml-cpp: parses with · Loads YAML scenario and robot configuration files.
- Config utils → spdlog: logs with · Emits diagnostics while loading and validating configuration.
- Python API → Safety shield: exposes · Wraps the core orchestrator for Python consumers.
- Python API → Motion: exposes · Makes motion primitives available through the Python API.
- Python API → Long-term traj: exposes · Publishes long-term trajectory handling to Python.
- Python API → C++ tests: validated by · Binding behavior is exercised by Python-facing tests.
- C++ tests → Safety shield: covers · Native tests verify the main coordination layer.
- C++ tests → Human reach: covers · Native tests verify reachability analysis.
- C++ tests → Robot reach: covers · Native tests verify robot reachability analysis.
- C++ tests → Verify: covers · Native tests verify safety decision logic.
- Python tests → Python API: covers · Python tests validate the pybind11 API contract.
- Debug tools → Safety shield: exercise · Standalone debug executables drive the core runtime.
- Capsule gen → Robot reach: supports · Generates collision geometry used by robot safety analysis.
