FFC Wizard Sample Program

Euresys provides the source code of a sample application, called ffc-wizard, that computes the coefficients and packs them in a binary file targeting the Coaxlink cards.

The purpose of this sample code is threefold:

□ guide the user through the calibration procedure;
□ provide a technical and practical translation of what's described in this document;
□ provide building blocks for developing custom applications.

The source code lies in a single source file: src/ffc-wizard.cpp. Building the application should be straightforward;

□ for Windows, there is a Microsoft Visual Studio project file ffc-wizard.vcproj;
□ for Linux and macOS, a Makefile is provided.

The wizard is a console application. The help message is displayed when the flag -h (or --help) is given:

getting the help message

> ffc-wizard.exe --help
Flat Field Correction Wizard
fcc-wizard [OPTIONS]

Options:
  --if=INT                 Index of GenTL interface to use
  --dev=INT                Index of GenTL device to use
  --ds=INT                 Index of GenTL data stream to use
  --average=INT            Number of images to average (default: 10)
  --roi_x=INT              Horizontal offset in pixels of ROI upper-left corner (default: 0)
  --roi_y=INT              Vertical offset in pixels of ROI upper-left corner (default: 0; ignored for line-scan)
  --roi_width=INT          Width of ROI (default: whole image)
  --roi_height=INT         Height of ROI (default: whole image; ignored for line-scan)
  --balance                Compute flat image average on all components rather than on each component
  --linescan               Force line-scan mode i.e. average image lines (automatically enabled for line-scan cards)
  --dark-setup=SCRIPT      Path to setup script for dark acquisitions
  --flat-setup=SCRIPT      Path to setup script for flat acquisitions
  --timeout=MS             Maximum time in milliseconds to wait for an image (default: 1000)
  --dark-histogram=FILE    Path to histogram html page of average dark image to output and open
  --flat-histogram=FILE    Path to histogram html page of average flat image to output and open
  --output-ffc=FILE        Path to coefficients output file (Coaxlink ffc binary format)
  --load-ffc=FILE          Load coefficients into Coaxlink coefficients partition (default: computed coefficients)
  --no-interact            Skip user interaction
  -h  --help               Display help message

Note: the ROI options allow defining a rectangular region to consider while computing averages,
      this is useful to eliminate pixels close to borders in images subject to vignetting.

Options details

Flags Details
--if, --def, --ds the indexes of the GenTL modules that identify the data stream to use (and/or to configure)
--average the number of images to acquire for dark and flat acquisitions; only the average of those acquisitions is further used in the calibration procedure
--roi_x, --roi_y, --roi_width, --roi_height an optional rectangular region to consider when computing the average pixel value of the flat image (average(Flat)); this impacts the evaluation of the gain value for each pixel
--balance enables the white balance; i.e. whether the coefficients of color pixel components are computed to balance the component values or not; obviously, this requires the flat background used to acquire the flat image(s) to be as close as possible to a true gray (for which all RGB components would have identical values)
--dark-setup, --flat-setup optional configuration scripts to run before dark and flat acquisitions
--dark-histogram, --flat-histogram optional; path to output file showing the histogram of dark and flat image pixel components; this gives a visual overview of the dark current variations as well as the variations in the flat image
--no-interact normally the wizard waits for the user to setup the system before starting the dark and flat acquisitions; when this flag is used, the wizard does not wait for the user (nor does it open the created histogram html pages)

Here is an illustrated example that generates FFC coefficients (written to the file coefficients.ffc) using the white balance functionality. The command to run from a console window is the following:

The program starts and tells you what to do:

You can prepare your setup for the dark acquisitions and press Enter when you are ready. It will then acquire the series of dark images and display the instructions for the next step

You can prepare your setup for the flat acquisitions and press Enter when you are ready. It will then acquire the series of flat images, compute the corresponding coefficients and write them to the file coefficients.ffc

Later on you can load the coefficients from the genicam-browser for example, by running the load-ffc script as follows:

Then you can select the previously created file coefficients.ffc

From that moment, the coefficients are loaded into the Coaxlink memory and the FFC processing is enabled.

The calibration procedure as well as the packing of the coefficients is controlled by the main function ffcWizard.

ffcWizard tasks

Task Done by function
acquiring a series of dark images to build an average dark image acquireImages
acquiring a series of flat images to build an average flat image acquireImages
computing the gain values for each pixel component computeGain
using the dark pixel component values as offset values computeOffset
packing offset and gain values into 16-bit little-endian values packCoefficients
writing the packed coefficients into a binary file savePackedCoefficients

The sample application already supports a few common pixel formats: Mono, RGB, RGBa and Bayer.

Limitation: to limit the complexity of the sample application, we consider (for pixel formats with several components per pixel) that all components have the same size. Supporting pixel formats with different component sizes is still possible by updating the functions addImage and addComponents.

To support a new pixel format (under the condition of the previous limitation), we need to modify two functions:

1. Image::getComponentsPerPixel, to return the number of components per pixel for the new format identified by its PFNC name
2. Image::getComponentFilters, to return a std::vector of ComponentFilter objects describing how the pixel components of the new format (identified by its PFNC name) are positioned in the image

The ComponentFilter objects are used to separate the processing of the different pixel components while evaluating the Gain and Offset values. For example, in RGB format, the FFC coefficients related to the Red components are computed using the Red components from the dark and flat images.

Please see the source code of Image::getComponentFilters for details about pixel component layout configuration.