System designTroubleshooting

RViz2 has topic data but no image: QoS, fixed frame, release

ros2 topic echo has data but RViz2 shows no image: fix the QoS reliability match, the Fixed Frame TF, then the rviz2 Foxy release 6 regression.

LumaSpec Vision10 min read Share on LinkedIn

On this page 10 sections
  1. 01What the echo output already proves
  2. 02Step 1: match the display's QoS reliability to the publisher
  3. 03Step 2: point the Fixed Frame at a real TF frame
  4. 04Step 3: rule out the rviz2 Foxy release 6 regression
  5. 05Worked example: a 640 x 480 rgb8 stream is not a bandwidth problem
  6. 06How to verify each fix
  7. 07When the three-step ladder is the wrong ladder
  8. 08Checklist before you touch hardware
  9. 09From bench camera to production hardware
  10. 10Questions

ros2 topic echo prints headers, timestamps and pixel bytes on your image topic, but the RViz2 image display stays empty. This walkthrough is for anyone bringing up a camera under ROS 2 — a bench depth camera or an industrial camera on a vision controller host. You will run three checks in order of probability: the QoS reliability match, the Fixed Frame and its TF path, and the rviz2 package build. Each step names the test that isolates the cause, the fix, and the arithmetic that tells you when to leave the hardware alone.

What the echo output already proves

An echoed image message carries most of the diagnosis in its header. In the case this ladder is drawn from, ros2 topic echo /camera/color/image_raw printed frame_id: camera_color_optical_frame, height: 480, width: 640, encoding: rgb8, step: 1920 and a stream of pixel bytes, with stamp values advancing in sec and nanosec.

That output proves three things at once. The driver is publishing. Complete messages are reaching your host over the cable and interface you already have. And a subscription to this topic can succeed on this machine. The blank panel therefore lives between RViz2's subscription and its renderer — not in the camera, not in the cable.

Step 1: match the display's QoS reliability to the publisher

A ROS 2 connection only forms when the publisher's offered reliability satisfies what the subscriber requests. Camera drivers usually publish image streams best effort — the profile ROS 2 defines for sensor data. If the image display requests reliable delivery, the middleware never joins the two endpoints: zero frames arrive, the panel stays blank, and there is no error dialog. Echo keeps printing, which is exactly the signature you are seeing.

Test. Ask the ROS 2 CLI for the topic's info in verbose form and read the reliability listed for the publisher endpoint. If the publisher is best effort and your display requests reliable, this is your cause. The command-by-command version, including the depth-stream variant, is in RViz2 image topic published but not displaying: fix the QoS mismatch.

Fix. In the image display's topic settings, set the display's reliability to best effort to match the publisher, then reselect the topic so the display re-subscribes.

Decision. A reliable publisher serves both settings. If the verbose output already shows a reliable publisher, QoS is not the cause — move on to the frame check.

Step 2: point the Fixed Frame at a real TF frame

The image display renders everything in the Fixed Frame, and it needs a TF chain from the image's frame_id to that frame. RViz2 commonly opens with map as the Fixed Frame — a frame a bare camera bring-up never publishes — and the display's status field then names a frame that does not exist.

Test and fix. Set the Fixed Frame to a frame the camera's TF tree actually publishes. In the case above, camera_link is the camera's root frame and camera_color_optical_frame its optical child, so either end of that chain works once TF is running.

Decision. If the image appears with the Fixed Frame on the frame_id but not on camera_link, the TF link between them is missing — publish that transform, statically if the camera never moves. No image in either setting means you continue to the build check.

Step 3: rule out the rviz2 Foxy release 6 regression

When the reliability matches and the frame exists, the remaining suspect is the renderer itself. Foxy's rviz2 release 6 package carried an image-display regression: topics echoed fine, QoS and frames checked out, and the panel still rendered nothing. Users on that build restored images by removing release 6 and installing the release 5 package of the same rviz2; the matching tracker entry is ros2/rviz#782.

Test. Ask your package manager which rviz2 build is installed; on Foxy, the release 6 build is the suspect. Also confirm you launch with ros2 run rviz2 rviz2 — a 30-second check that rules out a stale shell alias before you touch packages.

Fix. Install the release 5 build and hold it, so the next update does not quietly reinstall release 6.

Decision. On distros after Foxy this specific regression is history. A matched QoS and a valid frame on a modern build points at the host's renderer instead — the section below on the wrong ladder covers that.

Worked example: a 640 x 480 rgb8 stream is not a bandwidth problem

Inputs, taken from the echoed header: width 640 px, height 480 px, encoding rgb8 (3 channels at 8 bits, so 3 B per pixel), step 1920 B. The header does not carry the frame rate; 30 fps is the usual default for this class of color stream, and the conclusion holds anywhere from 15 to 60 fps.

The rule in words: the step already contains one full row, so bytes per frame is step times height, and the data rate is that times the frame rate, converted to bits.

bytes per frame = step × height data rate (bit/s) = bytes per frame × frames per second × 8

