image --- マシンビジョン

image モジュールは OpenMV マシンビジョンスタックの中核です。すべての描画・フィルタリング・変換・特徴抽出ルーチンが操作対象とするメモリ上のピクセルバッファである Image クラスを公開するとともに、それらのルーチンが返す結果オブジェクト（Blob、Line、Circle、Rect、QRCode、AprilTag、DataMatrix、BarCode など）や、それらを構成するために使用するヘルパークラス（Threshold、Histogram、Statistics、HaarCascade、Similarity、Percentile、Displacement、ImageIO）も提供します。

画像の取得

Image を RAM に取り込む方法は 4 通りあります。

  • カメラセンサーからのライブキャプチャ。 csi.CSI.snapshot() を呼び出すと、次のフレームを直接フレームバッファにキャプチャします。返される Image はそのバッファを参照します。

  • ファイルから。 Image コンストラクタにパスを渡します（image.Image("/sd/photo.jpg")）。サポートされているディスク上の形式は BMP、PPM/PGM、JPEG、PNG、および OpenMV の ImageIO 録画形式です。

  • ndarray から。 float32 の (h, w) または (h, w, 3) の ndarray を Image コンストラクタに渡します。ピクセルは 0.0 -- 255.0 からそれぞれ GRAYSCALE または RGB565 の画像にスケーリングされます。ml（または任意の ulab パイプライン）からのテンソル出力を描画可能な画像に戻すために使用します。

  • 空のバッファ。 指定したサイズとピクセル形式で Image を構築すると（image.Image(320, 240, image.RGB565)）、ゼロから描画したり、画像演算用のスクラッチサーフェスとして使用したりできます。

ピクセル形式

すべての Image は以下のいずれかのピクセル形式を持ちます。この選択により、メモリ・処理コスト・実行可能なアルゴリズムのトレードオフが決まります。画像を構築したりカメラセンサーを設定したりする際の pixformat 引数として BINARY、GRAYSCALE、RGB565、BAYER、YUV422、JPEG、PNG を使用します。

  • BINARY (1 bpp) -- 1 ピクセルあたり 1 ビット。最小の形式です。しきい値処理やモルフォロジールーチンで内部的に使用されますが、センサーから直接キャプチャされることはほとんどありません。

  • GRAYSCALE (8 bpp) -- 1 ピクセルあたり 1 バイト（YUV422 の Y チャンネル）。ほとんどのコンピュータビジョンアルゴリズム（AprilTag、エッジ検出、オプティカルフロー）で最も高速な形式です。

  • RGB565 (16 bpp) -- 1 ピクセルあたり 2 バイト、赤 5 ビット / 緑 6 ビット / 青 5 ビット。デフォルトのカラー形式です。

  • BAYER (8 bpp) -- センサーから直接出力される生の Bayer パターンのカラーデータ。カスタムなデモザイク処理を行ったり、必要に応じてデベイヤーする前により多くのピクセルを少ないメモリに格納したりするのに便利です。

  • YUV422 (16 bpp) -- 4:2:2 のクロマサブサンプリングされたカラー、1 ピクセルあたり 2 バイト。フル RGB のコストをかけずにクロマ固有のアルゴリズムを使いたい場合に便利です。

  • JPEG / PNG -- 圧縮されたバッファ。保存やネットワーク送信に最適です。ピクセルレベルの操作を行うには、まず Image.to_grayscale() または Image.to_rgb565() が必要です。

結果の取り扱い

Image の検出 / 特徴抽出メソッドは、反復処理したり組み合わせたりできるオブジェクトを返します。Image.find_blobs() の呼び出しは Blob のリストを返し、Image.find_apriltags() の呼び出しは AprilTag のリストを返す、といった具合です。各結果クラスは検出の幾何学的プロパティ（重心、バウンディングボックス、面積、コード値など）を公開しているため、それらを直接利用したり、描画メソッド（Image.draw_rectangle()、Image.draw_string() など）に渡し戻したりできます。

色空間ヘルパー

このモジュールは、個々のピクセル値を binary / grayscale / RGB / LAB / YUV の色空間間で変換するための小さな純関数も公開しています。これらは、しきい値やパレットエントリを画像演算に渡す前に Python 内で変換する必要がある場合に便利です。画像全体の変換には Image の to_* メソッドを使用してください。これらのヘルパーをループ内で呼び出すよりもはるかに高速です。

クラス

