External Device Synchronization + SingleImage (GbE-2 / C++)

These are the steps to configure external synchronization mode, in which the GbE-2 captures in sync with an external pulse signal (SYNC IN), and to create a program that captures one frame of image data and saves it in the PGM format.

Prerequisites

The steps for creating a new project and configuring the include/library paths are the same as in Creating the HelloWorld Project. Make sure the build configuration is set to x64.

1. Write the source code

   Open the main file (e.g. GbE2_ExternalSync.cpp) and replace its contents with the following code.

   #include <stdio.h>
   #include <stdlib.h>
   #include <PUCLIB.h> // Load the PUCLIB header
   
   int main() {
       printf("Starting INFINICAM GbE-2 external device synchronization setup & capture...\n");
   
       // 1. Initialize the SDK
       PUCRESULT ret = PUC_Initialize();
       if (ret != PUC_SUCCEEDED) {
           printf("Error: Failed to initialize the SDK. ErrorCode: %d\n", ret);
           return EXIT_FAILURE;
       }
   
       // 2. Search for a GbE-2 device on the network
       PUC_DETECT_FILTER filter = { 0 };
       filter.nDeviceTypeFlags = PUC_DETECT_TARGET_GBE2; // Specify GbE-2
   
       PUC_DETECT_INFO detectInfo = { 0 };
       ret = PUC_DetectDevice2(&filter, &detectInfo);
       if (ret != PUC_SUCCEEDED || detectInfo.nDeviceCount == 0) {
           printf("Error: No GbE-2 camera was found. ErrorCode: %d\n", ret);
           return EXIT_FAILURE;
       }
   
       // 3. Open the first detected device
       PUC_HANDLE hDevice = NULL;
       ret = PUC_OpenDevice2(0, &hDevice);
       if (ret != PUC_SUCCEEDED) {
           printf("Error: Failed to open the device. ErrorCode: %d\n", ret);
           return EXIT_FAILURE;
       }
   
       // 4. Configure the desired frame rate and shutter speed in advance
       // Note: Capture parameters must be set before configuring external synchronization
       PUC_SetFramerateShutter(hDevice, 1000, 1000); // 1000 fps, shutter 1/1000 sec
   
       // 5. Switch to external device synchronization mode (positive polarity pulse)
       // 2nd argument: PUC_SYNC_EXTERNAL (external sync), 3rd argument: PUC_SIGNAL_POSI (positive polarity)
       ret = PUC_SetSyncInMode(hDevice, PUC_SYNC_EXTERNAL, PUC_SIGNAL_POSI);
       if (ret != PUC_SUCCEEDED) {
           printf("Error: Failed to set external synchronization mode. ErrorCode: %d\n", ret);
           PUC_CloseDevice(hDevice);
           return EXIT_FAILURE;
       }
       printf("Set to external device synchronization (positive polarity).\n");
   
       // 6. Get the resolution, quantization table, and transfer data size
       UINT32 width = 0, height = 0;
       PUC_GetResolution(hDevice, &width, &height);
   
       unsigned short qVals[PUC_Q_COUNT] = { 0 };
       PUC_GetQuantization2(hDevice, qVals);
   
       UINT32 xferDataSize = 0;
       PUC_GetXferDataSize(hDevice, &xferDataSize);
   
       // 7. Allocate memory buffers
       unsigned char* pCompressedBuffer = (unsigned char*)malloc(xferDataSize);
   
       UINT32 lineBytes = (width + 3) & ~3;
       unsigned long decodedBufferSize = (unsigned long)lineBytes * height;
       unsigned char* pDecodedBuffer = (unsigned char*)malloc(decodedBufferSize);
   
       if (pCompressedBuffer == NULL || pDecodedBuffer == NULL) {
           printf("Error: Memory allocation failed.\n");
           free(pCompressedBuffer);
           free(pDecodedBuffer);
           PUC_CloseDevice(hDevice);
           return EXIT_FAILURE;
       }
   
       // 8. Capture one frame of data synchronized to the external sync signal
       PUC_XFER_DATA_INFO xferDataInfo = { 0 };
       xferDataInfo.pData = pCompressedBuffer;
       xferDataInfo.nDataSize = xferDataSize;
   
       printf("Waiting for the external sync pulse (capturing)...\n");
       ret = PUC_GetSingleXferData(hDevice, &xferDataInfo);
   
       if (ret == PUC_SUCCEEDED) {
           // 9. Decode the compressed data
           ret = PUC_DecodeData(pDecodedBuffer, 0, 0, width, height, lineBytes, pCompressedBuffer, qVals);
   
           if (ret == PUC_SUCCEEDED) {
               // 10. Save the decoded image in PGM (P5) format
               const char* filename = "ext_sync_image.pgm";
               FILE* fp = NULL;
   
               if (fopen_s(&fp, filename, "wb") == 0 && fp != NULL) {
                   fprintf(fp, "P5\n%u %u\n255\n", width, height);
   
                   for (UINT32 y = 0; y < height; y++) {
                       fwrite(pDecodedBuffer + (y * lineBytes), sizeof(unsigned char), width, fp);
                   }
                   fclose(fp);
   
                   printf("SUCCESS: Saved the externally synchronized capture image (%s)\n", filename);
               } else {
                   printf("Error: Failed to save the file.\n");
               }
           } else {
               printf("Error: Failed to decode the image data. ErrorCode: %d\n", ret);
           }
       } else {
           // This results in an error if no external signal is applied or if a timeout occurs
           printf("Error: Failed to capture the image data (no external signal applied, or timeout). ErrorCode: %d\n", ret);
       }
   
       // 11. Cleanup (restore internal synchronization mode before exiting)
       PUC_SetSyncInMode(hDevice, PUC_SYNC_INTERNAL, PUC_SIGNAL_POSI);
       free(pCompressedBuffer);
       free(pDecodedBuffer);
       PUC_CloseDevice(hDevice);
   
       return EXIT_SUCCESS;
   }

