Skip to main content

durchblick-relay

A Durchblick node that brings image streams from other PCs into the rings of this PC. You start one relay per PC. It relays every stream that a node on its PC reads from another PC: it receives the stream once, decodes each frame once and offers it to every node on the PC through shared memory and GPU memory. Decoding and publishing take 3.3 ms per frame.

The problem it solves

A ring is the memory in which a publisher keeps its newest frames for the readers on its own PC. A reader on another PC cannot open that memory. It receives the stream over the network as compressed or raw.

With n readers of one remote stream on a PC, the stream crosses the network n times and the PC decodes every frame n times. No reader receives the frame in GPU memory.

The relay receives the stream once and decodes it once. It then publishes the frames under the same stream name into a host ring and a CUDA ring on its PC. The readers need no change and no option: a reader with the transport auto asks the relay of its PC for the stream and moves to the relay's ring.

flowchart LR
  subgraph A["PC A"]
    cam[camera node]
  end
  subgraph B["PC B"]
    relay[durchblick-relay]
    ring[("host ring and CUDA ring")]
    n1[node 1]
    n2[node 2]
    n3[node 3]
  end
  cam -- "compressed, once over the network" --> relay
  relay -- "decodes once" --> ring
  ring --> n1
  ring --> n2
  ring --> n3

The relay is not specific to one camera. It relays any remote image stream.

What it publishes

Topic Message type Content
<stream> on the transports shm and cuda image stream The frames of the source, decoded, with the source's header and the attachments seq and source.
<stream>/info info record The relay's record with relayed_from: <source host>.
<camera>/diagnostics diagnostic_msgs/DiagnosticArray Status relay_<stream> once per second: state, rate, delays and counters.

<camera> is the stream's name without its last part. The relay never offers raw, compressed or camera_info. Readers receive those from the source.

Requirements

  • Durchblick 0.4. The readers need 0.4 too. The CMake build also needs Durchblick's C++ library.
  • For the CMake build: CMake 3.22 or newer, Ninja and a C++20 compiler. Installing the wheel needs none of them.
  • For GPU decoding with the CMake build: an NVIDIA GPU and a CUDA 12 toolkit with nvJPEG. Without them the relay decodes on the CPU and fills the host ring only.
  • A Zenoh router (zenohd) on the PC, as for every Durchblick node.

Install

With pip, install Durchblick's extra relay. It brings the wheel blick-relay, which contains the relay program and libzenohc.so. The command blick relay starts the program.

pip install "blick[relay]"
blick relay --help

The wheel runs on Linux on x86-64 with glibc 2.28 or newer (manylinux_2_28). It decodes on the CPU only. It contains libjpeg and libpng and takes glibc, libstdc++ and zlib from the system. PyPI has only this wheel and no source distribution of blick-relay, because the program builds only against an installed Durchblick C++ library.

tools/build_wheel.sh builds the wheel as PyPI has it, in the image quay.io/pypa/manylinux_2_28_x86_64. It builds zenoh-c from source, because the prebuilt zenoh-c needs glibc 2.34. The script's header lists what it needs.

For nvJPEG, or on a system that the wheel does not support, build the program with CMake:

cmake -S . -B build -G Ninja -DCMAKE_PREFIX_PATH=<durchblick install> \
  -DDURCHBLICK_RELAY_CUDA=ON -DCUDAToolkit_ROOT=<CUDA toolkit>
cmake --build build
cmake --install build --prefix build/install

Leave out the two CUDA options for a build without nvJPEG. Put build/install/bin on PATH, so that blick relay finds the program there. blick relay takes the installed wheel first and PATH second.

Run

Start one relay on each PC whose nodes read streams from other PCs.

durchblick-relay                # every stream that a reader on this PC asks for
durchblick-relay --cpu          # no GPU: host rings only
durchblick-relay --stream robot/ecam24/left robot/ecam24/right     # these streams also without a request

With the wheel, write blick relay in place of durchblick-relay. The options stay the same.

