Saltar para o conteúdo principal

​
Visão geral

O stellarHD expõe dois formatos de vídeo pela sua interface UVC (USB Video Class) padrão:
  • MJPEG — quadros comprimidos em JPEG. Melhor para altas taxas de quadros (até 60 FPS) e visualização ao vivo.
  • YUYV — vídeo bruto sem compressão em 4:2:2. Melhor quando você precisa dos dados de pixel originais, sem processamento (visão computacional, fotogrametria, imagem científica).
Este guia foca na captura YUYV (RAW): como capturar quadros verdadeiramente brutos, salvá-los em disco e convertê-los para inspeção. Também aborda um detalhe específico dos modelos monocromáticos do stellarHD, em que apenas o canal de luminância (Y) contém dados reais de imagem.
YUYV é sem compressão, portanto consome muito mais largura de banda USB do que MJPEG. Como resultado, o modo bruto é limitado a taxas de quadros menores em resoluções mais altas. Consulte as especificações técnicas do stellarHD para conhecer as combinações suportadas de resolução/taxa de quadros.

​
Requisitos

Estes comandos requerem um computador Linux com v4l-utils, GStreamer e FFmpeg instalados: 
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

​
Entendendo YUYV vs MJPEG

YUYV (sem compressão)MJPEG
CompressãoNenhuma (4:2:2 sem compressão)Compressão JPEG
Caso de usoDados brutos de pixel, análiseAlta taxa de quadros, pré-visualização ao vivo
Taxa de quadrosMenor em alta resoluçãoAté 60 FPS
Tamanho do arquivolargura × altura × 2 bytes por quadroVariável (pequeno)
Visualizável diretamenteNão (bytes brutos)Sim (cada quadro é um JPEG)
Nas caps do GStreamer, o formato V4L2 YUYV é escrito como YUY2.
“YUYV” é sem compressão, mas não é raw do sensor. Em termos de câmera, raw significa o mosaico Bayer sem processamento vindo diretamente do sensor — uma amostra de cor por pixel, antes do demosaicing, balanço de branco ou conversão de cor. YUYV 4:2:2 (YUY2) é algo diferente: é a saída já processada da câmera — os dados Bayer foram demosaicados na câmera, convertidos para o espaço de cor YUV e sub-amostrados em croma (4:2:2 armazena duas amostras de croma para cada duas amostras de luma). Isso vale tanto para os modelos coloridos quanto para os monocromáticos: a saída é sem compressão, mas ainda é processada e sub-amostrada.O stellarHD não expõe os dados Bayer/raw do sensor via UVC, então você não pode recuperar um mosaico bruto ou executar seu próprio pipeline de demosaicing. O “raw” neste guia significa dados de pixel sem compressão, não raw do sensor.

​
Passo 1 — Identifique o nó de dispositivo

Quando você conecta um stellarHD, o kernel cria vários nós de dispositivo V4L2. Tanto YUYV quanto MJPEG são expostos no primeiro nó do grupo. 
v4l2-ctl --list-devices
Exemplo de saída: 
stellarHD Leader: stellarHD Lea (usb-0000:00:14.0-6):
	/dev/video4   # <-- this node outputs both YUYV and MJPEG
	/dev/video5
	/dev/media2
Neste exemplo, /dev/video4 é o nó a ser usado. Substitua pelo seu próprio nó nos comandos abaixo.
Confirme os formatos, resoluções e taxas de quadros que sua câmera anuncia antes de capturar:
v4l2-ctl -d /dev/video4 --list-formats-ext
Você deve ver entradas tanto YUYV (4:2:2 sem compressão) quanto MJPG (MJPEG comprimido).

​
Passo 2 — Capturar um único quadro RAW

Use v4l2-ctl para capturar um quadro YUYV sem compressão em resolução máxima: 
v4l2-ctl -d /dev/video4 \
  --set-fmt-video=width=1600,height=1200,pixelformat=YUYV \
  --stream-mmap \
  --stream-count=1 \
  --stream-to=frame_1600x1200.yuyv
Isso grava os bytes YUYV brutos diretamente em frame_1600x1200.yuyv.

​
Verifique o tamanho do quadro

