SingleImage (Color PPM Save) Project (GbE-2 / Python)

Steps for creating a script that uses the common module puclib.py created in HelloWorld to capture one frame of compressed data from the GbE-2 (color model), perform color decoding that includes Bayer conversion (demosaicing) and white-balance adjustment, and save the result as a PPM (Portable Pixmap) file.

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

   gbe2_single_image_color.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,
       PUC_COLOR_COLOR
   )
   
   def main():
       print("Starting INFINICAM GbE-2 SingleImage (color) capture...")
   
       # 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. Determine the color model and set the white-balance gain
       color_type = c_uint32()
       puclib.PUC_GetColorType(h_device, byref(color_type))
       if color_type.value != PUC_COLOR_COLOR:
           print("Note: The connected camera was detected as a monochrome model.")
   
       # Set the white-balance gain for each of the R, G, B channels (1.0 = no change)
       puclib.PUC_SetWhiteBalanceGain(1.0, 1.0, 1.0)
   
       # 4. Retrieve camera parameters
       width, height = c_uint32(), c_uint32()
       puclib.PUC_GetResolution(h_device, byref(width), byref(height))
       w, h = width.value, height.value
       print(f"Resolution: {w} x {h} pixels (color)")
   
       q_vals = (c_ushort * PUC_Q_COUNT)()
       puclib.PUC_GetQuantization2(h_device, q_vals)
   
       xfer_data_size = c_uint32()
       puclib.PUC_GetXferDataSize(h_device, byref(xfer_data_size))
   
       # 5. Allocate buffers
       comp_buffer = (c_ubyte * xfer_data_size.value)()
       # Color decode data (24-bit RGB = 3 bytes per pixel)
       # Align the row width in bytes (w * 3) to a 4-byte boundary
       line_bytes = ((w * 3) + 3) & ~3
       decoded_buffer = (c_ubyte * (line_bytes * h))()
   
       # 6. Perform the 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:
           # 7. Color decoding of the compressed data
           # The SDK automatically applies Bayer conversion (demosaicing) and
           # white-balance adjustment internally, expanding the data as
           # RGB data (3 bytes per pixel).
           ret = puclib.PUC_DecodeData(
               decoded_buffer, 0, 0, w, h, line_bytes, comp_buffer, q_vals
           )
   
           if ret == PUC_SUCCEEDED:
               # 8. Convert the ctypes buffer into a NumPy array (remove padding)
               img_np = np.ctypeslib.as_array(decoded_buffer).reshape((h, line_bytes))[:, : w * 3]
   
               # 9. Save the file in PPM (P6) format
               filename = "captured_color_image.ppm"
               with open(filename, "wb") as f:
                   header = f"P6\n{w} {h}\n255\n".encode("ascii")
                   f.write(header)
                   f.write(img_np.tobytes())
   
               print(f"SUCCESS: Saved the PPM color image file ({filename})")
           else:
               print(f"Error: Failed to decode the image data. 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_color.py

   After execution finishes, captured_color_image.ppm will be generated in the current directory.

---

Code Explanation Highlights

1. Determining the color model and white balance

PUC_GetColorType() checks whether the connected camera is a color model, and PUC_SetWhiteBalanceGain() sets the gain for each of the R, G, B channels. During decoding, the SDK automatically applies Bayer conversion (demosaicing) and white-balance adjustment internally, expanding the data as RGB.

color_type = c_uint32()
puclib.PUC_GetColorType(h_device, byref(color_type))
puclib.PUC_SetWhiteBalanceGain(1.0, 1.0, 1.0)

2. Buffer size difference from monochrome

Since the color decode buffer uses 3 RGB bytes per pixel, the rounding calculation for the 4-byte boundary also uses w * 3.

line_bytes = ((w * 3) + 3) & ~3

3. Saving in PPM (P6) format

Just as with PGM (monochrome), no external image-encoding library is needed — writing the decode buffer’s RGB data straight out with a text header is enough to produce a complete color image file.