FG Camera Library  1.7.2.0 (2025-09-18)
Loading...
Searching...
No Matches
C Example

How to build and run the first example program.

Prerequisites

This document requires the user to have successfully walked through the "Getting Started Guide" for logging into the command line of the device. A basic understanding of using the Linux command line is also required.

IMAGO delivers the VisionCam and VisionSensor with a pre-installed Debian Linux root filesystem including development tools like the GNU GCC compiler and the Make utility. Additionally, the IMAGO SDK package provides the required kernel modules and libraries. In order to build and run the example program, there is no need to install or configure anything else.

The example program FGExample_Linux demonstrates the use of the library and can be used with the VisionSensor PV and the VisionCam XM. The source code is located at the following SDK directory:

/opt/ImagoTechnologies/SDK/examples/FGExample_Linux

The example directory contains a Makefile which uses the required library and compiler settings for building the program:

  • GCC compiler options (header search path):
    -I/opt/ImagoTechnologies/SDK/include
  • GCC linker options (library seach path and shared library name):
    -L/opt/ImagoTechnologies/SDK/lib/ -lFGCamera

Build and run the example program

First, copy the source code to your home directory and build the project with 'make':

> cp -r /opt/ImagoTechnologies/SDK/examples/FGExample_Linux ~/
> cd ~/FGExample_Linux
> make

After successful build, the program can be started:

> ./FGExample_Linux

The console output should look like this:

Sensor size: 736 x 480
Starting acquisition, press CTRL-C to stop the program.
100 frames received, current frame number: 4400
100 frames received, current frame number: 4500
100 frames received, current frame number: 4600
100 frames received, current frame number: 4700
...

The program can be stopped by pressing CTRL-C.

Typical workflow

The following steps describe the typical workflow for using the library:

Examine the source code

The example source code is located at /opt/ImagoTechnologies/SDK/examples/FGExample_Linux/src/main.c

Header files

The FG Camera library provides a single header file to the user: FG_CameraInterface.h

Initialization

Open the interface

It's possible to specify the desired hardware and sensor type when opening the interface. The function will fail if the specified type is not available. For sensor independent applications, there is an autodetection type available which is used below:

31 // initialize the camera using automatic type detection
33 if (fgResult != FG_ERROR_CODE_NoError)
34 {
35 FG_get_last_error(ErrText, sizeof(ErrText));
36 printf("FG_install_camera() failed! \n - ErrorCode: %d \n - ErrorText '%s'", fgResult, ErrText);
37 return -1;
38 }

Setup parameters

After opening the interface, some basic parameters are configured. Most of them have default values and are therefore optional. But for better readability we suggest setting them explicitly. For almost every set-function there is also a get-function for reading parameters:

43 // set trigger mode to free-run:
45
46 // get default AOI and pixel type:
47 FG_get_aoi(&x1, &y1, &x2, &y2, &pixel_type);
48 // set new pixel type:
49 FG_set_aoi(x1, y1, x2, y2, FG_PIXEL_TYPE_Y_8);
50
51 // Set the exposure time:
52 FG_set_shutter_time(1000); // 1000 microseconds

Buffer allocation and starting acquisition

The API provides functions for image buffer allocation and management. It's important to note that buffer access is only allowed if the user is the owner. After a buffer is added to the acquisition queue with FG_append_image(), access is forbidden until it's returned to the user by FG_get_image(), or until image acquisition is stopped with FG_stop_image().

The code below shows the buffer allocation and the start of acquisition by adding the buffers to the ready queue:

60 // allocate image buffers and them to the queue
61 for (UINT32 i = 0; i < NUM_BUFFERS; i++)
62 {
63 FG_alloc_image(&imageList[i]);
64 FG_append_image(&imageList[i]);
65 }

Acquisition loop

The function FG_get_image() is used to wait for new images. After success, the function returns the given FG_Image structure with the next valid image buffer and the ownership is transferred back to the user. The example code doesn't implement any image processing, but the pixel buffer can be accessed using the pointer pixel_ptr:

71 while (isRunning)
72 {
73 FG_IMAGE currentImage;
74
75 // wait for the image
76 fgResult = FG_get_image(&currentImage, 1000); // 1000 ms timeout
77 if (fgResult == FG_ERROR_CODE_NoError)
78 {
79 if ((currentImage.image_number % 100) == 0)
80 printf("100 frames received, current frame number: %u\n", currentImage.image_number);
81
82 // todo: work with the image data => currentImage.pixel_ptr[x + y * width];
83
84 // add the buffer again to the free queue again
85 FG_append_image(&currentImage);
86 }
87 else if (fgResult == FG_ERROR_CODE_BrokenImage)
88 {
89 // the image is valid, but the contents are broken or incomplete, add the buffer again or release it
90 printf("FG_get_image() returned a broken image\n");
91 FG_append_image(&currentImage);
92 }
93 else if (fgResult == FG_ERROR_CODE_GrabTimeOut)
94 {
95 // timout occurred, the image is invalid
96 printf("FG_get_image() timeout occurred\n");
97 }
98 else
99 {
100 // other error occured, the image is invalid
101 FG_get_last_error(ErrText, sizeof(ErrText));
102 printf("FG_get_image() failed! \n - ErrorCode: %d \n - ErrorText '%s'", fgResult, ErrText);
103 break;
104 }
105 }

After the user has finished processing the buffer contents, it can be put back to the ready queue by calling FG_append_image(). Please note that ownership of the buffer is also transfered to the user in case of the error value FG_ERROR_CODE_BrokenImage (parital valid image).

Closing the camera interface

After calling FG_stop_image(), all previously allocated buffers can be released and the interface can be closed:

111 // abort image acquisition
113
114 // free buffers
115 for (UINT32 i = 0; i < NUM_BUFFERS; i++)
116 {
117 FG_free_image(&imageList[i]);
118 }
119
120 // close the camera