rosotacom-dev 2.5.dev39__tar.gz → 2.5.dev40__tar.gz

{rosotacom_dev-2.5.dev39 → rosotacom_dev-2.5.dev40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev39
+Version: 2.5.dev40
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause

{rosotacom_dev-2.5.dev39 → rosotacom_dev-2.5.dev40}/session-configuration.md

@@ -446,7 +446,8 @@ processing:
   pixel_cap_preset: "wsvga"       # scalar, used as suffix only,
   transport:
     type: ffmpeg                  # ffmpeg | foxglove | compressed
-    local_republish: false        # default false
+    local_republish: raw          # raw | compressed; omit for no sender-side decode
+    remote_republish: compressed  # raw | compressed; omit for no receiver-side decode
     # plus type-specific params (see below)
 ```
 
@@ -507,11 +508,37 @@ The receiver undoes the chain in reverse, and every stage there is computed from
 the delivered topic rather than from the OTA topic:
 
 1) unwrap → republishes on the pre-wrap name (so wrapping renames nothing)
-2) `local_republish: true` → reverse transport decodes into `+ /raw`
+2) `remote_republish: <transport>` → reverse transport decodes into `+ /<transport>`
 3) decompress → republishes on the pre-compress name
 4) framebridge `global_to_local` → the local base topic
 5) trickle → `+ /trickle`, the only receiver-side stage that adds a suffix
 
+##### The two reverse republishes
+
+An encoded stream crosses the link as packets — `FFMPEGPacket`, `CompressedVideo`
+— and something has to turn those back into an image. That decode can happen in
+two places, and they answer different questions:
+
+- **`remote_republish`** runs on the receiving peer and is the one that matters:
+  it produces the topic the receiving application subscribes to (`<encoded>/raw`
+  or `<encoded>/compressed`), and it is what `_delivered_topic` reports as the
+  delivered stage.
+- **`local_republish`** runs on the *sending* peer, against the stream it just
+  encoded. Nothing crosses the link for it; it exists so the sending machine can
+  see approximately what the receiver will get.
+
+Both name the image transport they publish in rather than being switched on:
+
+| value | delivered type | cost |
+|---|---|---|
+| `raw` | `sensor_msgs/msg/Image` | the transport undone and nothing else, at full frame size — a 1280x800 stream is ~3 MB per frame |
+| `compressed` | `sensor_msgs/msg/CompressedImage` | a JPEG encode per frame, roughly an order of magnitude less data on the wire and in a `record -a` |
+
+Omitting a key means that side does not decode. There is deliberately **no
+default**: `type: compressed` already delivers an image, so a decode that
+switched itself on would produce exactly the full-size copy a session chose that
+transport to avoid.
+
 #### Transport parameters
 `type: ffmpeg` supports:
 - `gop_size` (int)

{rosotacom_dev-2.5.dev39 → rosotacom_dev-2.5.dev40}/src/rosotacom/cli.py

@@ -6134,8 +6134,11 @@ def _smoke_postprocessed_topic(entry: Any, pipe: dict[str, Any]) -> str:
     if pipe.get("framebridge") == "global_to_local":
         return str(pipe["fb_g2l_base"])
     transport = pipe.get("transport")
-    if transport is not None and bool(getattr(transport, "local_republish", False)):
-        return str(pipe["final"]) + "/raw"
+    remote_republish = getattr(transport, "remote_republish", None) if transport is not None else None
+    if remote_republish:
+        # The receiver's decode is what the smoke drives and asserts; the
+        # sender's own preview (`local_republish`) never reaches this peer.
+        return str(pipe["final"]) + f"/{remote_republish}"
     return str(pipe["final"])
 
 

{rosotacom_dev-2.5.dev39 → rosotacom_dev-2.5.dev40}/src/rosotacom/resources/examples/sessions/17_synthetic_camera_quality/session-definition.yaml

@@ -49,7 +49,11 @@ topics:
       processing:
         transport:
           type: ffmpeg
-          local_republish: true
+          # `raw` on both sides, because this example measures the codec: PSNR
+          # and SSIM compare pixels, and a JPEG twin would fold its own loss
+          # into the number the example exists to report.
+          local_republish: raw
+          remote_republish: raw
           gop_size: 4
           bit_rate: 2000000
         # Wrapping an encoded stream: the wrapper runs after the encoder, so the

{rosotacom_dev-2.5.dev39 → rosotacom_dev-2.5.dev40}/src/rosotacom/resources/ws/session/creation/generate_session_files.py

@@ -64,18 +64,34 @@ HEARTBEAT_MSG_TYPE = "com_msgs/msg/EchoHeartbeat"
 COMPRESSED_MSG_TYPE = "com_msgs/msg/CompressedData"
 OTA_STAMPED_MSG_TYPE = "com_msgs/msg/OtaStamped"
 SENSOR_IMAGE_MSG_TYPE = "sensor_msgs/msg/Image"
+SENSOR_COMPRESSED_IMAGE_MSG_TYPE = "sensor_msgs/msg/CompressedImage"
 TRANSPORT_OUTPUT_TYPES = {
     "compressed": "sensor_msgs/msg/CompressedImage",
     "ffmpeg": "ffmpeg_image_transport_msgs/msg/FFMPEGPacket",
     "foxglove": "foxglove_msgs/msg/CompressedVideo",
 }
+#: The image transports a reverse republish may decode *into*, and the message
+#: type each one delivers. `raw` is the neutral reconstruction -- the transport
+#: undone and nothing else -- and `compressed` trades a JPEG encode for roughly
+#: an order of magnitude less data on the wire and in a `record -a`.
+REPUBLISH_OUTPUT_TYPES = {
+    "raw": SENSOR_IMAGE_MSG_TYPE,
+    "compressed": SENSOR_COMPRESSED_IMAGE_MSG_TYPE,
+}
 
 
 @dataclass
 class TransportSpec:
     type: str
     params: Dict[str, Any]
-    local_republish: bool = False
+    #: Reverse republish on the sending peer: decode the stream it just encoded,
+    #: so the machine that sends can see what the receiver will get. Optional.
+    local_republish: Optional[str] = None
+    #: Reverse republish on the receiving peer: the decode the receiving
+    #: application consumes. Optional too -- a consumer that subscribes through
+    #: image_transport itself, or one that only forwards or records packets,
+    #: does not want a second copy of every frame.
+    remote_republish: Optional[str] = None
 
 
 @dataclass
@@ -1288,11 +1304,14 @@ def _delivered_topic(pipe: Dict[str, Any], final: str) -> str:
         # renames nothing downstream of it.
         topic = str(pipe["ota_in"])
     transport = pipe.get("transport")
-    if isinstance(transport, TransportSpec) and transport.local_republish:
-        # image_transport reverse republish decodes the encoded topic into
-        # `<encoded>/raw`; PSNR/SSIM and application-level checks need that
-        # decoded sensor_msgs/Image stage, not the encoded packet.
-        topic = str(pipe["irt_in"]) + "/raw"
+    if isinstance(transport, TransportSpec) and transport.remote_republish:
+        # The receiver's reverse republish decodes the encoded topic into
+        # `<encoded>/<transport>`, and that decoded image -- not the encoded
+        # packet -- is what the receiving application subscribes to.
+        # `local_republish` is deliberately not consulted here: it is the
+        # *sender's* preview, on the sender's machine, and says nothing about
+        # what the receiver ends up reading.
+        topic = str(pipe["irt_in"]) + f"/{transport.remote_republish}"
     elif pipe.get("compress"):
         topic = str(pipe["comp_in"])
     if pipe.get("framebridge") == "global_to_local":
@@ -1544,8 +1563,8 @@ def _build_status_pipeline_spec(
             if postprocessed != final:
                 native_in_type = base_type
                 transport = p.get("transport")
-                if isinstance(transport, TransportSpec) and transport.local_republish:
-                    native_in_type = SENSOR_IMAGE_MSG_TYPE
+                if isinstance(transport, TransportSpec) and transport.remote_republish:
+                    native_in_type = REPUBLISH_OUTPUT_TYPES[transport.remote_republish]
                 stages.append(
                     {
                         "stage": "native_in",
@@ -1659,9 +1678,27 @@ def _compute_pipeline(
         if not isinstance(t, dict) or "type" not in t:
             raise ValueError(f"transport must be dict with 'type' for topic '{entry.base}'")
         ttype = t["type"]
-        local_republish = bool(t.get("local_republish", False))
-        params = {k: v for k, v in t.items() if k not in ("type", "local_republish")}
-        transport = TransportSpec(type=ttype, params=params, local_republish=local_republish)
+        republish_keys = ("local_republish", "remote_republish")
+
+        def _republish(key: str) -> Optional[str]:
+            value = t.get(key)
+            if value is None:
+                return None
+            if value not in REPUBLISH_OUTPUT_TYPES:
+                raise ValueError(
+                    f"transport.{key} must name an image transport "
+                    f"({'|'.join(sorted(REPUBLISH_OUTPUT_TYPES))}) for topic '{entry.base}', got {value!r}. "
+                    "Omit the key for no reverse republish on that side."
+                )
+            return str(value)
+
+        params = {k: v for k, v in t.items() if k not in ("type", *republish_keys)}
+        transport = TransportSpec(
+            type=ttype,
+            params=params,
+            local_republish=_republish("local_republish"),
+            remote_republish=_republish("remote_republish"),
+        )
 
     topic = entry.base
 
@@ -1747,7 +1784,11 @@ def _compute_pipeline(
     if transport:
         it_in = topic
         topic = topic + f"/{transport.type}"
-        if transport.local_republish:
+        if transport.local_republish or transport.remote_republish:
+            # The encoded topic a reverse republish decodes *from*. One name for
+            # both sides: each peer runs its own decoder against the copy it has
+            # (the sender against what it just encoded, the receiver against what
+            # arrived), and which of them exists is decided per side below.
             irt_in = topic
 
     # The wrapper is last, always. Its `seq` and send stamp describe whatever it
@@ -2607,7 +2648,11 @@ def func(
         thr_items = [(p["thr_in"], p["throttle"]) for p in out_pipes if p["thr_in"]]
         ipx_items = [(p["ipx_in"], p["pixel"]) for p in out_pipes if p["ipx_in"]]
         it_items = [(p["it_in"], p["transport"]) for p in out_pipes if p["it_in"]]
-        irt_items_local = [(p["irt_in"], p["transport"]) for p in out_pipes if p["irt_in"]]
+        # Sender-side reverse transport: this peer decodes what it just encoded,
+        # so the machine that sends can see what the receiver will get.
+        irt_items_local = [
+            (p["irt_in"], p["transport"]) for p in out_pipes if p["irt_in"] and p["transport"].local_republish
+        ]
 
         # Compression happens on the sender side for topics marked with processing.compress
         comp_topics = _dedup_keep_order([p["comp_in"] for p in out_pipes if p["comp_in"]])
@@ -2660,15 +2705,15 @@ def func(
         _assert_max("it", it_items, 4)
         _assert_max("nor", nor_items, 4)
 
-        # Remote-side reverse transport is configured (if requested via local_republish) on the receiver, too.
+        # Receiver-side reverse transport: this peer decodes what arrived, which
+        # is the copy the receiving application reads (see `_delivered_topic`).
         irt_items_remote = []
         for e, p in zip(in_entries, in_pipes):
-            if not p["irt_in"]:
-                continue
             tspec = p["transport"]
-            assert tspec is not None
+            if not p["irt_in"] or not (tspec and tspec.remote_republish):
+                continue
             topic = _prefix_with_source_name_if_needed(local, remote, p["irt_in"])
-            irt_items_remote.append((topic, tspec.type))
+            irt_items_remote.append((topic, tspec))
 
         # Build plugin.yaml blocks
         blocks: List[PluginBlock] = []
@@ -2953,9 +2998,9 @@ def func(
                         if p.get("it_in")
                     ]
                     + [
-                        f'{p["irt_in"]}/raw'
+                        f'{p["irt_in"]}/{p["transport"].local_republish}'
                         for p in out_pipes
-                        if p.get("irt_in")
+                        if p.get("irt_in") and p["transport"].local_republish
                     ]
                 )
                 blocks.append(
@@ -3152,12 +3197,15 @@ def func(
                     raise ValueError(f"Unsupported transport type '{tspec.type}'")
             blocks.append(PluginBlock("it", items2))
 
-        # Merge reverse-transport config for (a) local reconstruction and (b) inbound remote topics (if requested).
+        # Merge reverse-transport config for (a) the sender's own preview of what
+        # it encoded and (b) the decode of what arrived. Both run on *this* peer;
+        # what differs is which copy they decode and which transport the session
+        # asked each of them to publish in.
         irt_all: List[Tuple[str, str, str]] = []
         for t, tspec in irt_items_local:
             assert tspec is not None
-            irt_all.append((t, tspec.type, "raw"))
-        irt_all.extend((topic, ttype, "raw") for topic, ttype in irt_items_remote)
+            irt_all.append((t, tspec.type, str(tspec.local_republish)))
+        irt_all.extend((topic, tspec.type, str(tspec.remote_republish)) for topic, tspec in irt_items_remote)
         _assert_max("irt", irt_all, 4)
         if irt_all:
             items2 = [("irt", True)]

{rosotacom_dev-2.5.dev39 → rosotacom_dev-2.5.dev40}/src/rosotacom_dev.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rosotacom-dev
-Version: 2.5.dev39
+Version: 2.5.dev40
 Summary: Host CLI for ROS OTA communication sessions.
 Author: develNor
 License-Expression: BSD-3-Clause

rosotacom_dev-2.5.dev40/src/rosotacom_dev.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "2.4",
+  "distance": 40,
+  "node": "g679b8af8945b83eea3c582a4e0db6916592635bc",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-08-17"
+}

{rosotacom_dev-2.5.dev39 → rosotacom_dev-2.5.dev40}/tests/unit/test_session_pipeline.py

@@ -57,9 +57,9 @@ def _pipeline(processing: dict, base: str = "/camera/image", msg_type: str = "se
 
 
 def _ffmpeg(**extra: object) -> dict:
-    spec = {"type": "ffmpeg", "local_republish": True}
+    spec: dict = {"type": "ffmpeg", "local_republish": "raw", "remote_republish": "raw"}
     spec.update(extra)
-    return {"transport": spec}
+    return {"transport": {k: v for k, v in spec.items() if v is not None}}
 
 
 # ---------------------------------------------------------------------------
@@ -88,12 +88,51 @@ def test_wrapping_a_transport_does_not_rename_the_delivered_topic() -> None:
 
 
 def test_transport_without_republish_delivers_the_unwrapped_packet() -> None:
-    _, pipe = _pipeline({**_ffmpeg(local_republish=False), "use_ota_wrapper": True})
+    _, pipe = _pipeline(
+        {**_ffmpeg(local_republish=None, remote_republish=None), "use_ota_wrapper": True},
+    )
 
     assert pipe["irt_in"] is None
     assert generator._postprocessed_topic(pipe, pipe["final"]) == "/camera/image/ffmpeg"
 
 
+# ---------------------------------------------------------------------------
+# the two reverse republishes are separate decisions (#276)
+# ---------------------------------------------------------------------------
+
+
+def test_the_receiver_decode_names_the_delivered_topic_and_type() -> None:
+    """`remote_republish` decides what the receiving application subscribes to."""
+    entry, pipe = _pipeline(_ffmpeg(remote_republish="compressed"))
+
+    assert generator._postprocessed_topic(pipe, pipe["final"]) == "/camera/image/ffmpeg/compressed"
+    assert generator.REPUBLISH_OUTPUT_TYPES["compressed"] == "sensor_msgs/msg/CompressedImage"
+    # What crosses the link is still the encoded packet; only the decode changed.
+    assert generator._final_topic_type(entry, pipe) == generator.TRANSPORT_OUTPUT_TYPES["ffmpeg"]
+
+
+def test_the_senders_preview_does_not_decide_the_delivered_topic() -> None:
+    """`local_republish` runs on the sending machine and never reaches the receiver."""
+    _, pipe = _pipeline(_ffmpeg(local_republish="raw", remote_republish="compressed"))
+
+    assert generator._postprocessed_topic(pipe, pipe["final"]) == "/camera/image/ffmpeg/compressed"
+
+
+def test_a_sender_only_preview_delivers_the_packet() -> None:
+    """A preview on the sender leaves the receiver with what crossed the link."""
+    _, pipe = _pipeline(_ffmpeg(remote_republish=None))
+
+    # The encoded topic still exists -- the sender decodes it locally --
+    # but nothing decodes it on the receiving side.
+    assert pipe["irt_in"] == "/camera/image/ffmpeg"
+    assert generator._postprocessed_topic(pipe, pipe["final"]) == "/camera/image/ffmpeg"
+
+
+def test_a_republish_must_name_a_known_image_transport() -> None:
+    with pytest.raises(ValueError, match="remote_republish"):
+        _pipeline(_ffmpeg(remote_republish="jpeg"))
+
+
 def test_trickle_republishes_the_unwrapped_topic() -> None:
     """#259: `<latched>/ota_stamped/trickle` is a name no application subscribes to."""
     _, pipe = _pipeline(

{rosotacom_dev-2.5.dev39 → rosotacom_dev-2.5.dev40}/tests/unit/test_status_overview.py

@@ -720,7 +720,8 @@ def test_pipeline_spec_exposes_decoded_reverse_transport_stage(tmp_path: Path) -
                 "processing": {
                     "transport": {
                         "type": "ffmpeg",
-                        "local_republish": True,
+                        "local_republish": "raw",
+                        "remote_republish": "raw",
                         "gop_size": 4,
                         "bit_rate": 500000,
                     }
@@ -744,6 +745,86 @@ def test_pipeline_spec_exposes_decoded_reverse_transport_stage(tmp_path: Path) -
     assert "metric_stage_topics: /com/in/b/camera/image/ffmpeg,/camera/image/ffmpeg,/camera/image/ffmpeg/raw" in plugin
 
 
+def test_a_compressed_receiver_decode_names_the_stage_and_its_type(tmp_path: Path) -> None:
+    """#276: the decoded twin follows `remote_republish`, on the name and the type.
+
+    An uncompressed `sensor_msgs/Image` twin is ~3 MB per frame at 1280x800 and
+    dominates any `record -a` on the receiving machine; a session that asks for
+    `compressed` must get a `CompressedImage` under `.../ffmpeg/compressed`, and
+    the status overview has to report that stage, not the one it used to assume.
+    """
+    cfg = _heartbeat_cfg()
+    cfg["shared"]["use_heartbeat"] = False
+    cfg["topics"] = {
+        "b_to_a": [
+            {
+                "topic": "/camera/image",
+                "type": "sensor_msgs/msg/Image",
+                "processing": {
+                    "transport": {
+                        "type": "ffmpeg",
+                        # Deliberately asymmetric: the sender keeps pixels for a
+                        # local look, the receiver takes the small copy.
+                        "local_republish": "raw",
+                        "remote_republish": "compressed",
+                        "gop_size": 4,
+                        "bit_rate": 500000,
+                    }
+                },
+            }
+        ]
+    }
+
+    _generate(cfg, tmp_path)
+
+    spec = yaml.safe_load((tmp_path / "a" / "pipeline_spec.yaml").read_text(encoding="utf-8"))
+    inbound = next(topic for topic in spec["topics"] if topic["base"] == "/camera/image")
+    stages = {stage["stage"]: stage for stage in inbound["stages"]}
+    assert stages["native_in"]["topic"] == "/camera/image/ffmpeg/compressed"
+    assert stages["native_in"]["type"] == "sensor_msgs/msg/CompressedImage"
+
+    receiver_plugin = (tmp_path / "a" / "plugin.yaml").read_text(encoding="utf-8")
+    assert "irt_1_out_transport: compressed" in receiver_plugin
+
+    # The sender's own preview is a separate decision and keeps its own format.
+    sender_plugin = (tmp_path / "b" / "plugin.yaml").read_text(encoding="utf-8")
+    assert "irt_1_out_transport: raw" in sender_plugin
+
+
+def test_a_receiver_without_a_decode_gets_no_reverse_transport(tmp_path: Path) -> None:
+    """A sender-side preview must not put a decoder on the receiving peer."""
+    cfg = _heartbeat_cfg()
+    cfg["shared"]["use_heartbeat"] = False
+    cfg["topics"] = {
+        "b_to_a": [
+            {
+                "topic": "/camera/image",
+                "type": "sensor_msgs/msg/Image",
+                "processing": {
+                    "transport": {
+                        "type": "ffmpeg",
+                        "local_republish": "raw",
+                        "gop_size": 4,
+                        "bit_rate": 500000,
+                    }
+                },
+            }
+        ]
+    }
+
+    _generate(cfg, tmp_path)
+
+    receiver_plugin = (tmp_path / "a" / "plugin.yaml").read_text(encoding="utf-8")
+    assert "irt_1_topic" not in receiver_plugin
+    sender_plugin = (tmp_path / "b" / "plugin.yaml").read_text(encoding="utf-8")
+    assert "irt_1_out_transport: raw" in sender_plugin
+
+    spec = yaml.safe_load((tmp_path / "a" / "pipeline_spec.yaml").read_text(encoding="utf-8"))
+    inbound = next(topic for topic in spec["topics"] if topic["base"] == "/camera/image")
+    stages = {stage["stage"] for stage in inbound["stages"]}
+    assert "native_in" not in stages
+
+
 def test_reverse_transport_raw_stage_uses_sensor_image_type_for_compressed_source(tmp_path: Path) -> None:
     cfg = _heartbeat_cfg()
     cfg["shared"]["use_heartbeat"] = False
@@ -758,7 +839,8 @@ def test_reverse_transport_raw_stage_uses_sensor_image_type_for_compressed_sourc
                     "drop": {"drop_count": 1, "window_size": 2},
                     "transport": {
                         "type": "ffmpeg",
-                        "local_republish": True,
+                        "local_republish": "raw",
+                        "remote_republish": "raw",
                         "gop_size": 4,
                         "bit_rate": 500000,
                     },

rosotacom_dev-2.5.dev39/src/rosotacom_dev.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "2.4",
-  "distance": 39,
-  "node": "g17e7c753489cb153f8066e2911d37fdd85dcdb2f",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-08-14"
-}