Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dwe.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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
CompressionNone (4:2:2 uncompressed)JPEG compressed
Use caseRaw pixel data, analysisHigh framerate, live preview
FramerateLower at high resolutionUp to 60 FPS
File sizewidth × height × 2 bytes per frameVariable (small)
Directly viewableNo (raw bytes)Yes (each frame is a JPEG)
In GStreamer caps, the V4L2 format 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. 
v4l2-ctl --list-devices
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
In this example, /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
You should see both 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
This writes the raw YUYV bytes directly to 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)
If the file size matches, you have captured a complete raw frame.

​
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
This uses only the luminance channel and avoids bogus chroma interpretation.

​
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

​
Extracting Luminance in OpenCV / Python

If you process raw frames downstream and your sensor is monochrome, extract the luminance channel rather than treating the frame as color. 
# YUYV frame loaded as a 3-channel array — the Y channel is the real image
gray = frame[:, :, 0]
Or convert explicitly from YUY2: 
import cv2

gray = cv2.cvtColor(frame, cv2.COLOR_YUV2GRAY_YUY2)
https://github.com/opencv/opencv/wiki/logo/OpenCV_logo_no_text.png

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.