stellarHD YUYV 비디오 가이드

개요

stellarHD는 표준 UVC (USB Video Class) 인터페이스를 통해 두 가지 비디오 형식을 제공합니다:

MJPEG — JPEG 압축 프레임. 높은 프레임 속도(최대 60 FPS) 및 실시간 보기에 적합합니다.
YUYV — 비압축 4:2:2 원시 비디오. 원본의 미가공 픽셀 데이터가 필요할 때 적합합니다(머신 비전, 사진측량, 과학 영상).

이 가이드는 YUYV (RAW) 캡처에 중점을 둡니다: 실제 원시 프레임을 가져오는 방법, 디스크에 저장하는 방법, 검사를 위해 변환하는 방법. 또한 휘도(Y) 채널만 실제 이미지 데이터를 포함하는 흑백 stellarHD 모델에 특정한 세부 정보도 다룹니다.

YUYV는 비압축이므로 MJPEG보다 훨씬 많은 USB 대역폭을 소비합니다. 결과적으로 원시 모드는 더 높은 해상도에서 더 낮은 프레임 속도로 제한됩니다. 지원되는 해상도/프레임 속도 조합은 stellarHD 기술 사양을 참조하세요.

요구 사항

이 명령은 v4l-utils, GStreamer 및 FFmpeg이 설치된 Linux 컴퓨터를 필요로 합니다:

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

YUYV vs MJPEG 이해하기

	YUYV (비압축)	MJPEG
압축	없음 (4:2:2 비압축)	JPEG 압축
사용 사례	원시 픽셀 데이터, 분석	높은 프레임 속도, 실시간 미리보기
프레임 속도	높은 해상도에서 낮음	최대 60 FPS
파일 크기	프레임당 `width × height × 2` 바이트	가변 (작음)
직접 볼 수 있는지 여부	아니요 (원시 바이트)	예 (각 프레임은 JPEG)

GStreamer caps에서 V4L2 형식 YUYV는 YUY2로 표기됩니다.

“YUYV”는 비압축이지만 센서-raw는 아닙니다. 카메라 용어에서 raw는 디모자이크, 화이트 밸런스 또는 색상 변환 이전의 픽셀당 하나의 색상 샘플로 구성된 센서 직출력 베이어 모자이크(Bayer mosaic) 를 의미합니다. YUYV 4:2:2 (YUY2)는 다릅니다: 이는 카메라의 이미 처리된 출력입니다 — 베이어 데이터는 카메라에서 디모자이크되고 YUV 색 공간으로 변환되며 크로마 서브샘플링됩니다(4:2:2는 두 개의 휘도 샘플마다 두 개의 크로마 샘플을 저장합니다). 이는 컬러 모델과 흑백 모델 모두에 해당합니다: 출력은 비압축이지만 여전히 처리되고 서브샘플링됩니다.stellarHD는 UVC를 통해 기저 베이어/센서-raw 데이터를 노출하지 않으므로, 원시 모자이크를 검색하거나 자체 디모자이크 파이프라인을 실행할 수 없습니다. 이 가이드에서 “raw”는 센서-raw가 아니라 비압축 픽셀 데이터를 의미합니다.

단계 1 — 장치 노드 식별

stellarHD를 연결하면 커널이 여러 V4L2 장치 노드를 생성합니다. YUYV와 MJPEG 모두 그룹의 첫 번째 노드에 노출됩니다.

v4l2-ctl --list-devices

예시 출력:

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가 사용할 노드입니다. 아래 명령에서 자신의 노드로 대체하세요.

캡처하기 전에 카메라가 보고하는 형식, 해상도 및 프레임 속도를 확인하세요:

v4l2-ctl -d /dev/video4 --list-formats-ext

YUYV (비압축 4:2:2) 항목과 MJPG (MJPEG 압축) 항목이 모두 표시되어야 합니다.

단계 2 — 단일 RAW 프레임 캡처

v4l2-ctl을 사용하여 전체 해상도에서 비압축 YUYV 프레임 한 장을 캡처합니다:

v4l2-ctl -d /dev/video4 \
  --set-fmt-video=width=1600,height=1200,pixelformat=YUYV \
  --stream-mmap \
  --stream-count=1 \
  --stream-to=frame_1600x1200.yuyv

이 명령은 원시 YUYV 바이트를 직접 frame_1600x1200.yuyv에 기록합니다.

프레임 크기 확인

완전한 원시 프레임은 정확히 width × height × 2 바이트여야 합니다:

1600 × 1200 × 2 = 3,840,000 bytes (~3.8 MB)

파일 크기가 일치하면 완전한 원시 프레임을 캡처한 것입니다.

단계 3 — RAW 프레임을 PNG로 변환

원시 YUYV 바이트는 직접 볼 수 없습니다. FFmpeg을 사용하여 프레임을 PNG로 변환하여 검사할 수 있습니다:

ffmpeg \
  -f rawvideo \
  -pixel_format yuyv422 \
  -video_size 1600x1200 \
  -i frame_1600x1200.yuyv \
  frame.png

FFmpeg에 원시 파일의 정확한 픽셀 형식(yuyv422)과 해상도(-video_size)를 알려야 합니다. 원시 비디오에는 헤더가 없으므로 이 값이 캡처와 일치하지 않으면 이미지가 왜곡되거나 손상되어 보일 수 있습니다.

