> ## 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.

# stellarHD YUYV 비디오 가이드

> 흑백 모델을 포함한 stellarHD에서 비압축 YUYV 프레임을 캡처, 저장 및 변환하는 방법.

## 개요

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

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

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

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

## 요구 사항

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

```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
```

## YUYV vs MJPEG 이해하기

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

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

<Warning>
  **"YUYV"는 비압축이지만 센서-raw는 아닙니다.** 카메라 용어에서 *raw*는 디모자이크, 화이트 밸런스 또는 색상 변환 이전의 픽셀당 하나의 색상 샘플로 구성된 센서 직출력 **베이어 모자이크(Bayer mosaic)** 를 의미합니다. YUYV 4:2:2 (`YUY2`)는 다릅니다: 이는 카메라의 **이미 처리된 출력**입니다 — 베이어 데이터는 카메라에서 디모자이크되고 YUV 색 공간으로 변환되며 크로마 서브샘플링됩니다(4:2:2는 두 개의 휘도 샘플마다 두 개의 크로마 샘플을 저장합니다). 이는 컬러 모델과 흑백 모델 모두에 해당합니다: 출력은 비압축이지만 여전히 처리되고 서브샘플링됩니다.

  stellarHD는 UVC를 통해 기저 베이어/센서-raw 데이터를 노출하지 **않으므로**, 원시 모자이크를 검색하거나 자체 디모자이크 파이프라인을 실행할 **수 없습니다**. 이 가이드에서 "raw"는 *센서-raw*가 아니라 *비압축 픽셀 데이터*를 의미합니다.
</Warning>

## 단계 1 — 장치 노드 식별

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

```bash theme={null}
v4l2-ctl --list-devices
```

예시 출력:

```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
```

이 예시에서는 `/dev/video4`가 사용할 노드입니다. 아래 명령에서 자신의 노드로 대체하세요.

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

  ```bash theme={null}
  v4l2-ctl -d /dev/video4 --list-formats-ext
  ```

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

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

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

```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
```

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

### 프레임 크기 확인

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

```text theme={null}
1600 × 1200 × 2 = 3,840,000 bytes (~3.8 MB)
```

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

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

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

```bash theme={null}
ffmpeg \
  -f rawvideo \
  -pixel_format yuyv422 \
  -video_size 1600x1200 \
  -i frame_1600x1200.yuyv \
  frame.png
```

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

## 흑백 stellarHD 모델

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

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

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

```bash theme={null}
ffmpeg \
  -f rawvideo \
  -pixel_format yuyv422 \
  -video_size 1600x1200 \
  -i frame_1600x1200.yuyv \
  -vf format=gray \
  mono.png
```

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

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

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

```bash theme={null}
ffplay \
  -f rawvideo \
  -pixel_format yuyv422 \
  -video_size 1600x1200 \
  frame_1600x1200.yuyv
```

## GStreamer 파이프라인

### 실시간 원시 스트림 보기

```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
```

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

```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
```

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

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

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

## OpenCV / Python에서 휘도 추출

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

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

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

```python theme={null}
import cv2

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

<Card title="OpenCV 가이드" icon="https://github.com/opencv/opencv/wiki/logo/OpenCV_logo_no_text.png" href="/ko/stellarHD/guides/opencv-stellarHD">
  stellarHD를 OpenCV와 함께 사용하는 전체 가이드를 참조하세요.
</Card>

## 문제 해결

### 출력 파일 크기가 잘못됨

완전한 원시 프레임은 정확히 `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로 전환하세요.