Overview
The stellarHD exposes two video formats over its standard UVC (USB Video Class) interface:
- MJPEG — JPEG-compressed frames. Best for high framerates (up to 60 FPS) and live viewing.
- YUYV — uncompressed 4:2:2 raw video. Best when you need the original, unprocessed pixel data (machine vision, photogrammetry, scientific imaging).
This guide focuses on YUYV (RAW) capture: how to grab true raw frames, save them to disk, and convert them for inspection. It also covers a detail specific to monochrome stellarHD models, where only the luminance (Y) channel contains real image data.
YUYV is uncompressed, so it consumes far more USB bandwidth than MJPEG. As a result, raw mode is limited to lower framerates at higher resolutions. Refer to the stellarHD Technical Specifications for the supported resolution/framerate combinations. Requirements
These commands require a Linux computer with v4l-utils, GStreamer, and FFmpeg installed:
sudo apt install v4l-utils ffmpeg \
libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev gstreamer1.0-tools \
gstreamer1.0-x gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
gstreamer1.0-plugins-bad gstreamer1.0-libav gstreamer1.0-plugins-ugly
Understanding YUYV vs MJPEG
| YUYV (uncompressed) | MJPEG |
|---|
| Compression | None (4:2:2 uncompressed) | JPEG compressed |
| Use case | Raw pixel data, analysis | High framerate, live preview |
| Framerate | Lower at high resolution | Up to 60 FPS |
| File size | width × height × 2 bytes per frame | Variable (small) |
| Directly viewable | No (raw bytes) | Yes (each frame is a JPEG) |
YUYV is written as YUY2.
“YUYV” is uncompressed, but it is not sensor-raw. In camera terms, raw means the
unprocessed Bayer mosaic straight off the sensor — one color sample per pixel, before
demosaicing, white balance, or color conversion. YUYV 4:2:2 (YUY2) is something different:
it is the camera’s already-processed output — the Bayer data has been demosaiced on the
camera, converted to the YUV color space, and chroma-subsampled (4:2:2 stores two chroma
samples for every two luma samples). This is true of both the color and monochrome models:
the output is uncompressed, but it is still processed and sub-sampled.The stellarHD does not expose the underlying Bayer/sensor-raw data over UVC, so you
cannot retrieve a raw mosaic or run your own demosaicing pipeline. The “raw” in this guide
means uncompressed pixel data, not sensor-raw.
Step 1 — Identify the Device Node
When you plug in a stellarHD, the kernel creates several V4L2 device nodes. Both YUYV and MJPEG are exposed on the first node of the group.
Example output:
stellarHD Leader: stellarHD Lea (usb-0000:00:14.0-6):
/dev/video4 # <-- this node outputs both YUYV and MJPEG
/dev/video5
/dev/media2
/dev/video4 is the node to use. Substitute your own node in the commands below.
Confirm the formats, resolutions, and framerates your camera advertises before capturing:v4l2-ctl -d /dev/video4 --list-formats-ext
YUYV (uncompressed 4:2:2) and MJPG (MJPEG compressed) entries. Step 2 — Capture a Single RAW Frame
Use v4l2-ctl to capture one uncompressed YUYV frame at full resolution:
v4l2-ctl -d /dev/video4 \
--set-fmt-video=width=1600,height=1200,pixelformat=YUYV \
--stream-mmap \
--stream-count=1 \
--stream-to=frame_1600x1200.yuyv
frame_1600x1200.yuyv.
Verify the frame size
A complete raw frame should be exactly width × height × 2 bytes:
1600 × 1200 × 2 = 3,840,000 bytes (~3.8 MB)
Step 3 — Convert the RAW Frame to PNG
Raw YUYV bytes are not directly viewable. Use FFmpeg to convert the frame into a PNG for inspection:
ffmpeg \
-f rawvideo \
-pixel_format yuyv422 \
-video_size 1600x1200 \
-i frame_1600x1200.yuyv \
frame.png
You must tell FFmpeg the exact pixel format (yuyv422) and resolution (-video_size) of the raw file. Raw video has no header, so if these values don’t match the capture, the image will appear skewed or corrupted.
Monochrome stellarHD Models
Because of a UVC quirk, the monochrome stellarHD advertises its output as YUYV 4:2:2 even though the sensor has no color information.
- Only the
Y (luminance) channel contains the real image.
- The
U and V (chroma) channels are dummy/fixed values and can be ignored.
If you convert a monochrome frame as full color, you may see bogus tinting from the meaningless chroma data. Extract grayscale only:
ffmpeg \
-f rawvideo \
-pixel_format yuyv422 \
-video_size 1600x1200 \
-i frame_1600x1200.yuyv \
-vf format=gray \
mono.png
Verify the camera is genuinely monochrome
Play the raw file back directly with ffplay. If the image appears grayscale naturally, the chroma channels are constant:
ffplay \
-f rawvideo \
-pixel_format yuyv422 \
-video_size 1600x1200 \
frame_1600x1200.yuyv
GStreamer Pipelines
View the live raw stream
gst-launch-1.0 \
v4l2src device=/dev/video4 ! \
video/x-raw,format=YUY2,width=1600,height=1200,framerate=5/1 ! \
videoconvert ! \
autovideosink
Save one raw frame to disk
gst-launch-1.0 -e \
v4l2src device=/dev/video4 num-buffers=1 ! \
video/x-raw,format=YUY2,width=1600,height=1200,framerate=5/1 ! \
filesink location=frame.yuyv
Faster preview with MJPEG
Because YUYV is limited to low framerates at high resolution, use MJPEG when you only need a smooth realtime preview:
gst-launch-1.0 \
v4l2src device=/dev/video4 ! \
image/jpeg,width=1600,height=1200,framerate=30/1 ! \
jpegdec ! \
videoconvert ! \
autovideosink
# YUYV frame loaded as a 3-channel array — the Y channel is the real image
gray = frame[:, :, 0]
import cv2
gray = cv2.cvtColor(frame, cv2.COLOR_YUV2GRAY_YUY2)
OpenCV Guide
See our full guide on using the stellarHD with OpenCV.
Troubleshooting
The output file is the wrong size
A complete raw frame is exactly width × height × 2 bytes. A smaller file usually means the capture was interrupted or the requested resolution isn’t supported in YUYV mode — check v4l2-ctl -d /dev/video4 --list-formats-ext.
The converted image is skewed or garbled
The -pixel_format and -video_size passed to FFmpeg must exactly match the capture. Raw video has no header, so any mismatch corrupts the layout.
The image looks tinted on a monochrome camera
The chroma channels carry no real data on a monochrome sensor. Re-convert with -vf format=gray (FFmpeg) or extract the Y channel (OpenCV) as shown above.
YUYV framerate is too low
This is expected — uncompressed video is bandwidth-heavy. Drop the resolution, lower the framerate, or switch to MJPEG for live viewing.
