feat: per-topic message transforms; Cloudini point cloud compression

[facontidavide]

Summary

Operator-configured, per-topic message transforms for the ROS2 backend, with two implementations:

• cloudini — sensor_msgs/msg/PointCloud2 → point_cloud_interfaces/msg/CompressedPointCloud2 using Cloudini (lossy at a configurable resolution). Cloudini's own second compression stage is disabled: the bridge already zstd-compresses every frame.
• strip — the existing MessageStripper behind the new interface. strip_large_messages: true keeps working as sugar for strip rules appended after the profile's rules.

Enabled with one new parameter, transform_profile (path to a JSON file, empty = off). With no profile and strip_large_messages: false nothing is created and behaviour is unchanged. Design and rationale: docs/superpowers/specs/2026-09-20-message-transforms-design.md; user documentation: docs/API.md → "Message Transforms".

{"transforms": [{"match_type": "sensor_msgs/msg/PointCloud2", "transform": "cloudini",
                 "params": {"resolution": 0.001}}]}

How it works

• TransformSet parses the profile (ordered rules, first match wins; match_type is required and exact, match_topic is an optional full-match regex that narrows it) and owns one transform instance per topic plus its counters. The whole profile is validated at launch, before the WebSocket port opens: every mistake — including a transform paired with a type it cannot handle, e.g. cloudini on an Image — exits 1 with a message naming the rule. match_type is mandatory precisely so that this check does not depend on which topics happen to be discovered at startup.
• TransformingTopicSource decorates the topic source, so a transformed topic is advertised with its output type and schema. The wire protocol is unchanged; the only additions are an optional source_type on get_topics entries and a message_transforms capability, both ignored by the current PlotJuggler plugin (checked against its source).
• Ros2SubscriptionManager subscribes with the topic's real type and runs the transform on a std::span over the rcl buffer — the raw message is never copied — writing straight into the vector MessageBuffer keeps. A failed transform drops the sample (counted, throttled warning); it is never forwarded raw, since the client was told the output type.
• Everything downstream (latched replay, heavy-frame threshold, rate limits, backpressure) sees post-transform bytes with no special cases.
• Per-topic transform statistics are logged at shutdown.

Measured (pinned cores, performance governor, 4 lidars × 10 Hz ≈ 52 MiB/s raw, 1 client, 3 runs each)

Configuration	Bridge CPU (% of a core)	Wire	Encode
no profile	16.7 / 18.9 / 19.3	31.0 MB/s	—
cloudini 1 mm	16.7 / 14.0 / 16.8	14.6 MB/s	1.4 ms/cloud
cloudini 1 mm + viz_preprocessing	18.3 / 17.9 / 18.3	13.8 MB/s	2.9 ms/cloud

Lossless in every run (300/300 clouds per lidar in 30 s, zero drops). Bandwidth halves at roughly equal CPU: the encode time on the ingest thread is paid back by zstd having a third of the bytes to compress. Synchronous encoding was sufficient, so no worker thread was added.

Build changes

• C++20 (needed for std::span; cloudini_lib also exports cxx_std_20). First commit on the branch, so CI isolates it.
• Cloudini is optional: find_package(cloudini_lib 1.3.1) first, otherwise fetched (1.3.1, pinned hash) with a plain FetchContent_MakeAvailable and linked statically. Embedding it cleanly and validating malformed clouds needed upstream fixes, released as Cloudini 1.3.1 (fix: reject inconsistent point clouds; make ros_message_definitions.hpp includable twice facontidavide/cloudini#141, #142); the workarounds this PR first carried for that are gone. -DPJ_BRIDGE_FETCH_CLOUDINI=OFF builds without the cloudini transform (needed for builds without network access).

Behaviour changes

• strip: a message that fails to strip is now dropped instead of forwarded untouched (uniform transform failure policy).

Testing

• 304 unit tests (Humble pixi locally, all seven CI jobs); 301 with -DPJ_BRIDGE_FETCH_CLOUDINI=OFF, where a profile naming cloudini fails at startup with "unknown transform"; TSAN clean on the new code (includes a two-thread run() vs bind/find/stats test).
• Startup error paths exercised against the real binary.
• Review passes per task, on the whole branch, a four-angle simplification pass (352cafb) and a final one on the mandatory-match_type change. Bugs found along the way were reproduced by a failing test before being fixed.

Not verified / known limitations

• End-to-end rendering in PlotJuggler needs a client with the CompressedPointCloud2 parser (pj-official-plugins, feat/compressed-pointcloud) — not tested here.
• Kilted, Lyrical and the Humble CI container (CMake 3.22) are verified by this PR's CI only (green).
• The installed-by-ament cloudini_lib path (target cloudini_lib::cloudini_lib) is handled but could not be exercised locally.
• package.xml does not depend on cloudini_lib yet, so ROS buildfarm debs (no network) would lack the transform until that rosdep key exists; GitHub-built debs, conda packages and AppImages get it through the fetch.
• Big-endian point clouds are not detected (Cloudini discards the flag). FastDDS/RTI backends are not wired.

🤖 Generated with Claude Code

https://claude.ai/code/session_01711BZcEtp3KsoF9uZHNFME