2. Build and run

   1. Press Ctrl + Shift + B to build.
   2. Connect an external signal source (such as a function generator) to the SYNC IN terminal of the GbE-2.
   3. Run with Ctrl + F5. Capture occurs in sync with the external signal input, and if ext_sync_image.pgm is generated directly under the execution folder, it has succeeded.

Notes when no external sync signal (SYNC IN) is applied

When set to external device synchronization mode (PUC_SYNC_EXTERNAL), the camera will not perform exposure or image data transfer until a sync pulse is input to the SYNC IN port from an external source.

If the sync signal line is not physically connected, or if no signal is being output, calling PUC_GetSingleXferData or PUC_BeginXferData will fail to receive data and result in a timeout error, preventing image data transmission and saving. When testing, be sure to either keep an external signal applied, or use PUC_SetSyncInMode to switch back to PUC_SYNC_INTERNAL (internal synchronization) after the connection test.

---

Key Points for Configuring External Device Synchronization

1. Synchronization mode configuration function (PUC_SetSyncInMode)

PUC_SetSyncInMode(hDevice, nMode, nSignal);

• nMode: Specifies the synchronization input mode.
  • PUC_SYNC_INTERNAL : Internal synchronization (free-running capture using the camera’s internal clock)
  • PUC_SYNC_EXTERNAL : External signal synchronization (synchronized to pulses input to the SYNC IN port)
  • PUC_SYNC_EXTERNAL_PTP : Synchronization to a PTP (Precision Time Protocol) master clock
• nSignal: Specifies the rising/falling edge (polarity).
  • PUC_SIGNAL_POSI : Positive polarity (synchronized to the rising edge)
  • PUC_SIGNAL_NEGA : Negative polarity (synchronized to the falling edge)

2. About the order of configuration

When external device synchronization is configured, the camera automatically adjusts the exposure time to account for variation in the input pulse. For this reason, always change to the desired frame rate and shutter speed using PUC_SetFramerateShutter (or PUC_SetExposeTime) before calling PUC_SetSyncInMode.