How intel/ad-rss-lib works
Project Type & Overall Purpose
• This is a C++ library for implementing Responsibility Sensitive Safety (RSS) for automated vehicles. Its purpose is to take processed sensor input (an object list) and produce a range of safety responses (acceleration restrictions) for use in automated driving systems.
• In addition, there are Python bindings to enable integration with Python-based systems and an “ad_rss_map_integration” module that demonstrates how to integrate the core RSS functionality with map data (used for providing road boundary and map information).
Main Components
a. Core RSS Library (ad_rss)
– Submodules:
• Core: Implements the safety checks – including RssCheck, RssResponseResolving, and RssSituationExtraction.
• Situation: Contains the RSS formulas and physics calculations (see files like RssFormulas, Physics.cpp/hpp).
• State: Implements the state evaluation aspects (e.g., lateral and longitudinal responses, RssStateEvaluator, etc.) found in the ‘state’ directory.
• World/Unstructured: Contains modules that handle additional aspects (e.g., lane driving, object topology, world modeling, geometry).
– Generated code:
• The project creates generated header and source files for many of these components (for example, in the “generated/include” and “generated/src” directories) to ensure consistency between different parts of the RSS functionality.
b. Python Binding Module
– Under the “python” directories (in both the ad_rss and ad_rss_map_integration folders), this provides an interface to use the library with Python.
– Key components such as “AdRssPythonModule.cpp.in”, “generate_python_lib.py.in”, and “setup.py.in” should be highlighted as integration points.
c. Integration Module (ad_rss_map_integration)
– This module demonstrates how to integrate the RSS library with automated driving map data.
– Important components include classes for logging, converting objects, and creating RSS scenes (files like RssSceneCreator, RssSceneCreation, and related test resources).
d. Build, Testing, and Documentation Infrastructure
– Build System: Emphasize the cmake support, including CMakeLists.txt files in multiple directories and cmake configuration modules.
– Continuous Integration: Include the GitHub workflows (under “.github/workflows”) that handle building, testing, code formatting, static analysis, and documentation deployment.
– Testing Components: There are extensive unit tests (in “tests”). The test directories for core, situation, state, world, and integration are part of ensuring the robustness of the implementation.
– Documentation: The “doc” directories contain markdown, Doxygen configurations (including doxyfiles), and images to support the architectural overview. This helps users understand safe driving scenarios and design decisions.
Relationships and Interactions
• Within the core RSS library, the input object list is processed to form “situations” (for each pair of ego vehicle and external object). These situations are then analyzed by:
• Core Processing (RssSituationChecking, RssResponseResolving, etc.)
• Physics and formula evaluations (RssFormulas and Physics)
• State evaluation that results in the proper acceleration restrictions.
• The map integration module uses the core RSS functionality and wraps it to account for additional map information (like road boundaries) and to generate more contextualized RSS scenes.
• Python bindings provide a gateway for interfacing between the C++ core functionality and Python-driven applications.
• Testing and CI pipelines are connected to all the major modules to ensure quality and compliance.
Architectural Patterns & Key Design Principles
• Modular Design: The library is split into clearly defined modules (core, situation, state, world, unstructured, integration) which fosters reusability and testability.
• Separation of Concerns: Input conversion and actuation conversion are deliberately outside the library scope, focusing solely on calculating the safety response.
• Automated Building & Testing: Use of cmake, GitHub workflows, and structured test directories enforce continuous integration practices.
• Use of Code Generation: The “generated” code directories highlight that parts of the API are auto-generated to enforce consistency and proper input range checking.