You set the sensor to RAW10, the frame arrives, and every pixel sits between 0 and 255. The image looks correct, the histogram looks healthy, but the two low bits you asked for are nowhere. In almost every case the sensor is fine: MIPI CSI-2 packs four 10-bit pixels into five bytes, and your viewer is reading only the four high-bit bytes as if the buffer were plain 8-bit. This guide is for engineers bringing up MIPI sensor modules through USB3 bridges or SoC CSI receivers who need the missing bits back. You will compute the packed row size, recognize the 255 cap and its artifacts, unpack the buffer with tested code, and know when to move to a camera that declares its pixel format.
The diagnosis: the data is fine, the readout is 8-bit
A 10-bit pixel holds values from 0 to 1023. If your maximum is exactly 255 and the image itself is usable, the sensor delivered RAW10 and your software kept only bits [9:2] of each pixel. Nothing was clipped in transit: the two low bits of every group of four pixels sit in the fifth byte of that group, waiting to be recombined. So the first decision is easy — leave the sensor configuration alone and fix the host-side parsing.
Confirm the packing before touching anything. Divide the captured buffer size by the frame height, then by the width: 1.25 bytes per pixel means packed RAW10, while 1.00 means the sensor is genuinely in 8-bit mode and no unpacking will help.
| What you see | What it means |
|---|---|
| Maximum pixel value exactly 255 | You are reading the MSB bytes only |
| 2000 bytes per row for a 1600-pixel width | Packed RAW10, 1.25 bytes per pixel |
| A faint vertical stripe every fifth column | An LSB byte rendered as if it were a pixel |
| A data-length error when you raise bits per pixel | The host expects a size no real mode produces |
How MIPI CSI-2 packs RAW10
The CSI-2 specification transmits RAW10 by packing four 10-bit pixels into five bytes. Bytes 0 to 3 hold bits [9:2] — the most significant 8 bits — of pixels 0 to 3. Byte 4 collects the four 2-bit remainders, ordered from the low end of the byte:
| Byte | Content |
|---|---|
| 0 | pixel 0, bits [9:2] |
| 1 | pixel 1, bits [9:2] |
| 2 | pixel 2, bits [9:2] |
| 3 | pixel 3, bits [9:2] |
| 4 | bits [1:0] of pixels 0, 1, 2 and 3, packed from the LSB end |
The specification sizes RAW10 lines in multiples of four pixels, so a width that divides cleanly by four needs no padding — 1600 and 640 both qualify. A width of 1302 would be padded to 1304, and the stride, not the width, would then size the row.
Four causes, ranked
- Your viewer reads the buffer as 8-bit. By far the most common. Test: maximum value exactly 255 together with the row-size check above. Fix: unpack, as shown below.
- You changed the bits-per-pixel field on its own. The host computes its expected frame size from that field, and no plain 8- or 16-bit setting matches a packed stream. Fix: capture the buffer at its true packed size, then unpack on the host after the frame arrives.
- The mode width is not a multiple of four. Padding bytes extend each row beyond the pixel count. Fix: pass the padded row length as the stride.
- The sensor is really in 8-bit mode. Test: the buffer is exactly width × height bytes. Fix: load the 10-bit mode configuration for your module.
Worked example: 1600 × 1300 RAW10 at 60 fps over USB3
Inputs: width 1600 px and height 1300 px from the module's native mode, 10 bits per pixel, 60 frames per second, carried over a USB3 bridge.
- Row: 1600 × 10 / 8 = 2000 bytes per line.
- Frame: 2000 × 1300 = 2,600,000 bytes, or 2.6 MB.
- Rate: 2,600,000 × 60 = 156 MB/s (about 1.25 Gbit/s), well inside USB3.
The same frame mis-declared as 16-bit would be expected at 1600 × 1300 × 2 = 4,160,000 bytes, and as 8-bit at 2,080,000 bytes. The packed 2.6 MB matches neither, which is why flipping the bits-per-pixel field alone ends in a data-length error rather than an image.
Now take one group of five captured bytes: FF 00 80 40 E4.
- The MSB bytes give 255, 0, 128, 64 — exactly what an 8-bit viewer shows.
- 0xE4 is 11100100 in binary: bits [1:0] = 00 (0), bits [3:2] = 01 (1), bits [5:4] = 10 (2), bits [7:6] = 11 (3).
- Pixel 0 = 255 × 4 + 0 = 1020; pixel 1 = 0 × 4 + 1 = 1; pixel 2 = 128 × 4 + 2 = 514; pixel 3 = 64 × 4 + 3 = 259.
The decision that follows: if the feature you measure rides on differences smaller than 1/256 of full scale — about 4 counts out of 1023 — the 8-bit read has already discarded it, and unpacking is not optional.
Unpack the buffer, with a test that proves it
The function below uses numpy; the names in it are our own, and the assert at the end proves the packing arithmetic on the five bytes from the worked example.
import numpy as np
def unpack_raw10(buf: bytes, width: int, height: int) -> np.ndarray:
"""Return packed RAW10 bytes as a 16-bit image, values 0-1023."""
row = width * 10 // 8 # five bytes per four pixels
a = np.frombuffer(buf, dtype=np.uint8).reshape(height, row)
img = a[:, :width].astype(np.uint16) * 4 # MSB bytes, shifted into place
lsb = a[:, width:].reshape(height, width // 4)
shifts = np.array([0, 2, 4, 6], dtype=np.uint8)
low = (lsb[:, :, None] >> shifts) & 0x03 # four 2-bit fields per byte
img = img.reshape(height, width // 4, 4)
img += low
return img.reshape(height, width)
group = bytes([0xFF, 0x00, 0x80, 0x40, 0xE4])
assert unpack_raw10(group, 4, 1).tolist() == [[1020, 1, 514, 259]]
Keep the result 16-bit; values now run to 1023 and an 8-bit container would clip them a second time. For display only, divide by four to get an 8-bit preview. The byte layout is identical whether the buffer came from a USB3 bridge or from a SoC CSI receiver, so the same function serves both.
Check the unpacked image before you trust it
- The histogram spans down near 0 and up to 1023. A sensor with a black-level offset idles above zero in darkness — black level offset in raw 12-bit images covers that shift.
- Saturated pixels land at 1023, or just under it on sensors whose saturation level sits below full scale.
- No vertical stripes every fifth column. Leftover stripes mean the stride you passed does not match the packed row.
- Aim at a smooth gradient: neighboring pixels step by 1 or 2 counts, never in jumps of 4.
When 10-bit earns its keep
Ten bits give 1024 codes against 8-bit's 256 — a quantization step near 0.1 % of full scale instead of 0.4 %. That margin pays for itself when you brighten dark scenes in software, fit edges to sub-pixel accuracy, or merge exposures. It changes nothing when you threshold high-contrast features under controlled light. The trade-offs are laid out in machine vision camera bit depth: choosing 8, 10 or 12 bits, and the dynamic-range side of the argument is in the global shutter CMOS sensor comparison. When the sensor offers the choice, raw10 and raw12 sensor modes explains why the 10-bit mode is worth selecting at capture time.
Skip the parsing: cameras that declare their pixel format
If the deliverable is an inspection system rather than a sensor bring-up, a camera with a USB3 Vision or GigE Vision interface removes the byte arithmetic: the frame arrives with a declared pixel format — Mono8, Mono10 or Mono12 — and the vendor library or any GenICam viewer decodes it. Those interfaces have their own packed formats, and the same discipline applies: unpacking Mono12p from the raw buffer and why a Mono16 buffer carries 12-bit sensor data cover the GigE-side cases. When your ceiling is a strange number rather than 255, 12-bit data in a 16-bit V4L2 frame is the matching diagnosis.
Start from board-level cameras for embedded builds or area scan cameras for full stations, and filter the camera finder by interface and resolution. The LS-BCM-0003 is a 3.1 MP USB3 board-level camera with a 1/1.8" global-shutter sensor at 120 fps:
- Sensor format
- 1/1.8"
- Lens mount
- C-mount
- Interface
- USB3
- Resolution
- 5 MP
For the same freedom over GigE or on a bare board, the MV-CB060-10UM-B is a 6 MP USB3 board camera and the MV-CB016-10GM-M-W is a 1.6 MP GigE board camera, both mono:
- Sensor format
- 1/1.8"
- Interface
- USB3
- Sensor format
- 1/2.9"
- Lens mount
- M12
Pair the module with its bridge before you stream — board-level camera and USB3 bridge board — then size the rest of the station in the system configurator.
Bring-up checklist
- Compute the packed row size before the first capture and assert the buffer matches it.
- Save one raw frame and check its size as a file, not through the viewer.
- Unpack with the tested function and keep the result in a 16-bit container.
- Confirm the histogram reaches 1023 and that darkness sits at the black level, not at zero.
- Record sensor mode, width, height and stride beside every capture.
Questions
Why do my 10-bit sensor values stop at 255?
The readout keeps only the top 8 bits of each pixel, so the value shown is the true value divided by four, rounded down. The two low bits of every group of four pixels are stored in the fifth byte of each five-byte group. Unpack that byte back into the low bits and the range extends to 1023.
How many bytes per line does a RAW10 image use?
A RAW10 line uses 1.25 × width bytes: 2000 bytes for a 1600-pixel width, 800 bytes for a 640-pixel width. The CSI-2 specification sizes RAW10 lines in multiples of four pixels, so widths not divisible by four are padded — pass the padded stride, not the width, when you read the buffer.
Why does setting 16-bit mode fail with a data-length error?
The host computes its expected frame size from the declared bits per pixel. At 1600 × 1300, 16-bit mode expects 4,160,000 bytes and 8-bit expects 2,080,000, but packed RAW10 delivers 2,600,000 — no plain setting matches, so the length check fails. Declare the packed size and unpack after capture instead.
Should I store the unpacked image as 8-bit?
No. Values run to 1023, so an 8-bit container clips exactly what you recovered; use 16-bit storage. Divide by four only to render an 8-bit preview on screen, and keep the original packed file so the low bits survive any later reprocessing.
Do USB3 Vision and GigE Vision cameras also pack 10-bit data?
They can — packed formats exist on those interfaces too — but the camera declares the pixel format in the stream, and standard libraries or any GenICam viewer decodes it for you. You choose Mono8, Mono10 or Mono12 in software instead of parsing five-byte groups by hand.


