SingleImage + ROI Decoding (GbE-2 / Python)

Steps for creating a script that uses the common module puclib.py created in HelloWorld to decode only a specified region (ROI: Region of Interest) from a single frame of compressed data captured from the GbE-2, and save it as a PGM image.

Prerequisites

• Common module: puclib.py must be placed in the same folder as the script.
• Required library: numpy (pip install numpy)

1. Create the script

   In the same folder as puclib.py, create gbe2_single_image_roi.py and write the following code.

   gbe2_single_image_roi.py

   from ctypes import c_uint32, c_ushort, c_ubyte, c_void_p, byref
   import numpy as np
   
   # Import from the common module puclib.py
   from puclib import (
       load_sdk, PUC_SUCCEEDED, PUC_DETECT_TARGET_GBE2,
       PUC_Q_COUNT, PUC_DETECT_FILTER, PUC_DETECT_INFO, PUC_XFER_DATA_INFO
   )
   
   def main():
       print("Starting INFINICAM GbE-2 ROI decoding...")
   
       # 1. Load and initialize the SDK
       puclib = load_sdk()
       if puclib.PUC_Initialize() != PUC_SUCCEEDED:
           print("Error: Failed to initialize the SDK.")
           return
   
       # 2. Search for and open the device
       detect_filter = PUC_DETECT_FILTER(nDeviceTypeFlags=PUC_DETECT_TARGET_GBE2)
       detect_info = PUC_DETECT_INFO()
   
       if puclib.PUC_DetectDevice2(byref(detect_filter), byref(detect_info)) != PUC_SUCCEEDED or detect_info.nDeviceCount == 0:
           print("Error: No GbE-2 camera was found.")
           return
   
       h_device = c_void_p()
       if puclib.PUC_OpenDevice2(0, byref(h_device)) != PUC_SUCCEEDED:
           print("Error: Failed to open the device.")
           return
   
       # 3. Retrieve the full resolution and the quantization table
       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 resolution: {full_w.value} x {full_h.value} pixels")
   
       # 4. Set the ROI (Region of Interest) parameters
       # Note: Because compression is done in 8x8 block units, the coordinates
       # and size must always be specified as multiples of 8
       roi_x = 200      # Decode start X coordinate (0 or a multiple of 8)
       roi_y = 150      # Decode start Y coordinate (0 or a multiple of 8)
       roi_w = 400      # ROI width (a multiple of 8)
       roi_h = 300      # ROI height (a multiple of 8)
   
       print(f"ROI settings: position({roi_x}, {roi_y}), size {roi_w} x {roi_h} pixels")
   
       # 5. Allocate buffers
       xfer_data_size = c_uint32()
       puclib.PUC_GetXferDataSize(h_device, byref(xfer_data_size))
   
       comp_buffer = (c_ubyte * xfer_data_size.value)()
   
       # ROI output buffer (allocate memory only for the cropped ROI size)
       roi_line_bytes = (roi_w + 3) & ~3  # 4-byte boundary alignment
       roi_decoded_buffer = (c_ubyte * (roi_line_bytes * roi_h))()
   
       # 6. Perform the single-frame capture
       xfer_info = PUC_XFER_DATA_INFO()
       xfer_info.pData = comp_buffer
       xfer_info.nDataSize = xfer_data_size.value
   
       print("Capturing...")
       if puclib.PUC_GetSingleXferData(h_device, byref(xfer_info)) == PUC_SUCCEEDED:
           # 7. Decode only the specified ROI region
           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. Convert into a NumPy array (shaped to the cropped ROI size)
               img_roi = np.ctypeslib.as_array(roi_decoded_buffer).reshape((roi_h, roi_line_bytes))[:, :roi_w]
   
               # 9. Save as a PGM file
               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: Saved the ROI-cropped image (PGM) ({filename})")
           else:
               print(f"Error: ROI decoding failed. ErrorCode: {ret}")
       else:
           print("Error: Failed to retrieve the image data.")
   
       # 10. Close
       puclib.PUC_CloseDevice(h_device)
   
   
   if __name__ == "__main__":
       main()

2. Run the script

   python gbe2_single_image_roi.py

   After execution finishes, the 400x300-pixel image file roi_captured_image.pgm, cropped from the specified position, is generated.

---

Benefits and Setup Rules for ROI Decoding

1. Major improvements in processing speed and memory efficiency

Because the whole image is never expanded and only the region needed for analysis or monitoring is decoded, the CPU decoding cost and memory footprint can be greatly reduced.

2. Coordinate/size boundary rule (8x8 block units)

Since INFINICAM performs DCT compression in 8x8 pixel block units, the ROI parameters (roi_x, roi_y, roi_w, roi_h) passed to PUC_DecodeData must always be multiples of 8. If a value that is not a multiple of 8 is set, the function returns an error when called.