The arithmetic:

  • Row check: 640 px × 3 B/px = 1920 B, equal to the printed step, so rows arrive complete.
  • Frame size: 1920 B × 480 = 921,600 B, about 0.92 MB per frame.
  • At 30 fps: 921,600 × 30 = 27,648,000 B/s ≈ 27.6 MB/s, which is 27.6 × 8 ≈ 221 Mbit/s.
  • Headroom: 221 of 1,000 Mbit/s is about 22% of a gigabit link, and 221 of 5,000 Mbit/s is about 4% of USB 3. Even 60 fps only doubles the rate to roughly 442 Mbit/s, still under half of gigabit.

For contrast, a 20-megapixel rgb8 stream at 30 fps needs 20,000,000 px × 3 B × 30 × 8 ≈ 14.4 Gbit/s. That one really is a link problem, it belongs on 10GigE, and the data must be sized before the first cable — full resolution image capture is slow or stalls: size the data first works that case.

Decision. With echo printing headers, a stream of roughly 221 Mbit/s cannot be failing on transport. The camera, cable and interface are proven; run the three display-path checks and leave the hardware alone. Reopen the bandwidth question only when step × height × fps × 8 approaches your link's capacity.

How to verify each fix

  • QoS. After matching reliability and reselecting the topic, frames render within a second or two at 30 fps, and the display's status field drops its warning.
  • Frame. Scroll the echo output: consecutive stamp values advance by about 33 ms at 30 fps (1 ÷ 30 s = 33.3 ms), confirming steady delivery without extra tools.
  • Build. After a rollback, relaunch ros2 run rviz2 rviz2 and re-add the image display before judging it.

When the three-step ladder is the wrong ladder

Four cases sit outside the ladder, and each has its own fix:

  • The host cannot render. QoS matched, frame valid, known-good build, still nothing — check the machine's GPU. A GPU-starved or headless host draws a blank panel with everything else correct; run RViz2 on a desktop with a working GPU, or view it remotely, as RViz2 shows a blank image on a Jetson works through.
  • RViz2 crashes on a topic change. That is a teardown-order defect, not a display-settings problem: Rviz crash changing image topic: fix the mutex teardown order.
  • The image renders but arrives scrambled. Frames out of order or frozen point at the grab and the link, not at QoS: camera image stream out of sync.
  • You echo a different topic than you display. Remapped or namespaced node names publish under unexpected names; find what the node really publishes, as ROS 2 camera topic missing shows.

Depth streams add one more variant: a depth image that renders only black, or blinks, is the same QoS mismatch on the depth topic — depth image blinking black in rviz covers it.

Checklist before you touch hardware

  1. ros2 topic echo prints headers at a steady rate — driver, cable and interface proven.
  2. Display reliability is best effort wherever the publisher is best effort — the connection can form.
  3. The Fixed Frame exists in the running TF tree, or equals the image's frame_id — the transform path exists.
  4. The rviz2 build is known good (on Foxy: release 5, not release 6) — the renderer works.
  5. The host has a working GPU, and you launched with ros2 run rviz2 rviz2.

All five pass and the panel is still blank? Now swap the camera data cable for a known-good one and try another port — and if echo stops printing at the same time, you have found a real transport fault.

From bench camera to production hardware

The same three checks govern a ROS 2 node publishing from an industrial camera. Choose the sensor among the area scan cameras, give it a host with the LAN and USB 3 ports the stream needs among the vision controllers, and size the data before the first cable — the worked example above is the two-minute version of that sizing. Start in the camera finder or the system configurator, read more bring-up write-ups on the systems topic page, or ask us to review the set-up.

Questions

Why does ros2 topic echo show data while RViz2 stays blank?

Because the two tools ask for different things. Echo prints whatever arrives, while the image display requests a specific reliability level and a TF path before it draws anything. When either request cannot be satisfied, DDS never joins the endpoints: zero frames reach the renderer, with no error dialog. Image, depth and camera_info topics from camera drivers are typically best effort, so the display must come down to best effort to match them.

Which Fixed Frame should an image display use?

On a bare camera bring-up, the safest choice is the frame_id printed in the echo header, because the display then needs no transform at all. Once the camera joins a robot, prefer a frame the robot's TF publisher provides, such as camera_link or the robot base, so the image lines up with the rest of the view. The rule stays the same: the Fixed Frame must exist in TF and connect to the image's frame_id.

How do I roll rviz2 back to Foxy release 5?

Ask your package manager which rviz2 build is installed, install the earlier release 5 build of the same package, and hold it so the next update does not reinstall release 6. On distros after Foxy, read the rviz2 changelog for image-display fixes before rolling anything back, since that regression belongs to Foxy's release 6. Relaunch with ros2 run rviz2 rviz2 afterwards and re-add the display before judging it.

Could the camera, cable or link still be the cause?

Not while echo is printing headers. The echoed message proves complete frames are arriving: at 640 x 480 rgb8 and 30 fps that is about 221 Mbit/s, roughly a fifth of a gigabit link. Change cables only after the QoS, Fixed Frame and rviz2 build checks all pass, or when echo itself stops updating — then the fault has moved from the display path to the transport, and a known-good cable is the first swap.

Do depth and point cloud displays fail the same way?

Yes. Depth and point cloud topics from the same driver carry the same best-effort reliability, and their displays make the same reliability and frame requests. Run the identical two checks on the depth topic before touching the camera's depth settings: a depth image that renders black or blinks is most often the QoS mismatch again, and point clouds with the same mismatch simply stay absent.