> ## 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. # Guia de vídeo YUYV do stellarHD > Capture, salve e converta quadros YUYV sem compressão do stellarHD, incluindo modelos monocromáticos. ## 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](/pt/stellarHD/specs/stellarHD#resoluções-e-taxas-de-quadros-suportadas) 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: ```bash theme={null} 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ão | Nenhuma (4:2:2 sem compressão) | Compressão JPEG | | Caso de uso | Dados brutos de pixel, análise | Alta taxa de quadros, pré-visualização ao vivo | | Taxa de quadros | Menor em alta resolução | Até 60 FPS | | Tamanho do arquivo | `largura × altura × 2` bytes por quadro | Variável (pequeno) | | Visualizável diretamente | Nã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. ```bash theme={null} v4l2-ctl --list-devices ``` Exemplo de saída: ```text theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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: ```text theme={null} 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: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} ffplay \ -f rawvideo \ -pixel_format yuyv422 \ -video_size 1600x1200 \ frame_1600x1200.yuyv ``` ## Pipelines do GStreamer ### Visualizar o stream raw ao vivo ```bash theme={null} 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 ```bash theme={null} 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: ```bash theme={null} 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. ```python theme={null} # YUYV frame loaded as a 3-channel array — the Y channel is the real image gray = frame[:, :, 0] ``` Ou converta explicitamente de YUY2: ```python theme={null} import cv2 gray = cv2.cvtColor(frame, cv2.COLOR_YUV2GRAY_YUY2) ``` 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.