FG Camera Library  1.2.8.0
First Steps

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  fgResult = FG_get_aoi(&x1, &y1, &x2, &y2, &pixel_type);
48  // set new pixel type:
49  fgResult = FG_set_aoi(x1, y1, x2, y2, FG_PIXEL_TYPE_Y_8);
50 
51  // Set the exposure time:
52  fgResult = 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  fgResult = FG_alloc_image(&imageList[i]);
64  fgResult = 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 occured, the image is invalid
96  printf("FG_get_image() timeout occured\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
112  fgResult = FG_stop_image();
113 
114  // free buffers
115  for (UINT32 i = 0; i < NUM_BUFFERS; i++)
116  {
117  fgResult = FG_free_image(&imageList[i]);
118  }
119 
120  // Close the camera
121  fgResult = FG_uninstall_camera();
FG_get_image
UINT32 DLL_FG_API FG_get_image(FG_IMAGE *img, UINT32 TimeOut_ms)
Waits, for a configured time span, for a new image.
Definition: FG_CameraInterface.cpp:573
FG_get_aoi
UINT32 DLL_FG_API FG_get_aoi(UINT32 *x1, UINT32 *y1, UINT32 *x2, UINT32 *y2, enum eFG_PIXEL_TYPE *pixel_type)
Returns the area of interest and output format.
Definition: FG_CameraInterface.cpp:632
FG_get_last_error
UINT32 DLL_FG_API FG_get_last_error(char *error_sting, UINT32 max_string_size)
Returns to the last FG_ERROR_CODE_ExtraErrorInformation; a detailed human-readable description.
Definition: FG_CameraInterface.cpp:485
FG_install_camera
UINT32 DLL_FG_API FG_install_camera(enum eFG_CAMERA_TYPE camera_type)
Opens and initializes the camera.
Definition: FG_CameraInterface.cpp:280
FG_ERROR_CODE_GrabTimeOut
@ FG_ERROR_CODE_GrabTimeOut
No new image was completely captured until the timeout timed out, prt is invalid [5]
Definition: FG_CameraInterface.h:125
FG_stop_image
UINT32 DLL_FG_API FG_stop_image(void)
Forces the camera to stop grabbing and using any buffers.
Definition: FG_CameraInterface.cpp:601
FG_IMAGE
Information about one image.
Definition: FG_CameraInterface.h:142
FG_CAMERA_TYPE_X_X_IMAGO_Vxx_AUTO
@ FG_CAMERA_TYPE_X_X_IMAGO_Vxx_AUTO
IMAGO VisionCam/Sensor (automatic)
Definition: FG_CameraInterface.h:53
FG_ERROR_CODE_BrokenImage
@ FG_ERROR_CODE_BrokenImage
The image was broken or incomplete, but the pointer (with the full size) is valid [6]
Definition: FG_CameraInterface.h:126
FG_free_image
UINT32 DLL_FG_API FG_free_image(FG_IMAGE *img)
Frees a previously allocated buffer.
Definition: FG_CameraInterface.cpp:547
FG_set_aoi
UINT32 DLL_FG_API FG_set_aoi(UINT32 x1, UINT32 y1, UINT32 x2, UINT32 y2, enum eFG_PIXEL_TYPE pixel_type)
Sets the area of interest and output format.
Definition: FG_CameraInterface.cpp:620
FG_set_shutter_time
UINT32 DLL_FG_API FG_set_shutter_time(UINT32 shutter_time_us)
Sets exposure time in ┬Ás.
Definition: FG_CameraInterface.cpp:761
FG_TRIGGER_MODE_FREERUN
@ FG_TRIGGER_MODE_FREERUN
Free-run triggered mode.
Definition: FG_CameraInterface.h:135
FG_ERROR_CODE_NoError
@ FG_ERROR_CODE_NoError
The function was successful, [0]
Definition: FG_CameraInterface.h:121
FG_append_image
UINT32 DLL_FG_API FG_append_image(FG_IMAGE *img)
Puts a new image buffer into the free image queue.
Definition: FG_CameraInterface.cpp:560
FG_alloc_image
UINT32 DLL_FG_API FG_alloc_image(FG_IMAGE *img)
Allocates a new buffer, which can hold as a minimum a complete image.
Definition: FG_CameraInterface.cpp:534
FG_IMAGE::image_number
const UINT32 image_number
Image number, is counting up with every new image.
Definition: FG_CameraInterface.h:148
FG_set_trigger_mode
UINT32 DLL_FG_API FG_set_trigger_mode(enum eFG_TRIGGER_MODE trigger_mode)
Sets the trigger mode.
Definition: FG_CameraInterface.cpp:657
FG_PIXEL_TYPE_Y_8
@ FG_PIXEL_TYPE_Y_8
1 byte per pixel, can be monochrome or raw bayer values (depending on the sensor)
Definition: FG_CameraInterface.h:101
FG_uninstall_camera
UINT32 DLL_FG_API FG_uninstall_camera(void)
Uninstalls a currently open camera.
Definition: FG_CameraInterface.cpp:439