Um quadro raw completo deve ter exatamente largura × altura × 2 bytes: 
1600 × 1200 × 2 = 3.840.000 bytes (~3,8 MB)
Se o tamanho do arquivo corresponder, você capturou um quadro raw completo.

​
Passo 3 — Converter o quadro RAW para PNG

Bytes YUYV brutos não são diretamente visualizáveis. Use o FFmpeg para converter o quadro em um PNG para inspeção: 
ffmpeg \
  -f rawvideo \
  -pixel_format yuyv422 \
  -video_size 1600x1200 \
  -i frame_1600x1200.yuyv \
  frame.png
Você deve informar ao FFmpeg o formato de pixel exato (yuyv422) e a resolução (-video_size) do arquivo raw. Vídeo raw não tem cabeçalho, portanto, se esses valores não coincidirem com a captura, a imagem aparecerá distorcida ou corrompida.

​
Modelos monocromáticos do stellarHD

Por uma peculiaridade do UVC, o stellarHD monocromático anuncia sua saída como YUYV 4:2:2, mesmo que o sensor não tenha informação de cor.
  • Apenas o canal Y (luminância) contém a imagem real.
  • Os canais U e V (croma) são valores fictícios/fixos e podem ser ignorados.
Se você converter um quadro monocromático como cor completa, poderá ver tons falsos vindos dos dados de croma sem significado. Extraia apenas em tons de cinza: 
ffmpeg \
  -f rawvideo \
  -pixel_format yuyv422 \
  -video_size 1600x1200 \
  -i frame_1600x1200.yuyv \
  -vf format=gray \
  mono.png
Isso usa apenas o canal de luminância e evita a interpretação falsa do croma.

​
Verifique se a câmera é realmente monocromática

Reproduza o arquivo raw diretamente com ffplay. Se a imagem aparecer em tons de cinza naturalmente, os canais de croma são constantes: 
ffplay \
  -f rawvideo \
  -pixel_format yuyv422 \
  -video_size 1600x1200 \
  frame_1600x1200.yuyv

​
Pipelines do GStreamer

​
Visualizar o stream raw ao vivo

gst-launch-1.0 \
  v4l2src device=/dev/video4 ! \
  video/x-raw,format=YUY2,width=1600,height=1200,framerate=5/1 ! \
  videoconvert ! \
  autovideosink

​
Salvar um quadro raw em disco

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

​
Pré-visualização mais rápida com MJPEG

Como o YUYV é limitado a taxas de quadros baixas em alta resolução, use MJPEG quando você só precisar de uma pré-visualização suave em tempo real: 
gst-launch-1.0 \
  v4l2src device=/dev/video4 ! \
  image/jpeg,width=1600,height=1200,framerate=30/1 ! \
  jpegdec ! \
  videoconvert ! \
  autovideosink

​
Extraindo luminância em OpenCV / Python

Se você processa quadros raw a jusante e seu sensor é monocromático, extraia o canal de luminância em vez de tratar o quadro como colorido. 
# YUYV frame loaded as a 3-channel array — the Y channel is the real image
gray = frame[:, :, 0]
Ou converta explicitamente de YUY2: 
import cv2

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

Guia OpenCV

Veja nosso guia completo sobre como usar o stellarHD com OpenCV.

​
Solução de problemas

​
O arquivo de saída está com o tamanho errado

Um quadro raw completo tem exatamente largura × altura × 2 bytes. Um arquivo menor normalmente significa que a captura foi interrompida ou que a resolução solicitada não é suportada no modo YUYV — verifique v4l2-ctl -d /dev/video4 --list-formats-ext.

​
A imagem convertida está distorcida ou embaralhada

Os valores -pixel_format e -video_size passados ao FFmpeg devem corresponder exatamente à captura. Vídeo raw não tem cabeçalho, portanto qualquer divergência corrompe o layout.

​
A imagem parece tingida em uma câmera monocromática

Os canais de croma não carregam dados reais em um sensor monocromático. Reconverta com -vf format=gray (FFmpeg) ou extraia o canal Y (OpenCV) conforme mostrado acima.

​
A taxa de quadros YUYV está muito baixa

Isso é esperado — vídeo sem compressão consome muita largura de banda. Diminua a resolução, reduza a taxa de quadros ou mude para MJPEG para visualização ao vivo.