How jakobthumm/sara-shield works
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.h Safety shield · src C++ tests · safety_shield_bindings.cpp Python API · motion.h Motion
Components 22
Core library
Native C++ safety shielding and analysis components.
- Safety shield · Top-level runtime coordinator that turns analysis into safety actions.
safety_shield/include/safety_shield/safety_shield.h - Motion · Robot motion representation and state evolution helpers.
safety_shield/include/safety_shield/motion.h - Path · Planned path representation used by motion and trajectory logic.
safety_shield/include/safety_shield/path.h - Long-term traj · Long-horizon trajectory handling for safety evaluation.
safety_shield/include/safety_shield/long_term_traj.h - Traj utils · Utility layer for trajectory construction and transformation.
safety_shield/include/safety_shield/trajectory_utils.h - Measurements · Consumes raw observations and prepares state estimates for analysis.
safety_shield/include/safety_shield/measurement_handler.h - Kalman filter · Filtering and estimation logic for noisy measurements.
safety_shield/include/safety_shield/kalman_filter.h - Human reach · Human reachable-set computation and scenario-specific reach analysis.
safety_shield/include/safety_shield/human_reach.h - Robot reach · Robot reachable-set computation for the planned motion.
safety_shield/include/safety_shield/robot_reach.h - Verify · Primary collision-risk evaluation and safety decision logic.
safety_shield/include/safety_shield/verify.h - ISO verify · ISO-oriented verification path for standard-driven safety checks.
safety_shield/include/safety_shield/verify_iso.h - Verify utils · 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 · 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 · 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 · Vendored reachability engine used by human and robot reach analysis.
safety_shield/external/SaRA - LongTermPlanner · Vendored planner library supporting long-horizon trajectory logic.
safety_shield/external/LongTermPlanner - yaml-cpp · Vendored YAML parsing library for configuration loading.
safety_shield/external/yaml-cpp - spdlog · Vendored logging library used for runtime diagnostics.
safety_shield/external/spdlog
Tests
Native and Python test coverage for library behavior.
- C++ tests · C++ unit tests covering the core safety modules.
safety_shield/tests/src - Python tests · Python tests validating the exposed API and bindings.
safety_shield/tests/bindings
Tooling
Debug programs and supporting scripts.
- Debug tools · Standalone debug and scenario exploration programs.
safety_shield/src/debug.cc - Capsule gen · Script for generating capsule collision geometry from robot descriptions.
safety_shield/scripts/urdf_capsule_generation.py
Connections 30
- 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.