Camera preview shows a gray image: fix the format mismatch

You open a color viewer example, the pipeline starts without errors, and the window fills with a uniform gray plane, a green-tinted haze, or scrambled bands. The log shows the stream running, occasional frame timeout warnings, and a note that metadata lacks timestamps. This guide walks you through diagnosing a gray camera preview caused by a pixel format mismatch: how to read what the camera actually sends, why the viewer renders it wrong, and how to fix it on the host side. It applies to any machine-vision camera or 3D sensor whose color stream is decoded by your own code.

The symptom and what it tells you

A flat gray or tinted preview with no camera errors almost always means the bytes are arriving but being interpreted in the wrong pixel format. The classic pattern in an SDK log looks like this: the code requests one format, and the backend negotiates another.

When the viewer assumes BGR (three bytes per pixel, interleaved) but the buffer holds YUYV (luminance shared between pixel pairs, chroma subsampled), the luminance channel dominates every interpreted pixel and the image collapses toward a flat gray. A green tint is the tell-tale of YUV data read as RGB, because the Y byte lands where the display expects the G byte. Scrambled diagonal banding instead points to raw Bayer data displayed without demosaicing, the same family of problem covered in Unsupported Bayer pixel format: diagnose a blank preview.

The timeout warnings in the log are usually a secondary effect: the wait time is short, the first color frames are delayed while conversion spins up, and the metadata parser reports missing timestamps. Fix the format first; the warnings often disappear with it.

Likely causes, in order of probability

1. Backend format differs from the requested format. The driver cannot deliver BGR natively, falls back to YUYV, and the example's display path does not convert. This is the most common cause.
2. Host-side conversion missing or wrong. The code copies the frame buffer straight into the display surface with no YUYV-to-BGR step, or uses a stride in bytes that ignores the two-bytes-per-pixel packing.
3. Mixed or stale SDK environment. Two SDK versions installed in one Python environment, or a viewer example older than the SDK, can silently pick a different conversion path. Rebuilding the environment cleanly has fixed reports exactly like this one.
4. The camera is mono. A mono sensor produces a gray preview by design. Check the sensor's spec before assuming a fault.

Step 1: Read the negotiated format from the log

Run the viewer and find the stream start line. It names the stream type, the format your code asked for, the resolution, the frame rate, and the backend format the driver actually chose. Write both down. If they differ, you have found the mismatch: the frames on the wire are in the backend format, and any display code that assumes the requested format is wrong.

Also check the frame size implied by the numbers. YUYV stores two bytes per pixel, BGR three. For a 640 × 360 stream, YUYV is 640 × 360 × 2 = 460,800 bytes per frame. If your code allocates 640 × 360 × 3 = 691,200 bytes, the buffer sizes alone prove the interpretation is wrong.

Step 2: Fix the format at the source or the host

You have two clean options.

Option A: request a display-ready format. Ask the pipeline for BGR or RGB output and let the SDK convert. This is the simplest fix and costs extra conversion work or bandwidth. If the interface is tight, read the trade-offs in the guide on optimizing camera bandwidth: grayscale versus resolution versus framerate.

Option B: keep the native format and convert on the host. Take the YUYV frame and convert with an optimized path:

Use the SDK's built-in converter or a vectorized library rather than a per-pixel Python loop; a per-pixel loop at 30 fps will not keep up and produces the same timeout warnings. For Bayer sources, see Packed Bayer 12-bit conversion to a 16-bit image for the byte-layout pitfalls.

Step 3: Rebuild the capture environment cleanly

If the negotiated format matches the request and the conversion code is correct, suspect the environment. Create a fresh virtual environment, install only the vendor SDK from its official package, and rerun the unmodified viewer example. A mixed environment with two SDK builds is a known source of gray previews, because the example and the library disagree about defaults.

Step 4: Verify the fix

1. Point the camera at a strongly colored object, ideally something red or blue.
2. Confirm the preview shows that color, not a gray or green version of it.
3. Save one frame to disk and inspect its byte size: width × height × bytes-per-pixel must match the format you now assume.
4. Watch the log for one minute; timeout warnings should stop or drop to occasional.
5. Sweep something dark across the field of view to confirm luminance tracks correctly.

Choosing hardware that avoids the problem

Most modern area scan cameras deliver standard formats that common viewers handle natively. The area scan cameras finder lets you filter by interface and color, and mono models sidestep conversion entirely when you only need gray data.

For depth-plus-color tasks, a ToF or structured-light sensor with a rectified color stream avoids manual registration. The 3D sensors category covers laser profilers, stereo cameras and ToF devices; registration itself is covered in Depth to color registration: raw versus rectified frames.

If inspection should run without a host PC at all, a smart camera does its own processing and hands you results over Ethernet, removing the host conversion step completely.

When the usual answer is wrong

• Gray is correct. On a mono camera, gray output is the design, not a fault. The MV-CS200-10UM is a mono USB3 model; a gray preview from it means everything works.
• The stream is fine and the display is the fault. A remote desktop session or a window scaled by the OS can wash out a preview. Check on the local display before touching camera settings.
• The format negotiation never happened. If the viewer opens before the pipeline configures the stream, it can render an uninitialized buffer. This failure mode and its timing fix are covered in Vision format selection timing: fix PLC trigger races, and rejected modes in USB camera format negotiation: diagnose rejected modes.

Checklist

• [ ] Log shows requested format and backend format; note any difference.
• [ ] Frame byte size equals width × height × bytes per pixel of the format you assume.
• [ ] Conversion path matches the backend format, not the requested one.
• [ ] Timeouts raised to 500-1000 ms while diagnosing.
• [ ] Environment rebuilt with a single SDK version before changing camera settings.
• [ ] Camera confirmed color, not mono, before treating gray as a fault.
• [ ] One frame saved and inspected on disk to prove the pipeline.

If the mismatch persists after these steps, the camera finder and the system configurator help you pick a camera whose native output matches your software, or contact our team through the contact page with your stream log.