diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..dceba19a8 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,142 @@ +# Copilot Instructions for Open Simulation Interface (OSI) + +## Overview + +OSI is a Protocol Buffers (proto2) interface specification for environmental perception of automated driving functions. All `.proto` files use `syntax = "proto2"`, `option optimize_for = SPEED`, and belong to `package osi3`. + +## Build & Test + +**Run all tests:** + +```sh +pip install pyyaml +python -m unittest discover tests +``` + +**Run a single test file or test case:** + +```sh +python -m unittest tests.test_rules +python -m unittest tests.test_rules.TestRules.test_rules_compliance +``` + +**Validate proto compilation** (requires `grpcio-tools`): + +```sh +python -m grpc_tools.protoc --proto_path=. --python_out=. osi_common.proto osi_occupant.proto +``` + +**Build Doxygen docs** (requires CMake, Doxygen, proto2cpp): + +```sh +mkdir build && cd build +cmake -D FILTER_PROTO2CPP_PY_PATH= ../ +cmake --build . --config Release +``` + +## Architecture + +### Proto Dependency Hierarchy + +``` +osi_version.proto.in (template → osi_version.proto via CMake) + ↓ +osi_common.proto (primitives: Vector3d, Timestamp, Identifier, BoundingBox, etc.) + ↓ +building blocks (osi_object, osi_lane, osi_environment, osi_trafficsign, osi_trafficlight, + osi_roadmarking, osi_occupant, osi_logicallane, osi_referenceline, osi_route, …) + ↓ +top-level containers (see below) +``` + +### Top-Level Container Messages + +| Message | File | Role | +|---------|------|------| +| `GroundTruth` | `osi_groundtruth.proto` | Complete simulated environment state | +| `SensorView` | `osi_sensorview.proto` | Input to a sensor model (GroundTruth + config) | +| `SensorData` | `osi_sensordata.proto` | Output of a sensor model (detected entities) | +| `HostVehicleData` | `osi_hostvehicledata.proto` | Vehicle's own internal state perception | +| `StreamingUpdate` | `osi_streamingupdate.proto` | Partial/incremental updates | +| `SensorDataSeries` | `osi_datarecording.proto` | Time-series recording wrapper | + +### Detected vs Ground Truth Pattern + +Ground truth entities (e.g. `MovingObject`, `Occupant`, `Lane`) live in `GroundTruth`. Each has a corresponding `Detected*` message (e.g. `DetectedMovingObject`, `DetectedOccupant`, `DetectedLane`) in `SensorData` that wraps a list of candidates with probabilities. + +## Proto Commenting Conventions + +Every message, enum, and field **must** have a comment. CI tests enforce this. + +### Messages and Enums + +Must start with `\brief` on a separate comment line: + +```proto +// +// \brief A cartesian 3D vector for positions, velocities or accelerations. +// +// The coordinate system is defined as right-handed. +// +message Vector3d +{ +``` + +### Fields + +Minimum 2 comment lines (content + blank `//`). Units on a separate line: + +```proto + // The number of seconds since start. + // + // Unit: s + // + optional int64 seconds = 1; +``` + +### Validation Rules + +Wrap in `\rules` / `\endrules` blocks. Available rules are defined in `rules.yml`: + +```proto + // \rules + // is_greater_than_or_equal_to: 0 + // is_less_than_or_equal_to: 999999999 + // \endrules +``` + +Available rule keywords: `is_greater_than`, `is_greater_than_or_equal_to`, `is_less_than`, `is_less_than_or_equal_to`, `is_equal_to`, `is_different_to`, `is_globally_unique`, `refers_to`, `is_iso_country_code`, `first_element`, `last_element`, `check_if ... else do_check`, `is_set`, `minimum_length`, `maximum_length`. + +### Other Doxygen Markers + +- `\note` — important notes +- `\attention` — deprecation warnings +- `\c TypeName` — inline code/type reference +- `\image html filename.svg "caption" width=550px` — image reference +- `\b text` — bold + +## Code Style + +Defined in `.clang-format`: Google base style, 4-space indent, 80-column limit, Allman braces (`{` on new line), no tabs. + +## Versioning + +`VERSION` file holds `VERSION_MAJOR`, `VERSION_MINOR`, `VERSION_PATCH`. CMake substitutes these into `osi_version.proto.in` → `osi_version.proto`. Current version: **3.8.0**. + +## CI Pipeline + +GitHub Actions (`protobuf.yml`) runs on push/PR to master: +1. **Spellcheck** — aspell via pyspelling (custom wordlist at `.github/spelling_custom_words_en_US.txt`) +2. **Tests** — `python -m unittest discover tests` +3. **Doxygen build** — generates API docs from proto comments + +## Key Conventions + +- All proto field numbers are stable — never reuse or renumber existing fields. +- `repeated` fields use singular names (e.g. `repeated WheelData wheel_data`, not `wheel_datas`). +- Enum values are prefixed with the enum type in UPPER_SNAKE_CASE (e.g. enum `Seat` → `SEAT_FRONT_LEFT`). +- IDs use the `Identifier` message type and are typically `is_globally_unique`. +- Cross-references between entities use `refers_to` rules (e.g. `refers_to: MovingObject`). +- Coordinate system is right-handed, following ISO 8855 for vehicles. +- Bounding box offsets follow the `bbcenter_to_*` naming pattern (e.g. `bbcenter_to_rear`, `bbcenter_to_root`). +- PRs require DCO sign-off and "ReadyForCCBReview" label for Change Control Board review. diff --git a/osi_object.proto b/osi_object.proto index 8814782cb..f1f54d2c8 100644 --- a/osi_object.proto +++ b/osi_object.proto @@ -1302,6 +1302,11 @@ message MovingObject // This is an extension to the \c MovingObject with additional information // describing a pedestrian in more detail. // + // \note The \c Bone type defined in this message is also reused by + // \c Occupant::Skeleton for vehicle occupant pose representation. + // In OSI 4, a common skeleton type is planned to replace both + // usages. + // message PedestrianAttributes { // Position offset from the center of the bounding box to the current position diff --git a/osi_occupant.proto b/osi_occupant.proto index 8b7f6ea83..9f78673d0 100644 --- a/osi_occupant.proto +++ b/osi_occupant.proto @@ -3,6 +3,7 @@ syntax = "proto2"; option optimize_for = SPEED; import "osi_common.proto"; +import "osi_object.proto"; package osi3; @@ -36,6 +37,55 @@ message Occupant // repeated ExternalReference source_reference = 3; + // The skeleton of the occupant. + // + // The skeleton represents the posture and body structure of the occupant + // within the host vehicle. + // + optional Skeleton skeleton = 4; + + // + // \brief Skeleton data describing the posture of the occupant. + // + // The skeleton is defined relative to a root point. The root point + // itself is positioned relative to the vehicle's bounding box center + // using \c #bbcenter_to_root. + // + // \note This message reuses + // \c MovingObject::PedestrianAttributes::Bone to avoid type + // duplication. In OSI 4, a common skeleton type is planned to + // replace both this and \c MovingObject::PedestrianAttributes. + // + message Skeleton + { + // Position offset from the vehicle's bounding box center + // (\c MovingObject::base . \c BaseMoving::position) to the + // current position of the root point of the skeleton model, + // analogous to + // \c MovingObject::VehicleAttributes::bbcenter_to_rear. + // + optional Vector3d bbcenter_to_root = 1; + + // List of all bones of the occupant. + // + // The number of bones may vary, based on the detail level of + // the model used. For example, some simulators will not include + // detailed data about the hands of an occupant. + // + // \note A bone of each type can be provided, or left out, + // depending on the desired level of detail, or available data. + // However, if a bone is defined, all bones in the chain from + // that bone back to the root point must be provided to create + // a complete chain. + // + // \note Reuses \c MovingObject::PedestrianAttributes::Bone + // for the bone definition. Bone positions and orientations are + // defined relative to the skeleton root point + // (\c #bbcenter_to_root). + // + repeated MovingObject.PedestrianAttributes.Bone skeleton_bone = 2; + } + // // \brief Information regarding the classification of the occupant. //