関数

色空間変換ヘルパー

以下の X_to_Y 関数はそれぞれ単一のピクセル値変換を実行します。すべて OpenMV の正規範囲で値を受け取り / 返します。

  • binary -- int 0 -- 1。

  • grayscale -- int 0 -- 255。

  • RGB -- 8 ビット整数の (r, g, b) タプル（各 0 -- 255）。

  • LAB -- (l, a, b) タプル。L は 0 -- 100、A/B は -128 -- 127。

  • YUV -- (y, u, v) タプル。Y は 0 -- 255、U/V は -128 -- 127。

画像全体の変換には Image の to_* メソッドを使用してください。これらのヘルパーをループ内で呼び出すよりもはるかに高速です。

image.binary_to_grayscale(value: int) → int

binary 値を grayscale 値に変換します。

image.binary_to_rgb(value: int) → Tuple[int, int, int]

binary 値を RGB タプルに変換します。

image.binary_to_lab(value: int) → Tuple[int, int, int]

binary 値を LAB タプルに変換します。

image.binary_to_yuv(value: int) → Tuple[int, int, int]

binary 値を YUV タプルに変換します。

image.grayscale_to_binary(value: int) → int

grayscale 値を binary 値に変換します。

image.grayscale_to_rgb(value: int) → Tuple[int, int, int]

grayscale 値を RGB タプルに変換します。

image.grayscale_to_lab(value: int) → Tuple[int, int, int]

grayscale 値を LAB タプルに変換します。

image.grayscale_to_yuv(value: int) → Tuple[int, int, int]

grayscale 値を YUV タプルに変換します。

image.rgb_to_binary(value: Tuple[int, int, int]) → int

RGB タプルを binary 値に変換します。

image.rgb_to_grayscale(value: Tuple[int, int, int]) → int

RGB タプルを grayscale 値に変換します。

image.rgb_to_lab(value: Tuple[int, int, int]) → Tuple[int, int, int]

RGB タプルを LAB タプルに変換します。

image.rgb_to_yuv(value: Tuple[int, int, int]) → Tuple[int, int, int]

RGB タプルを YUV タプルに変換します。

image.lab_to_binary(value: Tuple[int, int, int]) → int

LAB タプルを binary 値に変換します。

image.lab_to_grayscale(value: Tuple[int, int, int]) → int

LAB タプルを grayscale 値に変換します。

image.lab_to_rgb(value: Tuple[int, int, int]) → Tuple[int, int, int]

LAB タプルを RGB タプルに変換します。

image.lab_to_yuv(value: Tuple[int, int, int]) → Tuple[int, int, int]

LAB タプルを YUV タプルに変換します。

image.yuv_to_binary(value: Tuple[int, int, int]) → int

YUV タプルを binary 値に変換します。

image.yuv_to_grayscale(value: Tuple[int, int, int]) → int

YUV タプルを grayscale 値に変換します。

image.yuv_to_rgb(value: Tuple[int, int, int]) → Tuple[int, int, int]

YUV タプルを RGB タプルに変換します。

image.yuv_to_lab(value: Tuple[int, int, int]) → Tuple[int, int, int]

YUV タプルを LAB タプルに変換します。

特徴ディスクリプタ

image.HaarCascade(path: str, stages: int = -1) → Cascade

Haar Cascade を読み込み、Image.find_features() で使用するための Cascade ハンドルを返します。

path には次のいずれかを指定できます。

  • ファームウェア ROM に組み込まれた 2 つのカスケードのいずれかを読み込むためのリテラル文字列 "frontalface" または "eye"、もしくは

  • OpenMV のカスケード変換ツールで生成されたカスタムの .cascade バイナリファイルへのファイルシステムパス。

stages は検出時に評価するカスケードステージ数を選択します。-1 はファイルに格納されているすべてのステージを使用します。この値を小さくすると、誤検出が増える代わりに検出が高速化されます。

image.load_descriptor(path: str) → kp_desc | lbp_desc

path のファイルからディスクリプタを読み込んで返します。ファイル内部のタイプタグによって、どのディスクリプタクラスが再構築されるかが選択されます。

image.save_descriptor(descriptor: kp_desc | lbp_desc, path: str) → None

descriptor（ORB キーポイントまたは LBP ディスクリプタ）を OpenMV ディスクリプタファイル形式で path のファイルにシリアライズします。同じファイルは後で image.load_descriptor() を介して再読み込みできます。

