External Device Synchronization Settings (GbE-2 / Python)

Steps for creating a script that uses the common module puclib.py created in HelloWorld to start capturing with the GbE-2 synchronized to an external trigger pulse signal (SYNC IN).

Create the script

In the same folder as puclib.py, create gbe2_external_sync.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
)

# Sync mode constants (PUC_SYNC_MODE)
PUC_SYNC_INTERNAL = 0  # Internal clock (normal capture)
PUC_SYNC_EXTERNAL = 1  # External signal synchronization (SYNC IN)

# Signal polarity constants (PUC_SIGNAL)
PUC_SIGNAL_POSI = 0  # Positive polarity (rising-edge synchronization)

def main():
    print("Starting INFINICAM GbE-2 external device synchronization (SYNC IN) 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. Enable external synchronization (SYNC IN) mode
    # =========================================================
    # PUC_SetSyncInMode(hDevice, nMode, nSignal)
    # nMode   : PUC_SYNC_INTERNAL (internal clock) / PUC_SYNC_EXTERNAL (external input sync)
    # nSignal : Polarity (PUC_SIGNAL_POSI = positive polarity / PUC_SIGNAL_NEGA = negative polarity)
    ret_sync = puclib.PUC_SetSyncInMode(h_device, PUC_SYNC_EXTERNAL, PUC_SIGNAL_POSI)
    if ret_sync == PUC_SUCCEEDED:
        print("Set external trigger synchronization mode (SYNC IN).")
    else:
        print(f"Error: Failed to set external synchronization mode. ErrorCode: {ret_sync}")
        puclib.PUC_CloseDevice(h_device)
        return

    # 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

    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"Resolution: {w} x {h} pixels")

    # 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 capture (wait for an external trigger signal)
    xfer_info = PUC_XFER_DATA_INFO()
    xfer_info.pData = comp_buffer
    xfer_info.nDataSize = xfer_data_size.value

    print("\nWaiting for an external trigger signal (SYNC IN)...")
    print("The capture will be performed once a signal is input from the external device.")

    ret_xfer = puclib.PUC_GetSingleXferData(h_device, byref(xfer_info))

    if ret_xfer == PUC_SUCCEEDED:
        print("Received the trigger signal. Decoding...")

        # 7. Decode processing
        ret_dec = puclib.PUC_DecodeData(
            decoded_buffer, 0, 0, w, h, line_bytes, comp_buffer, q_vals
        )

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

            # 9. Save as a PGM file
            filename = "external_sync_captured.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 externally triggered synchronized image ({filename})")
        else:
            print(f"Error: Failed to decode the image data. ErrorCode: {ret_dec}")
    else:
        print(f"Error: An error occurred while waiting for the trigger, or the wait timed out. ErrorCode: {ret_xfer}")

    # 10. Close processing (switch back to internal sync mode before closing)
    puclib.PUC_SetSyncInMode(h_device, PUC_SYNC_INTERNAL, PUC_SIGNAL_POSI)
    puclib.PUC_CloseDevice(h_device)


if __name__ == "__main__":
    main()

Run the script
Terminal window
```
python gbe2_external_sync.py
```
When a pulse signal is input from the external device, one frame is captured and saved as external_sync_captured.pgm.

External Synchronization Capture Highlights

1. Switching operating modes with `PUC_SetSyncInMode`

Setting PUC_SYNC_EXTERNAL on PUC_SetSyncInMode stops the camera’s continuous exposure driven by the internal clock, and switches it into a mode where it captures and transfers a frame only when a pulse signal is input from the external connector (SYNC IN). The third argument, PUC_SIGNAL_POSI (positive polarity) / PUC_SIGNAL_NEGA (negative polarity), specifies the polarity of the edge detected as a trigger.

2. Timeout when no trigger is received

If no external trigger signal is received within a certain period, PUC_GetSingleXferData either remains blocked (waiting for a response) or returns a timeout error. Before the program exits, it is safer to switch the setting back to PUC_SYNC_INTERNAL (internal synchronization) before closing the device.

External Device Synchronization Settings (GbE-2 / Python)

External Synchronization Capture Highlights

1. Switching operating modes with PUC_SetSyncInMode

2. Timeout when no trigger is received

1. Switching operating modes with `PUC_SetSyncInMode`