The driver builds cleanly inside its container on the module, the vendor's SDK viewer shows live video, and ros2 topic list prints every promised topic — yet the RViz2 image display sits blank. The node is usually innocent. On a Jetson Orin Nano under JetPack 6.2.1 the GPU already carries the depth pipeline, and RViz2 renders its scene with OpenGL on the same silicon; when jtop reads the GPU near 97% with the CPU near 50%, the display starves before a frame reaches the screen. This guide gives the test order, the remote-visualization fix with the settings that must match, the network arithmetic for the streams you subscribe to, and the on-device options when a second machine is not allowed.
The symptom: everything works except RViz2
The failure has a shape. The vendor's viewer, run inside the same container, plays live video, so the sensor, its cable, the port and the container's device access are all good. The topic list is complete. RViz2 opens, accepts the topic, and paints nothing.
What changed between "video in the vendor tool" and "blank in RViz2" is a second GPU workload. Stereo 3D sensors push depth computation onto the module's GPU, and RViz2 then asks that same GPU to build an OpenGL scene for every arriving frame. Plain area scan cameras hit the same wall when a detection model or an encoder shares the silicon. Capture is alive; rendering starves. Whenever a window opens but shows nothing, isolate capture from rendering before touching the driver.
Five causes, in the order to test them
A blank image display has five realistic causes under this pattern. Test the simplest first; each takes less than a minute.
| What you observe | Likely cause | The test | What settles it |
|---|---|---|---|
| Vendor viewer works, topics publish, RViz2 blank on the module | GPU saturation | Run jtop with RViz2 open | GPU above about 90%, CPU with headroom |
| Blank on every machine, even a fresh workstation RViz2 | QoS mismatch | Read the topic's QoS policy | Publisher is Best Effort, display is Reliable |
| Topic listed but no rate on the wire | Node publishes nothing | Measure the publish rate on the module | No rate reading appears |
| RViz2 console prints "Failed to create an OpenGL context" | Graphics stack mismatch | Read the console at launch | The error line is present |
| Viewer renders on the host, black inside a container on the workstation | Container has no GPU | Run RViz2 on the host first | Host renders, container does not |
The QoS row is the most common cause overall: camera topics publish with Best Effort reliability, and a Reliable subscriber receives nothing at all — RViz2 image topic published but not displaying: fix the QoS mismatch shows the panel. A silent rate points at the publisher, and finding the topic name the node really publishes covers the naming traps. The OpenGL row is a graphics-stack failure rather than a load failure, a close cousin of OpenGL invalid value errors in depth viewers. The last row belongs to the remote machine, not the module: point clouds black inside a container walks the GPU passthrough settings.
The jtop reading that settles it
Run jtop on the module with the camera node running and RViz2 open beside it. The verdict you are looking for: the GPU pinned in the nineties while the CPU idles around half. Then run the rebound test. Close RViz2 and keep watching — the GPU bar falls within a second or two while the topics keep publishing. Open RViz2 again and the pin returns. That rebound is cause and effect, not coincidence, and it clears the driver.
The mechanism is simple: the module's GPU computes depth for the stereo pipeline, and RViz2 adds a full OpenGL scene per received frame. No RViz2 setting makes that light on a module this size. A GPU held at its ceiling also fights for clock recovery, and how the Orin Nano's GPU behaves under sustained load goes deeper on that side.
The fix: visualize from another machine
The driver stays where it is, inside its container on the module. Only the viewer moves.
- Install the same ROS 2 distribution family on a workstation or laptop — Humble against Humble, for example.
- Put both machines on the same switch. Router hops, subnets and VPN links break DDS discovery.
- Set the same domain in both shells:
export ROS_DOMAIN_ID=7in the module console and on the workstation. - From the workstation, run
ros2 topic list. The camera topics appear within a few seconds of discovery. - Measure the image topic's rate from the workstation; it should match the rate the camera node was configured to publish.
- Launch RViz2, add an Image display, pick the topic, and set Reliability to Best Effort in the display's QoS panel.
Frames now render on the workstation's GPU and the module keeps its headroom. Nothing camera-specific is needed at the remote end: no SDK, no driver, no container — DDS carries the frames over plain Ethernet.
Budget the link before you blame the software
Remote visualization moves the bottleneck from GPU to network, so size the link for the streams you actually subscribe to:
A worked example at one common stereo-camera mode, 1280 × 720:
- Color, RGBA8 at 4 bytes per pixel, 30 fps: 1280 × 720 = 921,600 pixels; × 4 B = 3.69 MB per frame; × 30 = 110.6 MB/s; × 8 ≈ 885 Mbit/s.
- Depth, 16-bit at 2 bytes per pixel, 30 fps: 921,600 × 2 B = 1.84 MB per frame; × 30 = 55.3 MB/s ≈ 442 Mbit/s.
- Both together: 110.6 + 55.3 = 165.9 MB/s ≈ 1,327 Mbit/s — past a Gigabit port.
- A point cloud, XYZ at 12 bytes per point, costs the same 1,327 Mbit/s at only 15 fps: 921,600 × 12 B = 11.06 MB; × 15 = 165.9 MB/s.
Count roughly 900 Mbit/s as the usable ceiling on a 1 Gbit/s port once UDP and IP headers are included. One color stream fits; color plus depth does not. Congestion does not blank the display — it shows up as torn or corrupt buffers on the remote side, the failure mode in corrupt depth buffers over remote ROS. If the link must stay Gigabit at full rate, publish a hardware-encoded stream from the module instead of raw frames; GPU hardware acceleration for FFmpeg on Jetson covers the encoder path.
Hardware for the remote end
The workstation's Ethernet port is now part of the vision system, so give it the same attention as the camera link. For one camera at reduced rate, any wired Gigabit port is enough; a PCIe card such as the LS-FGB-0004 gives the machine a dedicated Intel i210AT port for the camera LAN, keeping the stream off the office network.
- Interface
- GigE
For the color-plus-depth case in the worked example, a 2.5GigE adapter such as the MV-GE4004 clears the total with margin. Several cameras at once call for a quad-port 10GbE card such as the MV-GT2104 at the aggregation machine.
- Interface
- 2.5GigE
- Ports
- 4 ports
- Interface
- 10GigE
- Ports
- 4 ports
Both live with the frame grabbers and interface cards; the accessories finder filters by interface and port count, and the camera finder covers the imaging end of the station.
When a second machine is not allowed
Some benches have no second machine on the plant network. Three on-module options remain, in falling order of usefulness:
- Measure, do not render. The publish rate read on the module costs no GPU. A silent reading is a capture problem; a steady reading with a blank RViz2 is a rendering problem.
- Record, then replay. Capture the topics to a bag on the module and replay the bag into RViz2 on any machine later, where the GPU is free.
- Cut the stream. Halve the resolution and frame rate in the camera node before opening RViz2 on the module, and treat the session as a short debug look with skipped frames. Running a depth camera at low fps shows how much a lower rate buys back.
None of this turns on-device RViz2 into a monitoring tool. It stays a bench instrument.
Pre-flight checklist
Walk this list before you reorder hardware or rewrite the driver:
- Vendor viewer plays on the module — sensor, cable, port and container device access are proven good.
- jtop read with RViz2 open — a GPU pin with CPU headroom is the rendering verdict.
- Close-and-reopen rebound — the GPU falls when RViz2 closes and pins when it returns.
- Best Effort on every image and depth display — one Reliable display silences that topic in RViz2 alone.
- Same ROS_DOMAIN_ID and the same switch — discovery needs both.
- Remote rate matches the configured rate — proves the link, not just the topic list.
- Link budget computed — sum the streams you subscribe to before blaming lag on software.
The decision, case by case
- Vendor viewer works, topics publish, RViz2 blank on the module, GPU pinned: move RViz2 to another machine; no RViz2 setting fixes this on an Orin Nano class module.
- Blank on every machine: match the QoS — a Best Effort display against a Best Effort publisher — and the exact topic name.
- No rate on the wire: the publisher, not the viewer; fix the driver or its trigger first.
- "Failed to create an OpenGL context" in the console: reboot the module so the kernel and user-space graphics stack match again.
- Torn or corrupt frames on the remote side: recompute the link budget, drop to one stream, or fit a faster port at the workstation.
To go further, the system configurator walks a full station — camera, lens, light, controller — and the contact page reaches our applications team for a parts check on the remote end.
Questions
Why does the vendor's viewer show live video while RViz2 stays blank?
The vendor viewer talks to the camera through the SDK and draws one simple 2D surface per frame. RViz2 receives frames over DDS, converts them, and renders a full 3D OpenGL scene on top of whatever the camera pipeline already runs on the GPU. When the GPU is near its ceiling, the lightweight path lives and the expensive one starves, so a working vendor viewer beside a blank RViz2 is itself evidence of saturation.
Can I tune RViz2 to run on the Jetson itself?
No setting inside RViz2 makes its OpenGL rendering light enough to sit beside a depth pipeline on an Orin Nano class module. Halve the camera's resolution and frame rate, close every other display, and you get a short debug session with skipped frames, not a monitoring tool. Anything you would watch for a full shift belongs on a second machine, with the driver left on the module.
Is WiFi good enough for remote RViz2?
For a bench check, yes. Sensor topics use Best Effort, so a lost frame is skipped rather than queued: a weak WiFi link looks like dropped frames, never a frozen or blank window. For continuous monitoring, wire both machines to the same switch, so the rate reading on the workstation reflects the camera rather than the air.
What has to match between the module and the remote machine?
Three things: the same ROS 2 distribution family, the same ROS_DOMAIN_ID value in both shells, and the same Layer-2 network so DDS multicast discovery works, meaning a switch rather than a router hop or VPN. Firewalls must allow the UDP traffic. RViz2 itself needs no camera SDK, driver or container on the remote side.
Does a faster module fix it?
It moves the threshold, not the principle. A larger module finishes the depth pipeline with more headroom, so RViz2 renders, until you add the detection model you were saving that headroom for. Size the module for the processing that must run on it, and plan from day one for visualization to happen somewhere else.
How many streams can one Gigabit link carry for remote RViz2?
One uncompressed 720p30 color stream, at about 885 Mbit/s, or color plus depth if you halve the frame rate, which lands near 660 Mbit/s. Past that, subscribe to a compressed topic or fit a 2.5GigE or 10GbE port at the workstation; the arithmetic is in the link-budget section.


