SingleImage + DC Component Extraction (GbE-2 / Python)

Steps for creating a script that uses the common module puclib.py created in HelloWorld to extract only the DC component (direct-current component) from a single frame of compressed data captured from the GbE-2, and decode and save a 1/8-size lightweight preview image at extremely high speed.

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_dc.py and write the following code.

   gbe2_single_image_dc.py

   from ctypes import c_uint32, 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_DETECT_FILTER, PUC_DETECT_INFO, PUC_XFER_DATA_INFO
   )
   
   def main():
       print("Starting INFINICAM GbE-2 DC component extraction (1/8 preview)...")
   
       # 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 camera resolution parameters
       width, height = c_uint32(), c_uint32()
       puclib.PUC_GetResolution(h_device, byref(width), byref(height))
       w, h = width.value, height.value
   
       xfer_data_size = c_uint32()
       puclib.PUC_GetXferDataSize(h_device, byref(xfer_data_size))
   
       print(f"Original image resolution: {w} x {h} pixels")
   
       # 4. Calculate parameters and allocate buffers for the DC component (1/8-size image)
       dc_w = w // 8
       dc_h = h // 8
       dc_line_bytes = (dc_w + 3) & ~3  # 4-byte boundary alignment
   
       print(f"DC extraction image resolution: {dc_w} x {dc_h} pixels")
   
       comp_buffer = (c_ubyte * xfer_data_size.value)()
       decoded_dc_buffer = (c_ubyte * (dc_line_bytes * dc_h))()
   
       # 5. 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 one frame...")
       if puclib.PUC_GetSingleXferData(h_device, byref(xfer_info)) == PUC_SUCCEEDED:
           # 6. Extract and decode only the DC component (direct-current component)
           # Note: nBlockCountX/Y are specified in "block count" (8x8 units), not pixels
           ret = puclib.PUC_DecodeDCData(
               decoded_dc_buffer, 0, 0, dc_w, dc_h, comp_buffer
           )
   
           if ret == PUC_SUCCEEDED:
               # 7. Convert into a NumPy array (shaped to the 1/8 size)
               img_dc = np.ctypeslib.as_array(decoded_dc_buffer).reshape((dc_h, dc_line_bytes))[:, :dc_w]
   
               # 8. Save as a PGM file
               filename = "dc_preview_image.pgm"
               with open(filename, "wb") as f:
                   header = f"P5\n{dc_w} {dc_h}\n255\n".encode("ascii")
                   f.write(header)
                   f.write(img_dc.tobytes())
   
               print(f"SUCCESS: Saved the DC extraction image (PGM) ({filename})")
           else:
               print(f"Error: Failed to extract the DC component. ErrorCode: {ret}")
       else:
           print("Error: Failed to retrieve the image data.")
   
       # 9. Close
       puclib.PUC_CloseDevice(h_device)
   
   
   if __name__ == "__main__":
       main()

2. Run the script

   python gbe2_single_image_dc.py

   After execution finishes, a very small image file, dc_preview_image.pgm, is instantly generated with its width and height each reduced to 1/8 (for example, 160x128 pixels for a 1280x1024 original).

---

Highlights of DC Component Extraction (PUC_DecodeDCData)

1. Entirely skipping inverse DCT and quantization-table computation

Because only the DC component (direct-current component), which represents the average brightness, is extracted from the 8x8-block DCT-compressed data, the heavy inverse discrete cosine transform (IDCT) and inverse quantization processing are skipped entirely. This allows decoding that is overwhelmingly faster than full-pixel decoding (PUC_DecodeData).

2. Arguments are specified in “block count,” not pixels

Whereas nWidth/nHeight in PUC_DecodeData are in pixel units, nBlockCountX/nBlockCountY in PUC_DecodeDCData specify how many 8x8 blocks to expand. Passing the original image’s resolution directly would request eight times the correct number of blocks and write past the end of the output buffer, so you must always pass dc_w (= w // 8) and dc_h (= h // 8).

3. Use cases

• Real-time, ultra-fast thumbnail rendering: Checking the content of a frame with low processing load.
• Low-load motion detection: Monitoring frame-to-frame differences at reduced resolution and performing a full decode only when significant motion is detected.