feat(pj_scene_protocol): SDK module for marker / scene wire format

[facontidavide]

Summary

Introduces pj_scene_protocol as a 4th sibling SDK module alongside pj_base, pj_datastore, pj_plugins. It carries the canonical schema and Foxglove ImageAnnotations Protobuf codec — writer and reader together — so a plugin author that produces or consumes markers links one target with pj_base-only deps.

Source content was moved from PJ4 (pj_media/pj_marker_protocol/ + pj_media/core/scene_decoder*). Folding the reader in eliminates the "matching reader still lives in pj_media_core for now" asymmetry the old CMake apologised for.

Renamed during the move: pj_marker_protocol → pj_scene_protocol. The scope was always wider than 2D markers (image_annotation.h documents the 3D ScenePrimitive / Grid expansion path); the rename matches Foxglove's own "scene" terminology and is cheap before any external code depends on the directory / target / include name. Type identifiers (ImageAnnotation, SceneFrame, kSchemaImageAnnotations, etc.) are unchanged.

What's in the module

pj_scene_protocol/
├── CMakeLists.txt                    # mirrors pj_base
├── include/pj_scene_protocol/
│   ├── image_annotation.h            # value types: Point2, ColorRGBA, ImageAnnotation, SceneFrame, …
│   ├── image_annotation_codec.h      # serializeImageAnnotation() + kSchemaImageAnnotations
│   └── scene_decoder.h               # ISceneDecoder + makeSceneDecoder()
├── src/
│   ├── image_annotation_codec.cpp    # hand-rolled writer (no libprotobuf)
│   ├── scene_decoder.cpp             # factory dispatcher
│   └── scene_decoder_protobuf.cpp    # hand-rolled reader, full Points/Circle/Text decode
├── tests/
│   ├── image_annotation_codec_test.cpp   # 9 cases incl. golden-byte + round-trip
│   └── scene_decoder_test.cpp            # decoder coverage + error paths
└── docs/
    ├── ARCHITECTURE.md               # wire format spec, type catalog, encoding rules
    └── USER_GUIDE.md                 # producer + consumer recipes, pitfalls

Build / integration

• plotjuggler_core/CMakeLists.txt — add_subdirectory(pj_scene_protocol).
• run_clang_tidy.sh — new module added to the source-dirs list.
• CLAUDE.md — module added to Modules list, dependency graph, Key Documentation table, and the Read all documentation glossary entry.

In-flight cleanup landed during the move

• scene_decoder_protobuf.cpp top-of-file comment fixed — the stale "MVP: decodes PointsAnnotation fully... CircleAnnotation/TextAnnotation bodies skipped" claim was contradicted by the implementation (decodes all three; round-trip tests cover them).
• All pj_marker_protocol/... and pj_media_core/scene_decoder.h includes rebased onto pj_scene_protocol/....

Commit layout

1. style: clang-format v22 pass across pj_base, pj_datastore, pj_plugins — pure formatting, surfaced because pre-commit re-ran clang-format v22 across the tree while formatting the new module. Isolated from the feature commit so review stays focused.
2. feat(pj_scene_protocol): SDK module for marker / scene wire format — the substantive change.

Phase 2 (separate, follow-up PR)

PJ4 deletes its local pj_media/pj_marker_protocol/ and the reader files in pj_media/core/, bumps the submodule pointer to this PR's merge commit, and rebases its includes onto pj_scene_protocol/.... Sequenced after this PR merges.

Test plan

• ./build.sh clean to 100%
• ./test.sh — submodule-local 44/44 pass (42 baseline + 2 new: image_annotation_codec_test 9 cases, scene_decoder_test)
• ./run_clang_tidy.sh — local environment is missing clangd-22; needs to be run by reviewer or in CI before merge
• Reviewer eye-pass on docs/ARCHITECTURE.md and docs/USER_GUIDE.md (newly written, no prior version to diff against)

🤖 Generated with Claude Code