흑백 stellarHD 모델

UVC의 특이점으로 인해 흑백 stellarHD는 센서에 색상 정보가 없음에도 출력을 YUYV 4:2:2로 보고합니다.

Y (휘도) 채널만 실제 이미지를 포함합니다.
U 및 V (크로마) 채널은 더미/고정 값이며 무시해도 됩니다.

흑백 프레임을 전체 컬러로 변환하면 의미 없는 크로마 데이터로 인해 잘못된 색조가 보일 수 있습니다. 흑백만 추출하세요:

ffmpeg \
  -f rawvideo \
  -pixel_format yuyv422 \
  -video_size 1600x1200 \
  -i frame_1600x1200.yuyv \
  -vf format=gray \
  mono.png

이는 휘도 채널만 사용하고 잘못된 크로마 해석을 방지합니다.

카메라가 실제로 흑백인지 확인

ffplay로 원시 파일을 직접 재생하세요. 이미지가 자연스럽게 그레이스케일로 나타나면 크로마 채널이 일정한 것입니다:

ffplay \
  -f rawvideo \
  -pixel_format yuyv422 \
  -video_size 1600x1200 \
  frame_1600x1200.yuyv

GStreamer 파이프라인

실시간 원시 스트림 보기

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

원시 프레임 하나를 디스크에 저장

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

MJPEG를 사용한 빠른 미리보기

YUYV는 고해상도에서 낮은 프레임 속도로 제한되므로, 부드러운 실시간 미리보기만 필요한 경우 MJPEG를 사용하세요:

gst-launch-1.0 \
  v4l2src device=/dev/video4 ! \
  image/jpeg,width=1600,height=1200,framerate=30/1 ! \
  jpegdec ! \
  videoconvert ! \
  autovideosink

OpenCV / Python에서 휘도 추출

다운스트림에서 원시 프레임을 처리하고 센서가 흑백인 경우, 프레임을 컬러로 처리하지 말고 휘도 채널을 추출하세요.

# 3채널 배열로 로드된 YUYV 프레임 — Y 채널이 실제 이미지
gray = frame[:, :, 0]

또는 YUY2에서 명시적으로 변환:

import cv2

gray = cv2.cvtColor(frame, cv2.COLOR_YUV2GRAY_YUY2)

OpenCV 가이드

stellarHD를 OpenCV와 함께 사용하는 전체 가이드를 참조하세요.

문제 해결

출력 파일 크기가 잘못됨

완전한 원시 프레임은 정확히 width × height × 2 바이트입니다. 더 작은 파일은 일반적으로 캡처가 중단되었거나 요청한 해상도가 YUYV 모드에서 지원되지 않음을 의미합니다 — v4l2-ctl -d /dev/video4 --list-formats-ext를 확인하세요.

변환된 이미지가 왜곡되거나 깨짐

FFmpeg에 전달된 -pixel_format 및 -video_size는 캡처와 정확히 일치해야 합니다. 원시 비디오에는 헤더가 없으므로 불일치하면 레이아웃이 손상됩니다.

흑백 카메라에서 이미지가 색조를 띠어 보임

흑백 센서에서는 크로마 채널이 실제 데이터를 전달하지 않습니다. 위에 표시된 대로 -vf format=gray (FFmpeg)로 다시 변환하거나 Y 채널을 추출(OpenCV)하세요.

YUYV 프레임 속도가 너무 낮음

이는 정상입니다 — 비압축 비디오는 대역폭을 많이 사용합니다. 해상도를 낮추거나 프레임 속도를 낮추거나 실시간 보기에는 MJPEG로 전환하세요.

​개요

​요구 사항

​YUYV vs MJPEG 이해하기

​단계 1 — 장치 노드 식별

​단계 2 — 단일 RAW 프레임 캡처

​프레임 크기 확인

​단계 3 — RAW 프레임을 PNG로 변환

​흑백 stellarHD 모델

​카메라가 실제로 흑백인지 확인

​GStreamer 파이프라인

​실시간 원시 스트림 보기

​원시 프레임 하나를 디스크에 저장

​MJPEG를 사용한 빠른 미리보기

​OpenCV / Python에서 휘도 추출

OpenCV 가이드

​문제 해결

​출력 파일 크기가 잘못됨

​변환된 이미지가 왜곡되거나 깨짐

​흑백 카메라에서 이미지가 색조를 띠어 보임

​YUYV 프레임 속도가 너무 낮음

개요

요구 사항

YUYV vs MJPEG 이해하기

단계 1 — 장치 노드 식별

단계 2 — 단일 RAW 프레임 캡처

프레임 크기 확인

단계 3 — RAW 프레임을 PNG로 변환

흑백 stellarHD 모델

카메라가 실제로 흑백인지 확인

GStreamer 파이프라인

실시간 원시 스트림 보기

원시 프레임 하나를 디스크에 저장

MJPEG를 사용한 빠른 미리보기

OpenCV / Python에서 휘도 추출

문제 해결

출력 파일 크기가 잘못됨

변환된 이미지가 왜곡되거나 깨짐

흑백 카메라에서 이미지가 색조를 띠어 보임

YUYV 프레임 속도가 너무 낮음