Option Default Meaning
--stream NAME ... none Streams that the relay relays from its start, also for readers that do not ask. See below.
--cuda-device N GPU 0 if the PC has one Decode with nvJPEG on GPU N and fill a CUDA ring and a host ring.
--cpu Decode on the CPU and fill the host ring only.
--connect HOST ..., --listen ENDPOINT ..., --zenoh-mode peer|client (also --mode) the PC's router at 127.0.0.1:7447 The Zenoh session.
--slots N 32 The number of ring slots. 32 slots hold about one second at 30 Hz.
--idle-ms MS 2000 The relay keeps a stream this long after its last reader left.
--prefer-raw off Take the source's raw form even where the source offers compressed.

A reader with the transport auto asks for a stream by itself. --stream is for readers that cannot ask: a reader with a fixed transport such as shm, or a reader with a Durchblick older than 0.3.60.

You can start the relay before or after the readers. A reader with the transport auto moves to the relay's ring when the relay starts, and back to the source's network transport when the relay stops.

A reader needs no option. ImageSubscriber(session, "robot/ecam24/left") takes the relay's ring like the ring of any local publisher. Its transport_reason then reads shm (...) or cuda (publisher on this GPU).

--help lists every option. Every option is also a read-only parameter of the node durchblick/relay_<host> (--node another name), which Durchblick's terminal interface (blick, tab Parameters) shows. --param NAME:=VALUE or --params-file FILE set them at the start.

Why it is fast

Without a relay, every reader decodes every frame. With the relay, the PC decodes and publishes each frame once in 3.3 ms, and a reader has the frame 5.1 ms after its capture stamp.

Change Effect
One subscription and one decode per stream for all readers on the PC The network load and the decode time no longer grow with the number of readers.
nvJPEG decodes a JPEG straight into GPU memory. Readers on the GPU receive a device array without an upload.
The relay downloads a frame to the host ring only while a reader of that ring exists. GPU-only readers cause no download.
The relay subscribes to the source only while a local reader exists. A stream that nobody reads costs no network traffic.

docs/performance.md has the measurement and explains the relay's status values.

Limits

  • We tested the relay on one machine only. We have not run it between two PCs, and we have not run relays on two PCs at the same time.
  • One relay per PC. A second relay on the same PC waits for each stream that the first one relays.
  • The relay handles image streams. It does not relay point clouds and it does not rectify.
  • The relay decodes every stream on one GPU. A reader on another GPU of the PC copies each frame from there.
  • The wheel decodes on the CPU only. We installed it with pip on Debian 12 (Python 3.10 and 3.12) and started its program on Ubuntu 22.04 and Ubuntu 24.04. Its tests passed on Ubuntu 24.04.

docs/design.md explains the reasons and lists the open work.

Documentation

Page Content
docs/design.md How the relay finds its source, republishes and avoids conflicts
docs/performance.md The measured delay and the status values on <camera>/diagnostics
docs/testing.md How to run the tests and what they check

Durchblick's concept pages explain the terms used here: rings, transports with its section "Relays", and sessions and routers.

Licence

The relay is licensed under the Apache License 2.0 (LICENSE). NOTICE names the copyright holder and the software of others in the wheel: zenoh-c with the Rust crates it is built from, libjpeg-turbo and libpng. Their licence texts are in licenses/ and in the wheel.

Metadata

Release files for blick-relay 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for blick-relay 0.3.1
File Interpreter ABI Platform Actions
blick_relay-0.3.1-py3-none-manylinux_2_28_x86_64.whl Python 3 none Linux glibc 2.28+ x86-64 Details for blick_relay-0.3.1-py3-none-manylinux_2_28_x86_64.whl

Release files / blick_relay-0.3.1-py3-none-manylinux_2_28_x86_64.whl

Download URL blick_relay-0.3.1-py3-none-manylinux_2_28_x86_64.whl
Size 7.6 MB
Tags Linux glibc 2.28+ x86-64 Python 3
SHA-256 checksum
How to use checksums
7aab2f6925cde960b17dfd5f43748e0fd8ef042a5ac213b57002f11799a3dea2
BLAKE2b-256 checksum
How to use checksums
8762e675f347736a186ea3af936f8ac19d35a63b29cd80384b8595e3b1a15eb8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.27 {"installer":{"name":"uv","version":"0.11.27","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for blick-relay 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.1 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page