Interprocess External-Endpoint Demo

Watch two separate processes exchange a live CUDA BGRA Tensor stream through a catalog-backed external endpoint. The sender captures RG10 Bayer frames from a V4L2 camera with V4L2UserPtrSourceOp, converts them to BGRA on the GPU, and publishes one stream. The receiver attaches to that endpoint and displays the frames continuously.

Custom application support

Your capture and processing stages may need to run as separate applications. Contact RidgeRun to adapt this example to your camera and processing pipeline.

This example connects the external endpoint concepts to a RidgeRun application. Read External Endpoints and Endpoint Catalogs before changing the endpoint contract.

Prerequisites

Prepare the Holoscan SDK and RidgeRun module environment using Holoscan RidgeRun Build and Installation. The application targets aarch64 and needs an NVIDIA GPU with a working CUDA runtime, a V4L2 camera available at /dev/video0 whose driver supports RAW10/RG10 capture with V4L2_MEMORY_USERPTR, and an accessible X11 display with DISPLAY configured for the receiver. Docker with the NVIDIA runtime is also required when using the wrapper's container build path.

What you will learn

How a sender captures live RG10 Bayer frames with V4L2UserPtrSourceOp.
How the sender converts the live frames to BGRA and publishes one external endpoint.
How a receiver selects a catalog entry through an external source operator.
How the sender and receiver keep a single live stream running across the process boundary.
Which catalog, discovery, display, and lifetime conditions must match.

Build and run

Clone the repository that contains the Interprocess application:

export HOLOSCAN_SDK_INSTALL_DIR="/absolute/path/to/holoscan-sdk/install"
WORKSPACE="$HOME/holoscan-5.0"
HOLOSCAN_RIDGERUN="$WORKSPACE/holoscan-ridgerun"
mkdir -p "$WORKSPACE"
git clone https://github.com/ridgeRun/holoscan-ridgerun.git "$HOLOSCAN_RIDGERUN"
cd "$HOLOSCAN_RIDGERUN"
./holoscan_ridgerun build interprocess receiver
./holoscan_ridgerun build interprocess sender

Follow the workflow

Operators used

Operator	Role in this example
V4L2UserPtrSourceOp	Captures live RG10 Bayer frames from the V4L2 camera through CUDA-mapped USERPTR buffers.
RawBayerToBgraOp	Converts the captured Bayer frames to display-ready BGRA tensors on the GPU.
InterprocessSrcOp	Selects the live external endpoint and provides its Tensor frames to the receiver graph.
X11DisplayOp	Displays the live stream in the receiver process.

The sender owns one live-capture graph:

V4L2 camera (RG10) -> V4L2UserPtrSourceOp -> RawBayerToBgraOp -> external endpoint "video"

The receiver owns one graph with InterprocessSrcOp followed by X11DisplayOp. Both processes use the same JSON endpoint catalog. The wrapper's validate mode creates that catalog without opening the camera, and the sender and receiver modes use the same generated catalog path.

First create the catalog without opening the camera:

cd "$HOLOSCAN_RIDGERUN"
./holoscan_ridgerun run interprocess validate \
  --no-local-build \
  --docker-opts="--ipc=host --network=host"

Start the receiver in one terminal. The wrapper uses the receiver application's default options. The X11 socket and DISPLAY environment are passed into the receiver container:

cd "$HOLOSCAN_RIDGERUN"
./holoscan_ridgerun run interprocess receiver \
  --no-local-build \
  --docker-opts="--ipc=host --network=host --env DISPLAY=$DISPLAY --volume /tmp/.X11-unix:/tmp/.X11-unix:rw"

Start the sender in another terminal. The wrapper uses the sender application's default options. The camera device must be passed to Docker:

cd "$HOLOSCAN_RIDGERUN"
./holoscan_ridgerun run interprocess sender \
  --no-local-build \
  --docker-opts="--ipc=host --network=host --device=/dev/video0"

After the catalog exists, the sender waits for the receiver to attach before counting or publishing camera frames. If you need to override the application defaults, pass the desired application arguments through --run-args. For example:

# Receiver: override the frame size and polling interval
./holoscan_ridgerun run interprocess receiver \
  --no-local-build \
  --run-args="--width 1920 --height 1080 --poll-ms 5" \
  --docker-opts="--ipc=host --network=host --env DISPLAY=$DISPLAY --volume /tmp/.X11-unix:/tmp/.X11-unix:rw"

# Sender: override the camera, format, frame rate, and frame limit
./holoscan_ridgerun run interprocess sender \
  --no-local-build \
  --run-args="--device /dev/video0 --width 1920 --height 1080 --fps 60 --frame-limit 600" \
  --docker-opts="--ipc=host --network=host --device=/dev/video0"

The optional --frame-limit 600 argument causes the sender to publish the completion signal and the receiver to close cleanly; omit it to run until the user stops the application.

Expected result

The receiver displays the live camera stream. When the optional --frame-limit 600 argument is used, the sender publishes sender_done after the synchronized frame limit and the receiver closes cleanly. Without the frame limit, both processes continue until stopped with q, Escape, a closed display window, or Ctrl-C. A camera that is not available through the device selected by the sender defaults, a capture mode that is not RAW10/RG10 USERPTR, different catalog paths, or an inaccessible X11 display prevents a useful observation.

Related examples and concepts

Examples

HoloMQ Example shows direct interprocess buffer exchange.
Descriptor-Tensor External Topic Example shows a schema-backed external round trip.
V4L2UserPtrSourceOp documents the live camera source used by the sender.
InterprocessSrcOp documents the external source used by the receiver.

Concepts

External Endpoints and Endpoint Catalogs explains catalogs and Tensor boundary contracts.
Standalone ChannelRuntime Clients explains catalog-backed clients.
Copy Paths and Memory Conversion explains bounded staging and transfer decisions.

Source The application source is in the Interprocess application directory. The sender captures and publishes the live stream, while the receiver imports and displays it. The V4L2 USERPTR source operator provides the camera input, the RawBayerToBgraOp converts the Bayer frames, and the InterprocessSrcOp provides the catalog-backed Tensor input.

Official documentation

NVIDIA Holoscan SDK official documentation provides the current application and external communication reference.

❯