image.match_descriptor(descriptor0, descriptor1, threshold: int = 85, filter_outliers: bool = False) → int | kptmatch

同じタイプの 2 つのディスクリプタをマッチングします。

  • 2 つの LBP ディスクリプタの場合 -- それらの間の整数のハミング距離を返します（小さいほど近い一致です）。

  • 2 つの ORB キーポイントディスクリプタの場合 -- 一致したキーポイントクラスタを記述する kptmatch を返します。threshold を通過する一致がない場合は None を返します。

threshold（0 -- 100）は、キーポイントペアを受け入れる際の ORB マッチングの厳格さを設定します。値を小さくすると、弱い最近傍一致を拒否することでマッチングが厳しくなります。

filter_outliers は、一致したキーポイントの集合全体にわたって RANSAC 形式の外れ値除去を有効にします。2 つのビュー間に単一の剛体変換が期待される場合に使用してください。一致したキーポイントが複数のオブジェクトにまたがる場合は無効にしてください。

ブロブ幾何ヘルパー

これらのヘルパーは（Image.find_blobs() が返す）Blob を受け取り、追加の幾何学的プロパティを必要に応じて計算します。これらは Blob 上ではなくモジュールスコープに存在するため、基本的な find_blobs() の処理パスでは、要求しない限りそのコストを支払いません。

image.get_solidity(blob: blob) → float

blob のソリディティ（blob.pixels / convex_hull_area）を返します。浮動小数点数で 0 -- 1。1.0 はブロブが凸包を完全に満たしていることを意味します。

image.get_convexity(blob: blob) → float

blob の凸性（convex_hull_perimeter / blob.perimeter）を返します。浮動小数点数で 0 -- 1。1.0 は完全に凸なブロブです。

image.get_major_axis_line(blob: blob) → line

blob の主軸（最小面積回転矩形の 2 つの主軸のうち長い方）に沿った Line を返します。

image.get_minor_axis_line(blob: blob) → line

blob の副軸（最小面積回転矩形の 2 つの主軸のうち短い方）に沿った Line を返します。

image.get_enclosing_circle(blob: blob) → circle

blob を囲む Circle を返します。

image.get_enclosed_ellipse(blob: blob) → Tuple[int, int, int, int, int]

blob の周囲の最小面積回転矩形に内接する楕円を記述する 5 要素タプル (cx, cy, a, b, rotation) を返します。

  • cx / cy -- 楕円の中心（ピクセル単位、整数）。

  • a / b -- 半軸の長さ（ピクセル単位、整数）。

  • rotation -- 楕円の回転 （度単位）（整数）。

これは attrtuple ではなくプレーンなタプルなので、フィールドにはインデックスでのみアクセスできます。

定数

ピクセル形式

以下のいずれかを Image コンストラクタの pixformat 引数、または csi.CSI.pixformat() に渡します。

image.BINARY: int

1 ピクセルあたり 1 ビットのビットマップ。最小の形式です。しきい値処理やモルフォロジーで内部的に使用され、センサーから直接キャプチャされることはほとんどありません。

image.GRAYSCALE: int

1 ピクセルあたり 8 ビットの grayscale（1 ピクセルあたり 1 バイト）。ほとんどのコンピュータビジョンアルゴリズム（AprilTag、エッジ検出、オプティカルフロー）で最も高速な形式です。

image.RGB565: int

赤 5 ビット / 緑 6 ビット / 青 5 ビットとしてパックされた、1 ピクセルあたり 16 ビットのカラー。デフォルトのカラー形式です。

image.BAYER: int

センサーから直接出力される、1 ピクセルあたり 8 ビットの生の Bayer データ。ほとんどの画像処理メソッドは Bayer 画像では利用できません。必要に応じてデベイヤーしたい場合や、より多くのピクセルを少ないメモリに格納したい場合に使用します。

image.YUV422: int

4:2:2 のクロマサブサンプリングされたカラー、1 ピクセルあたり 2 バイト、ピクセルペアごとに Y1, U, Y2, V としてパックされます。一部の画像処理メソッドのみが YUV422 上で直接動作します。

image.JPEG: int

圧縮された JPEG バッファ。ピクセルレベルの操作を行うには、まず Image.to_grayscale() または Image.to_rgb565() が必要です。

image.PNG: int

