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

These are the steps to create a program that changes the resolution (image size), frame rate, and shutter speed parameters of a GbE-2, then captures and decodes one frame of compressed image data under the new settings, saving it in the PGM format (Portable Graymap).

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_SingleImage_Settings.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 capture settings change & SingleImage 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. Change the resolution (width and height)
       UINT32 newWidth = 800;
       UINT32 newHeight = 320;
       ret = PUC_SetResolution(hDevice, newWidth, newHeight);
       if (ret != PUC_SUCCEEDED) {
           printf("Error: Failed to set the resolution. ErrorCode: %d\n", ret);
           PUC_CloseDevice(hDevice);
           return EXIT_FAILURE;
       }
       printf("Changed the resolution: %u x %u pixels\n", newWidth, newHeight);
   
       // 5. Change the frame rate and shutter speed
       UINT32 newFramerate = 1000;      // Frame rate: 1000 fps
       UINT32 newShutterSpeed = 2000;   // Shutter speed: 1/2000 sec
       ret = PUC_SetFramerateShutter(hDevice, newFramerate, newShutterSpeed);
       if (ret != PUC_SUCCEEDED) {
           printf("Error: Failed to set the frame rate/shutter speed. ErrorCode: %d\n", ret);
           PUC_CloseDevice(hDevice);
           return EXIT_FAILURE;
       }
       printf("Changed the capture settings: %u fps, shutter 1/%u sec\n", newFramerate, newShutterSpeed);
   
       // 6. Retrieve the latest resolution, quantization table, and transfer data size after the setting change
       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
       // Buffer to store the compressed data
       unsigned char* pCompressedBuffer = (unsigned char*)malloc(xferDataSize);
   
       // Buffer to store the decoded data (the row width is aligned to a 4-byte boundary)
       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 under the new settings
       PUC_XFER_DATA_INFO xferDataInfo = { 0 };
       xferDataInfo.pData = pCompressedBuffer;
       xferDataInfo.nDataSize = xferDataSize;
   
       printf("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 = "custom_setting_image.pgm";
               FILE* fp = NULL;
   
               if (fopen_s(&fp, filename, "wb") == 0 && fp != NULL) {
                   // Write the PGM header
                   fprintf(fp, "P5\n%u %u\n255\n", width, height);
   
                   // Write the valid image data one row at a time
                   for (UINT32 y = 0; y < height; y++) {
                       fwrite(pDecodedBuffer + (y * lineBytes), sizeof(unsigned char), width, fp);
                   }
                   fclose(fp);
   
                   printf("SUCCESS: Saved the image file (%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 {
           printf("Error: Failed to capture the image data. ErrorCode: %d\n", ret);
       }
   
       // 11. Free the memory and close the device
       free(pCompressedBuffer);
       free(pDecodedBuffer);
       PUC_CloseDevice(hDevice);
   
       return EXIT_SUCCESS;
   }

2. Build and run

   1. Press Ctrl + Shift + B to build.
   2. Run with Ctrl + F5. If an image file at the configured size (800x320), custom_setting_image.pgm, is generated directly under the project folder, it has succeeded.

Notes on changing settings

After changing the resolution or frame rate, the size of the data received from the camera will change. Be sure to call PUC_GetXferDataSize and PUC_GetResolution again to allocate a buffer of the correct size before capturing.

---

Key Configuration APIs and Parameters

Changing the resolution (PUC_SetResolution)

PUC_SetResolution(hDevice, width, height);

• Configurable width/height: Width (e.g. 800), height (e.g. 600, 480, 320, 160, 80).
• Behavior when changed: When you change the resolution, the received data size (PUC_GetXferDataSize) also changes automatically.

Changing the frame rate and shutter speed (PUC_SetFramerateShutter)

PUC_SetFramerateShutter(hDevice, framerate, shutterSpeedFps);

• framerate: The frame rate (e.g. 1000 = 1000 fps).
• shutterSpeedFps: The denominator of the shutter speed (e.g. 2000 = 1/2000 sec).
• Configuration constraint: The shutter speed must be set to a value equal to or faster than the frame rate (e.g. when capturing at 1000 fps, the shutter speed must be 1/1000 sec or faster).