> ## 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)インターフェイス上で 2 つのビデオフォーマットを公開します:
* **MJPEG** — JPEG 圧縮フレーム。高フレームレート(最大 60 FPS)とライブ表示に最適。
* **YUYV** — 非圧縮 4:2:2 raw ビデオ。元の未処理のピクセルデータ(マシンビジョン、フォトグラメトリ、科学イメージング)が必要な場合に最適。
このガイドは、**YUYV(RAW)** キャプチャに焦点を当てています。本物の raw フレームを取得し、ディスクに保存し、検査のために変換する方法です。また、輝度(`Y`)チャンネルのみが実際の画像データを含む **モノクロ stellarHD モデル** に固有の詳細についても説明します。
YUYV は非圧縮であるため、MJPEG よりもはるかに多くの USB 帯域幅を消費します。その結果、raw モードは高解像度では低いフレームレートに制限されます。サポートされる解像度/フレームレートの組み合わせについては、[stellarHD 技術仕様](/ja/stellarHD/specs/stellarHD#サポートされる解像度とフレームレート)を参照してください。
## 必要環境
これらのコマンドには、`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 と MJPEG の違いを理解する
| | YUYV(非圧縮) | MJPEG |
| ------- | -------------------------------- | ----------------- |
| 圧縮 | なし(4:2:2 非圧縮) | JPEG 圧縮 |
| ユースケース | Raw ピクセルデータ、解析 | 高フレームレート、ライブプレビュー |
| フレームレート | 高解像度では低い | 最大 60 FPS |
| ファイルサイズ | フレームあたり `width × height × 2` バイト | 可変(小さい) |
| 直接表示可能 | いいえ(raw バイト) | はい(各フレームが JPEG) |
GStreamer caps において、V4L2 フォーマットの `YUYV` は `YUY2` と記述されます。
**「YUYV」は非圧縮ですが、センサー raw ではありません。** カメラの用語において、*raw* とはセンサーから直接出力された未処理の **ベイヤーモザイク** を意味します — ピクセルあたり 1 つのカラーサンプルであり、デモザイク、ホワイトバランス、色変換を行う前のものです。YUYV 4:2:2(`YUY2`)は別物であり、カメラの **既に処理済みの出力** です — ベイヤーデータはカメラ上でデモザイクされ、YUV 色空間に変換され、彩度サブサンプリング(4:2:2 では 2 つの輝度サンプルごとに 2 つの彩度サンプルを格納)されています。これはカラーモデルとモノクロモデルの両方に当てはまります: 出力は非圧縮ですが、それでも処理されサブサンプリングされています。
stellarHD は UVC 経由で基礎となるベイヤー/センサー raw データを公開し**ません**。そのため、raw モザイクを取得したり、独自のデモザイクパイプラインを実行することは **できません**。このガイドにおける「raw」は、*非圧縮ピクセルデータ* を意味し、*センサー raw* ではありません。
## ステップ 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 # <-- このノードが YUYV と MJPEG の両方を出力します
/dev/video5
/dev/media2
```
この例では、`/dev/video4` を使用するノードです。以下のコマンドでは、ご自身のノードに置き換えてください。
キャプチャの前に、カメラが提供しているフォーマット、解像度、フレームレートを確認します:
```bash theme={null}
v4l2-ctl -d /dev/video4 --list-formats-ext
```
`YUYV`(非圧縮 4:2:2)と `MJPG`(MJPEG 圧縮)の両方のエントリが表示されているはずです。
## ステップ 2 — RAW フレームを 1 枚キャプチャする
`v4l2-ctl` を使用して、フル解像度で非圧縮 YUYV フレームを 1 つキャプチャします:
```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
```
これは raw YUYV バイトを直接 `frame_1600x1200.yuyv` に書き込みます。
### フレームサイズを確認する
完全な raw フレームは正確に `width × height × 2` バイトであるべきです:
```text theme={null}
1600 × 1200 × 2 = 3,840,000 bytes (~3.8 MB)
```
ファイルサイズが一致すれば、完全な raw フレームをキャプチャしたことになります。
## ステップ 3 — RAW フレームを PNG に変換する
Raw YUYV バイトは直接表示できません。FFmpeg を使用してフレームを PNG に変換し、検査します:
```bash theme={null}
ffmpeg \
-f rawvideo \
-pixel_format yuyv422 \
-video_size 1600x1200 \
-i frame_1600x1200.yuyv \
frame.png
```
FFmpeg には、raw ファイルの正確なピクセル形式(`yuyv422`)と解像度(`-video_size`)を指定する必要があります。Raw ビデオにはヘッダーがないため、これらの値がキャプチャと一致しない場合、画像が歪んだり破損したりして表示されます。
## モノクロ 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` で raw ファイルを直接再生します。画像が自然にグレースケールに見える場合、彩度チャンネルは一定です:
```bash theme={null}
ffplay \
-f rawvideo \
-pixel_format yuyv422 \
-video_size 1600x1200 \
frame_1600x1200.yuyv
```
## GStreamer パイプライン
### ライブ raw ストリームを表示する
```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
```
### raw フレームを 1 枚ディスクに保存する
```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 での輝度抽出
raw フレームを下流で処理し、センサーがモノクロの場合、フレームをカラーとして扱うのではなく、輝度チャンネルを抽出します。
```python theme={null}
# YUYV フレームは 3 チャンネル配列として読み込まれ、Y チャンネルが実際の画像
gray = frame[:, :, 0]
```
または YUY2 から明示的に変換します:
```python theme={null}
import cv2
gray = cv2.cvtColor(frame, cv2.COLOR_YUV2GRAY_YUY2)
```
stellarHD を OpenCV で使用する完全なガイドをご覧ください。
## トラブルシューティング
### 出力ファイルのサイズが間違っている
完全な raw フレームは正確に `width × height × 2` バイトです。それより小さいファイルは通常、キャプチャが中断されたか、要求された解像度が YUYV モードでサポートされていないことを意味します — `v4l2-ctl -d /dev/video4 --list-formats-ext` を確認してください。
### 変換された画像が歪んでいたり乱れている
FFmpeg に渡される `-pixel_format` と `-video_size` は、キャプチャと正確に一致する必要があります。Raw ビデオにはヘッダーがないため、不一致があるとレイアウトが破損します。
### モノクロカメラなのに画像に色がついて見える
モノクロセンサーでは彩度チャンネルに実データはありません。上記のように `-vf format=gray`(FFmpeg)で再変換するか、`Y` チャンネルを抽出してください(OpenCV)。
### YUYV のフレームレートが低すぎる
これは想定通りです — 非圧縮ビデオは帯域幅を大量に消費します。解像度を下げ、フレームレートを下げるか、ライブ表示のために MJPEG に切り替えてください。