C Example

Table of Contents

• Prerequisites
• Build and run the example program
• Typical workflow
• Examine the source code
  • Header files
  • Initialization
    • Open the interface
    • Setup parameters
    • Buffer allocation and starting acquisition
  • Acquisition loop
  • Closing the camera interface

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:

• Initialization
  • Open and initialize the camera by calling FG_install_camera().
  • Set the trigger mode with FG_set_trigger_mode().
  • The sensor size and current pixel format can be obained by calling FG_get_aoi(). FG_set_aoi() can be used to modify the area of interest and pixel format.
  • Allocate one or more buffers with FG_alloc_image().
  • Enqueue the allocated buffers with FG_append_image(), this will start the image aquisition.
• Acquisition loop
  • If the camera is configured for software triggering (FG_TRIGGER_MODE_SOFTWARE), trigger the next image by calling FG_trigger_image().
  • Wait for a new image by calling FG_get_image().
  • Process the image data.
  • Enqueue the buffer by calling FG_append_image().
• Closing the camera interface
  • Abort all threads waiting in FG_get_image() and force the driver to stop using any buffer by calling FG_stop_image().
  • Release all previously allocated buffers with FG_free_image().
  • Close the camera with FG_uninstall_camera().

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:

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

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:

    // set trigger mode to free-run:
    FG_set_trigger_mode(FG_TRIGGER_MODE_FREERUN);
 
    // get default AOI and pixel type:
    FG_get_aoi(&x1, &y1, &x2, &y2, &pixel_type);
    // set new pixel type:
    FG_set_aoi(x1, y1, x2, y2, FG_PIXEL_TYPE_Y_8);
 
    // Set the exposure time:
    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:

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

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:

    while (isRunning)
    {
        FG_IMAGE currentImage;
 
        // wait for the image
        fgResult = FG_get_image(&currentImage, 1000);   // 1000 ms timeout
        if (fgResult == FG_ERROR_CODE_NoError)
        {
            if ((currentImage.image_number % 100) == 0)
                printf("100 frames received, current frame number: %u\n", currentImage.image_number);
 
            // todo: work with the image data => currentImage.pixel_ptr[x + y * width];
 
            // add the buffer again to the free queue again
            FG_append_image(&currentImage);
        }
        else if (fgResult == FG_ERROR_CODE_BrokenImage)
        {
            // the image is valid, but the contents are broken or incomplete, add the buffer again or release it
            printf("FG_get_image() returned a broken image\n");
            FG_append_image(&currentImage);
        }
        else if (fgResult == FG_ERROR_CODE_GrabTimeOut)
        {
            // timout occured, the image is invalid
            printf("FG_get_image() timeout occured\n");
        }
        else
        {
            // other error occured, the image is invalid
            FG_get_last_error(ErrText, sizeof(ErrText));
            printf("FG_get_image() failed! \n - ErrorCode: %d \n - ErrorText '%s'", fgResult, ErrText);
            break;
        }
    }

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:

    // abort image acquisition
    FG_stop_image();
 
    // free buffers
    for (UINT32 i = 0; i < NUM_BUFFERS; i++)
    {
        FG_free_image(&imageList[i]);
    }
 
    // close the camera
    FG_uninstall_camera();