圧縮された PNG バッファ。ピクセルレベルの操作を行うには、まず Image.to_grayscale() または Image.to_rgb565() が必要です。

カラーパレット

grayscale 画像をカラー化するために、以下のいずれかを Image.to_rainbow()、Image.to_ironbow()、Image.draw_image()（color_palette=）、または csi.CSI.color_palette() に渡します。

image.PALETTE_RAINBOW: int

滑らかな虹色のカラーホイール。サーマル画像用のデフォルトの OpenMV パレットです。

image.PALETTE_IRONBOW: int

FLIR Lepton サーマルビューファインダーの見た目を模した非線形の「ironbow」パレット。

image.PALETTE_DEPTH: int

深度画像用パレット。深度センサーサポート付きのビルド（ToF パイプライン -- 例えば OpenMV Cam AE3 や ToF Pmod を取り付けた任意のカメラ）でのみ利用可能です。

image.PALETTE_EVT_DARK: int

暗い背景上で GENX320 イベントカメラのフレームを可視化するためのパレット。csi.CSI.color_palette に渡すと、GENX320 ドライバがヒストグラムモードでカラー化された RGB565 フレームを出力するようになります。また、grayscale のイベント画像をカラー化する際には Image.draw_image() の color_palette= に渡します。

GENX320 サポート付きのビルド（OpenMV Cam AE3 および GENX320 Pmod）でのみ利用可能です。

image.PALETTE_EVT_LIGHT: int

明るい背景上で GENX320 イベントカメラのフレームを可視化するためのパレット。ディスパッチと利用可能条件は PALETTE_EVT_DARK と同じです。

スケーリングモード

以下のいずれかを Image.draw_image()、Image.scale()、または同様のスケーリングメソッドの hint 引数として渡します。

image.AREA: int

面積平均スケーラー。縮小時に使用されます。拡大時には最近傍法が使用されます。

image.BILINEAR: int

バイリニアスケーラー。縮小時にはサブサンプリングします。

image.BICUBIC: int

バイキュービックスケーラー。BILINEAR よりも高品質ですが低速です。縮小時にはサブサンプリングします。

描画 / draw_image ヒント

これらの任意の組み合わせをビット OR で結合し、Image.draw_image() の hint 引数として渡します。

image.VFLIP: int

描画時にソースを垂直方向に反転します。

image.HMIRROR: int

描画時にソースを水平方向にミラーリングします。

image.TRANSPOSE: int

描画時にソースを転置します（x/y を入れ替えます）。

image.CENTER: int

ソースを描画先の中央に配置します。明示的な x/y オフセットは、左上からのオフセットではなく中央からのオフセットになります。

image.EXTRACT_RGB_CHANNEL_FIRST: int

Image.draw_image() を介して RGB チャンネルを抽出する際に、スケーリングの 前 にチャンネルを抽出します。このヒントがない場合、チャンネルはスケーリング後に抽出されます。

image.APPLY_COLOR_PALETTE_FIRST: int

Image.draw_image() を介してカラーパレットを適用する際に、スケーリングの 前 にパレットを適用します。このヒントがない場合、パレットはスケーリング後に適用されます。

image.SCALE_ASPECT_KEEP: int

アスペクト比を維持しながら、ソースを描画先の内側に収まるようにスケーリングします（比率が異なる場合はレターボックス表示になります）。

image.SCALE_ASPECT_EXPAND: int

アスペクト比を維持しながら、ソースを描画先いっぱいに満たすようにスケーリングします（比率が異なる場合はクロップされます）。

image.SCALE_ASPECT_IGNORE: int

アスペクト比を無視して、ソースを描画先いっぱいに満たすようにスケーリングします。

image.BLACK_BACKGROUND: int

描画先が既知の黒であることをアルファブレンディングの処理パスに伝え、描画先ピクセルの読み戻しをスキップできるようにします。新しくクリアされたバッファ上でのアルファ効果を高速化します。

image.ROTATE_90: int

VFLIP | TRANSPOSE のショートカット（時計回りに 90 度回転）。

image.ROTATE_180: int

HMIRROR | VFLIP のショートカット（180 度回転）。

image.ROTATE_270: int

HMIRROR | TRANSPOSE のショートカット（時計回りに 270 度回転）。

JPEG サブサンプリング

JPEG を書き込む際に、以下のいずれかを Image.to_jpeg()、Image.compress()、または Image.save() の subsampling 引数として渡します。

