SingleImage + ROI デコード（GbE-2 / Python）

HelloWorld で作成した共通モジュール puclib.py を使用して、GbE-2 から取得した 1 フレームの圧縮データから 指定した領域（ROI: Region of Interest）だけをピンポイントで復号 し、PGM 画像として保存するスクリプトの作成手順です。

スクリプトの作成

puclib.py と同じフォルダーに gbe2_single_image_roi.py を作成し、以下のコードを記述します。

from ctypes import c_uint32, c_ushort, c_ubyte, c_void_p, byref
import numpy as np

# 共通モジュール puclib.py から読み込み
from puclib import (
    load_sdk, PUC_SUCCEEDED, PUC_DETECT_TARGET_HAWK,
    PUC_Q_COUNT, PUC_DETECT_FILTER, PUC_DETECT_INFO, PUC_XFER_DATA_INFO
)

def main():
    print("INFINICAM GbE-2 ROI デコード処理開始...")

    # 1. SDKのロードと初期化
    puclib = load_sdk()
    if puclib.PUC_Initialize() != PUC_SUCCEEDED:
        print("エラー: SDKの初期化に失敗しました。")
        return

    # 2. デバイスの検索とオープン
    detect_filter = PUC_DETECT_FILTER(nDeviceTypeFlags=PUC_DETECT_TARGET_HAWK)
    detect_info = PUC_DETECT_INFO()

    if puclib.PUC_DetectDevice2(byref(detect_filter), byref(detect_info)) != PUC_SUCCEEDED or detect_info.nDeviceCount == 0:
        print("エラー: GbE-2 カメラが見つかりませんでした。")
        return

    h_device = c_void_p()
    if puclib.PUC_OpenDevice2(0, byref(h_device)) != PUC_SUCCEEDED:
        print("エラー: デバイスのオープンに失敗しました。")
        return

    # 3. 全体解像度および量子化テーブルの取得
    full_w, full_h = c_uint32(), c_uint32()
    puclib.PUC_GetResolution(h_device, byref(full_w), byref(full_h))

    q_vals = (c_ushort * PUC_Q_COUNT)()
    puclib.PUC_GetQuantization2(h_device, q_vals)

    print(f"全体解像度: {full_w.value} x {full_h.value} ピクセル")

    # 4. ROI（関心領域）パラメータの設定
    # ※8x8ブロック単位で圧縮されているため、座標・サイズは必ず 8 の倍数で指定します
    roi_x = 200      # 復号開始 X 座標 (0 または 8の倍数)
    roi_y = 150      # 復号開始 Y 座標 (0 または 8の倍数)
    roi_w = 400      # ROI の幅 (8の倍数)
    roi_h = 300      # ROI の高さ (8の倍数)

    print(f"ROI設定: 位置({roi_x}, {roi_y}), サイズ {roi_w} x {roi_h} ピクセル")

    # 5. バッファの確保
    xfer_data_size = c_uint32()
    puclib.PUC_GetXferDataSize(h_device, byref(xfer_data_size))

    comp_buffer = (c_ubyte * xfer_data_size.value)()

    # ROI 展開先バッファ（切り出す ROI サイズ分のみメモリ確保）
    roi_line_bytes = (roi_w + 3) & ~3  # 4バイト境界アラインメント
    roi_decoded_buffer = (c_ubyte * (roi_line_bytes * roi_h))()

    # 6. 1フレームキャプチャの実行
    xfer_info = PUC_XFER_DATA_INFO()
    xfer_info.pData = comp_buffer
    xfer_info.nDataSize = xfer_data_size.value

    print("キャプチャ実行中...")
    if puclib.PUC_GetSingleXferData(h_device, byref(xfer_info)) == PUC_SUCCEEDED:
        # 7. 指定した ROI 領域のみを復号
        ret = puclib.PUC_DecodeData(
            roi_decoded_buffer,
            roi_x, roi_y,
            roi_w, roi_h,
            roi_line_bytes,
            comp_buffer,
            q_vals
        )

        if ret == PUC_SUCCEEDED:
            # 8. NumPy 配列化 (切り出した ROI サイズで整形)
            img_roi = np.ctypeslib.as_array(roi_decoded_buffer).reshape((roi_h, roi_line_bytes))[:, :roi_w]

            # 9. PGM ファイルとして保存
            filename = "roi_captured_image.pgm"
            with open(filename, "wb") as f:
                header = f"P5\n{roi_w} {roi_h}\n255\n".encode("ascii")
                f.write(header)
                f.write(img_roi.tobytes())

            print(f"SUCCESS: ROI切り出し画像 (PGM) を保存しました ({filename})")
        else:
            print(f"エラー: ROI復号処理に失敗しました。ErrorCode: {ret}")
    else:
        print("エラー: 画像データの取得に失敗しました。")

    # 10. クローズ
    puclib.PUC_CloseDevice(h_device)


if __name__ == "__main__":
    main()

スクリプトの実行
Terminal window
```
python gbe2_single_image_roi.py
```
実行完了後、指定位置から切り出された 400x300 ピクセルの画像ファイル roi_captured_image.pgm が生成されます。

ROI デコードのメリットと設定ルール

1. 処理速度とメモリ効率の大幅な向上

全体画像を展開せず、解析や監視に必要な領域だけをピンポイントで復号するため、CPU のデコード計算コストおよびメモリ占有量を大幅に削減できます。

2. 座標・サイズの境界ルール（8×8 ブロック単位）

INFINICAM は 8×8 ピクセルのブロック単位で DCT 圧縮を行っているため、PUC_DecodeData に指定する ROI パラメータ（roi_x, roi_y, roi_w, roi_h）は必ず 8 の倍数にする必要があります。8 の倍数以外の値を設定した場合は関数実行時にエラーが返ります。