Changing Capture Settings + SingleImage (GbE-2 / Python)

Steps for creating a script that uses the common module puclib.py created in HelloWorld to change the GbE-2’s resolution, frame rate (FPS), and shutter speed (exposure time) from a program, then capture and save one frame of image data.

Create the script

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

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 capture-settings sample...")

    # 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. Change the capture settings
    # =========================================================
    target_width = 640
    target_height = 480
    target_fps = 1000
    target_shutter = 20000  # 1/20000 sec

    print(f"\n[Requested settings] Resolution: {target_width}x{target_height}, Frame rate: {target_fps}fps, Shutter: 1/{target_shutter}sec")

    # Set the resolution
    ret_res = puclib.PUC_SetResolution(h_device, target_width, target_height)
    if ret_res != PUC_SUCCEEDED:
        print(f"Warning: Failed to change the resolution. ErrorCode: {ret_res}")

    # Set the frame rate and shutter speed
    ret_fps = puclib.PUC_SetFramerateShutter(h_device, target_fps, target_shutter)
    if ret_fps != PUC_SUCCEEDED:
        print(f"Warning: Failed to change the frame rate. ErrorCode: {ret_fps}")


    # =========================================================
    # 4. Retrieve the resulting parameters (confirmation)
    # =========================================================
    # Due to hardware constraints on the camera, the requested values may be
    # rounded to the nearest valid value. For this reason, after changing the
    # settings, always re-fetch the current state before performing buffer
    # calculations and the like.
    actual_w, actual_h = c_uint32(), c_uint32()
    puclib.PUC_GetResolution(h_device, byref(actual_w), byref(actual_h))
    w, h = actual_w.value, actual_h.value

    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))

    print(f"[Resulting settings] Resolution: {w}x{h} pixels (allocated data size: {xfer_data_size.value} bytes)\n")

    # 5. Allocate buffers
    comp_buffer = (c_ubyte * xfer_data_size.value)()
    line_bytes = (w + 3) & ~3  # 4-byte boundary alignment
    decoded_buffer = (c_ubyte * (line_bytes * 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 one frame...")
    if puclib.PUC_GetSingleXferData(h_device, byref(xfer_info)) == PUC_SUCCEEDED:
        # 7. Decode processing
        ret = puclib.PUC_DecodeData(
            decoded_buffer, 0, 0, w, h, line_bytes, comp_buffer, q_vals
        )

        if ret == PUC_SUCCEEDED:
            # 8. Convert into a NumPy array (remove padding)
            img_np = np.ctypeslib.as_array(decoded_buffer).reshape((h, line_bytes))[:, :w]

            # 9. Save as a PGM file
            filename = "settings_captured_image.pgm"
            with open(filename, "wb") as f:
                header = f"P5\n{w} {h}\n255\n".encode("ascii")
                f.write(header)
                f.write(img_np.tobytes())

            print(f"SUCCESS: Saved the image captured under the new settings ({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()

Run the script
Terminal window
```
python gbe2_single_image_settings.py
```
When run, the camera’s resolution is changed to 640x480 and the frame rate to 1000 fps (shutter 1/20,000 sec), a capture is performed, and the result is saved as settings_captured_image.pgm.

Capture-Settings Change Highlights

1. Changing the resolution with `PUC_SetResolution`

Changing the resolution also changes the data size transferred per frame (XferDataSize). Immediately after changing the resolution, be sure to call PUC_GetXferDataSize again to recalculate the size of the receive buffer.

2. Rounding values to match camera specifications

If the requested resolution or frame rate violates the sensor’s hardware constraints (for example, exceeding the maximum FPS available at the specified resolution), the SDK may return an error, or it may automatically round the parameter to the nearest valid value. For this reason, it is recommended that after calling PUC_Set..., you always call the corresponding PUC_Get... function to retrieve and confirm the setting actually applied to the camera.

Changing Capture Settings + SingleImage (GbE-2 / Python)

Capture-Settings Change Highlights

1. Changing the resolution with PUC_SetResolution

2. Rounding values to match camera specifications

1. Changing the resolution with `PUC_SetResolution`