image.JPEG_SUBSAMPLING_AUTO: int

JPEG 品質設定に基づいてクロマサブサンプリングを自動的に選択します。

image.JPEG_SUBSAMPLING_444: int

4:4:4 クロマサブサンプリングを強制します（クロマ圧縮なし）。

image.JPEG_SUBSAMPLING_422: int

4:2:2 クロマサブサンプリングを強制します。4:2:0 で正しく動作しないサードパーティの動画プレーヤーに MJPEG をストリーミングする場合に推奨されます。

image.JPEG_SUBSAMPLING_420: int

4:2:0 クロマサブサンプリングを強制します。

テンプレートマッチング

以下のいずれかを Image.find_template() の search 引数として渡します。

image.SEARCH_EX: int

全数探索 -- ROI 内のすべての位置を評価します。最も低速ですが、最良の一致を見つけることが保証されます。

image.SEARCH_DS: int

ダイヤモンド探索 -- 粗から細への探索で、SEARCH_EX よりはるかに高速ですが、自己相似性の高いテンプレートでは大域的最適解を見逃す可能性があります。

エッジ検出

以下のいずれかを Image.find_edges() の algorithm 引数として渡します。

image.EDGE_CANNY: int

Canny エッジ検出器 -- 勾配の大きさ + 非最大抑制 + ヒステリシス。高品質ですが低速です。

image.EDGE_SIMPLE: int

しきい値処理されたハイパスフィルタのエッジ検出器。高速ですが、EDGE_CANNY よりも太くノイズの多いエッジを生成します。

ORB コーナー検出器

以下のいずれかを Image.find_keypoints() の corner_detector 引数として渡します。

image.CORNER_FAST: int

FAST コーナー検出器。CORNER_AGAST よりも高速ですが精度は劣ります。

image.CORNER_AGAST: int

AGAST コーナー検出器。CORNER_FAST よりも低速ですが、より安定したキーポイントを生成します。

AprilTag ファミリー

以下の任意の組み合わせをビット OR で結合し、Image.find_apriltags() の families 引数として渡します。各ファミリーはファームウェアの独自のビルドオプションによって制御されます。サポートされていないファミリーは、常にゼロになるのではなく実行時に存在しません。

image.TAG16H5: int

AprilTag 16h5 ファミリー（30 個の一意な ID、0 ビット誤り訂正）。

image.TAG25H9: int

AprilTag 25h9 ファミリー（35 個の一意な ID、最大 3 ビット誤り訂正）。

image.TAG36H10: int

AprilTag 36h10 ファミリー（2320 個の一意な ID、最大 3 ビット誤り訂正）。

image.TAG36H11: int

AprilTag 36h11 ファミリー（587 個の一意な ID、最大 4 ビット誤り訂正）。最も一般的なファミリーです。

image.TAGCIRCLE21H7: int

AprilTag Circle21h7 ファミリー。

image.TAGCIRCLE49H12: int

AprilTag Circle49h12 ファミリー。

image.TAGCUSTOM48H12: int

AprilTag Custom48h12 ファミリー。

image.TAGSTANDARD41H12: int

AprilTag Standard41h12 ファミリー。

image.TAGSTANDARD52H13: int

AprilTag Standard52h13 ファミリー。

バーコードシンボル体系

Image.find_barcodes() が返すエントリについて BarCode.type で報告される値です。

image.EAN2: int

EAN-2 補助バーコード。

image.EAN5: int

EAN-5 補助バーコード。

image.EAN8: int

EAN-8 バーコード。

image.UPCE: int

UPC-E バーコード。

image.ISBN10: int

ISBN-10 バーコード。

image.UPCA: int

UPC-A バーコード。

image.EAN13: int

EAN-13 バーコード。

image.ISBN13: int

ISBN-13 バーコード。

image.I25: int

インターリーブ 2 of 5 バーコード。

image.DATABAR: int

GS1 DataBar バーコード。

image.DATABAR_EXP: int

GS1 DataBar Expanded バーコード。

image.CODABAR: int

Codabar バーコード。

image.CODE39: int

Code 39 バーコード。

image.PDF417: int

PDF417 2D スタックバーコード。この定数は完全性のために存在しますが、バーコードデコーダは現在 PDF417 を実装していません。Image.find_barcodes() はこのタイプの検出結果を返しません。

image.CODE93: int

Code 93 バーコード。

image.CODE128: int

Code 128 バーコード。