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 技術仕様を参照してください。

必要環境

これらのコマンドには、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 と 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 の両方は、グループの 最初の ノードで公開されます。

v4l2-ctl --list-devices

出力例:

stellarHD Leader: stellarHD Lea (usb-0000:00:14.0-6):
	/dev/video4   # <-- このノードが YUYV と MJPEG の両方を出力します
	/dev/video5
	/dev/media2

この例では、/dev/video4 を使用するノードです。以下のコマンドでは、ご自身のノードに置き換えてください。

キャプチャの前に、カメラが提供しているフォーマット、解像度、フレームレートを確認します:

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

YUYV(非圧縮 4:2:2)と MJPG(MJPEG 圧縮)の両方のエントリが表示されているはずです。

ステップ 2 — RAW フレームを 1 枚キャプチャする

v4l2-ctl を使用して、フル解像度で非圧縮 YUYV フレームを 1 つキャプチャします:

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 バイトであるべきです:

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

ファイルサイズが一致すれば、完全な raw フレームをキャプチャしたことになります。

ステップ 3 — RAW フレームを PNG に変換する

Raw YUYV バイトは直接表示できません。FFmpeg を使用してフレームを PNG に変換し、検査します:

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(彩度) チャンネルはダミー/固定値であり、無視できます。

モノクロフレームをフルカラーとして変換すると、無意味な彩度データから偽の色合いが表示される可能性があります。グレースケールのみを抽出してください:

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

これは輝度チャンネルのみを使用し、誤った彩度の解釈を回避します。

カメラが本当にモノクロであるかを確認する

ffplay で raw ファイルを直接再生します。画像が自然にグレースケールに見える場合、彩度チャンネルは一定です:

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

GStreamer パイプライン

ライブ raw ストリームを表示する

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

raw フレームを 1 枚ディスクに保存する

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 での輝度抽出

raw フレームを下流で処理し、センサーがモノクロの場合、フレームをカラーとして扱うのではなく、輝度チャンネルを抽出します。

# YUYV フレームは 3 チャンネル配列として読み込まれ、Y チャンネルが実際の画像
gray = frame[:, :, 0]

または YUY2 から明示的に変換します:

import cv2

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

OpenCV ガイド

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 に切り替えてください。

​概要

​必要環境

​YUYV と MJPEG の違いを理解する

​ステップ 1 — デバイスノードの特定

​ステップ 2 — RAW フレームを 1 枚キャプチャする

​フレームサイズを確認する

​ステップ 3 — RAW フレームを PNG に変換する

​モノクロ stellarHD モデル

​カメラが本当にモノクロであるかを確認する

​GStreamer パイプライン

​ライブ raw ストリームを表示する

​raw フレームを 1 枚ディスクに保存する

​MJPEG でより高速なプレビュー

​OpenCV / Python での輝度抽出

OpenCV ガイド

​トラブルシューティング

​出力ファイルのサイズが間違っている

​変換された画像が歪んでいたり乱れている

​モノクロカメラなのに画像に色がついて見える

​YUYV のフレームレートが低すぎる

概要

必要環境

YUYV と MJPEG の違いを理解する

ステップ 1 — デバイスノードの特定

ステップ 2 — RAW フレームを 1 枚キャプチャする

フレームサイズを確認する

ステップ 3 — RAW フレームを PNG に変換する

モノクロ stellarHD モデル

カメラが本当にモノクロであるかを確認する

GStreamer パイプライン

ライブ raw ストリームを表示する

raw フレームを 1 枚ディスクに保存する

MJPEG でより高速なプレビュー

OpenCV / Python での輝度抽出

トラブルシューティング

出力ファイルのサイズが間違っている

変換された画像が歪んでいたり乱れている

モノクロカメラなのに画像に色がついて見える

YUYV のフレームレートが低すぎる