Add PersonSkeleton common type and skeleton field for Occupant

.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=<path-to-proto2cpp> ../
+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.

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

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.
     //