Skip to content

Commit 1e2335f

Browse files
jdsikajdsika
committed
feat: add skeleton to Occupant reusing PedestrianAttributes.Bone
Add Occupant.Skeleton message in osi_occupant.proto that reuses MovingObject.PedestrianAttributes.Bone for occupant pose representation. The skeleton root is anchored via bbcenter_to_root relative to the vehicle bounding box center. Add migration notes on PedestrianAttributes documenting the plan to introduce a common skeleton type in OSI 4. Add .github/copilot-instructions.md for Copilot context. Signed-off-by: Carlo van Driesten <carlo.van-driesten@bmw.de>
1 parent 083481d commit 1e2335f

3 files changed

Lines changed: 197 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Copilot Instructions for Open Simulation Interface (OSI)
2+
3+
## Overview
4+
5+
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`.
6+
7+
## Build & Test
8+
9+
**Run all tests:**
10+
11+
```sh
12+
pip install pyyaml
13+
python -m unittest discover tests
14+
```
15+
16+
**Run a single test file or test case:**
17+
18+
```sh
19+
python -m unittest tests.test_rules
20+
python -m unittest tests.test_rules.TestRules.test_rules_compliance
21+
```
22+
23+
**Validate proto compilation** (requires `grpcio-tools`):
24+
25+
```sh
26+
python -m grpc_tools.protoc --proto_path=. --python_out=. osi_common.proto osi_occupant.proto
27+
```
28+
29+
**Build Doxygen docs** (requires CMake, Doxygen, proto2cpp):
30+
31+
```sh
32+
mkdir build && cd build
33+
cmake -D FILTER_PROTO2CPP_PY_PATH=<path-to-proto2cpp> ../
34+
cmake --build . --config Release
35+
```
36+
37+
## Architecture
38+
39+
### Proto Dependency Hierarchy
40+
41+
```
42+
osi_version.proto.in (template → osi_version.proto via CMake)
43+
↓
44+
osi_common.proto (primitives: Vector3d, Timestamp, Identifier, BoundingBox, etc.)
45+
↓
46+
building blocks (osi_object, osi_lane, osi_environment, osi_trafficsign, osi_trafficlight,
47+
osi_roadmarking, osi_occupant, osi_logicallane, osi_referenceline, osi_route, …)
48+
↓
49+
top-level containers (see below)
50+
```
51+
52+
### Top-Level Container Messages
53+
54+
| Message | File | Role |
55+
|---------|------|------|
56+
| `GroundTruth` | `osi_groundtruth.proto` | Complete simulated environment state |
57+
| `SensorView` | `osi_sensorview.proto` | Input to a sensor model (GroundTruth + config) |
58+
| `SensorData` | `osi_sensordata.proto` | Output of a sensor model (detected entities) |
59+
| `HostVehicleData` | `osi_hostvehicledata.proto` | Vehicle's own internal state perception |
60+
| `StreamingUpdate` | `osi_streamingupdate.proto` | Partial/incremental updates |
61+
| `SensorDataSeries` | `osi_datarecording.proto` | Time-series recording wrapper |
62+
63+
### Detected vs Ground Truth Pattern
64+
65+
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.
66+
67+
## Proto Commenting Conventions
68+
69+
Every message, enum, and field **must** have a comment. CI tests enforce this.
70+
71+
### Messages and Enums
72+
73+
Must start with `\brief` on a separate comment line:
74+
75+
```proto
76+
//
77+
// \brief A cartesian 3D vector for positions, velocities or accelerations.
78+
//
79+
// The coordinate system is defined as right-handed.
80+
//
81+
message Vector3d
82+
{
83+
```
84+
85+
### Fields
86+
87+
Minimum 2 comment lines (content + blank `//`). Units on a separate line:
88+
89+
```proto
90+
// The number of seconds since start.
91+
//
92+
// Unit: s
93+
//
94+
optional int64 seconds = 1;
95+
```
96+
97+
### Validation Rules
98+
99+
Wrap in `\rules` / `\endrules` blocks. Available rules are defined in `rules.yml`:
100+
101+
```proto
102+
// \rules
103+
// is_greater_than_or_equal_to: 0
104+
// is_less_than_or_equal_to: 999999999
105+
// \endrules
106+
```
107+
108+
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`.
109+
110+
### Other Doxygen Markers
111+
112+
- `\note` — important notes
113+
- `\attention` — deprecation warnings
114+
- `\c TypeName` — inline code/type reference
115+
- `\image html filename.svg "caption" width=550px` — image reference
116+
- `\b text` — bold
117+
118+
## Code Style
119+
120+
Defined in `.clang-format`: Google base style, 4-space indent, 80-column limit, Allman braces (`{` on new line), no tabs.
121+
122+
## Versioning
123+
124+
`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**.
125+
126+
## CI Pipeline
127+
128+
GitHub Actions (`protobuf.yml`) runs on push/PR to master:
129+
1. **Spellcheck** — aspell via pyspelling (custom wordlist at `.github/spelling_custom_words_en_US.txt`)
130+
2. **Tests** — `python -m unittest discover tests`
131+
3. **Doxygen build** — generates API docs from proto comments
132+
133+
## Key Conventions
134+
135+
- All proto field numbers are stable — never reuse or renumber existing fields.
136+
- `repeated` fields use singular names (e.g. `repeated WheelData wheel_data`, not `wheel_datas`).
137+
- Enum values are prefixed with the enum type in UPPER_SNAKE_CASE (e.g. enum `Seat` → `SEAT_FRONT_LEFT`).
138+
- IDs use the `Identifier` message type and are typically `is_globally_unique`.
139+
- Cross-references between entities use `refers_to` rules (e.g. `refers_to: MovingObject`).
140+
- Coordinate system is right-handed, following ISO 8855 for vehicles.
141+
- Bounding box offsets follow the `bbcenter_to_*` naming pattern (e.g. `bbcenter_to_rear`, `bbcenter_to_root`).
142+
- PRs require DCO sign-off and "ReadyForCCBReview" label for Change Control Board review.

‎osi_object.proto‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1302,6 +1302,11 @@ message MovingObject
13021302
// This is an extension to the \c MovingObject with additional information
13031303
// describing a pedestrian in more detail.
13041304
//
1305+
// \note The \c Bone type defined in this message is also reused by
1306+
// \c Occupant::Skeleton for vehicle occupant pose representation.
1307+
// In OSI 4, a common skeleton type is planned to replace both
1308+
// usages.
1309+
//
13051310
message PedestrianAttributes
13061311
{
13071312
// Position offset from the center of the bounding box to the current position

‎osi_occupant.proto‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ syntax = "proto2";
33
option optimize_for = SPEED;
44

55
import "osi_common.proto";
6+
import "osi_object.proto";
67

78
package osi3;
89

@@ -36,6 +37,55 @@ message Occupant
3637
//
3738
repeated ExternalReference source_reference = 3;
3839

40+
// The skeleton of the occupant.
41+
//
42+
// The skeleton represents the posture and body structure of the occupant
43+
// within the host vehicle.
44+
//
45+
optional Skeleton skeleton = 4;
46+
47+
//
48+
// \brief Skeleton data describing the posture of the occupant.
49+
//
50+
// The skeleton is defined relative to a root point. The root point
51+
// itself is positioned relative to the vehicle's bounding box center
52+
// using \c #bbcenter_to_root.
53+
//
54+
// \note This message reuses
55+
// \c MovingObject::PedestrianAttributes::Bone to avoid type
56+
// duplication. In OSI 4, a common skeleton type is planned to
57+
// replace both this and \c MovingObject::PedestrianAttributes.
58+
//
59+
message Skeleton
60+
{
61+
// Position offset from the vehicle's bounding box center
62+
// (\c MovingObject::base . \c BaseMoving::position) to the
63+
// current position of the root point of the skeleton model,
64+
// analogous to
65+
// \c MovingObject::VehicleAttributes::bbcenter_to_rear.
66+
//
67+
optional Vector3d bbcenter_to_root = 1;
68+
69+
// List of all bones of the occupant.
70+
//
71+
// The number of bones may vary, based on the detail level of
72+
// the model used. For example, some simulators will not include
73+
// detailed data about the hands of an occupant.
74+
//
75+
// \note A bone of each type can be provided, or left out,
76+
// depending on the desired level of detail, or available data.
77+
// However, if a bone is defined, all bones in the chain from
78+
// that bone back to the root point must be provided to create
79+
// a complete chain.
80+
//
81+
// \note Reuses \c MovingObject::PedestrianAttributes::Bone
82+
// for the bone definition. Bone positions and orientations are
83+
// defined relative to the skeleton root point
84+
// (\c #bbcenter_to_root).
85+
//
86+
repeated MovingObject.PedestrianAttributes.Bone skeleton_bone = 2;
87+
}
88+
3989
//
4090
// \brief Information regarding the classification of the occupant.
4191
//

0 commit comments

Comments
 (0)