Detailed Description

Functions for setting common camera parameters.

Note: Some camera parameters may be taken into acount with a delay of one frame, depending on the sensor type.

Normalized parameter values

Functions for setting gain and black level use normalized arguments. The valid range is always 0...1023:

FG_set_gain() / FG_get_gain()
FG_set_gain_rgb() / FG_get_gain_rgb()
FG_set_black() / FG_get_black()

Each function scales the provided values from 0...1023 into a valid target range for the hardware. If there are less allowed steps in the target range, the library will configure the closest setting. Read the value back the get the actually configured value.

The default settings after initialization are unity gain and zero black offset. The normalized value depends on the sensor type. For example, unity gain can correspond to a value of 0, 256 or 512, depending on the supported target range for the hardware.

Exposure time

The functions FG_set_shutter_time() and FG_get_shutter_time() are used for setting and reading the exposure time.

If the value is out of range, FG_set_shutter_time() returns with an error. But the function will still set the closest value possible. This can be used to obtain the sensor limits, for example:

UINT32 exposure_min = 1;
UINT32 exposure_max = 1000000;
 
FG_set_shutter_time(exposure_min);        // ignore function result while setting lowest value
FG_get_shutter_time(&exposure_min);       // read the actual value
 
FG_set_shutter_time(exposure_max);        // ignore function result while setting highest value
FG_get_shutter_time(&exposure_max);       // read the actual value
 
printf("Exposure range: %u ... %u us\n", exposure_min, exposure_max);

Note: The exposure limits may depend on other settings like the AOI size, binning mode and trigger mode.

Default settings

All parameters are initialized to default values when calling FG_install_camera().

The area of interest is configured to the full sensor size, or the closest possible value if the acquisition interface has further restrictions.

The initial exposure time can vary depending on the sensor type.

Loading default settings from a JSON file

The default settings can be altered by using a JSON file. The function FG_install_camera() loads values from the file fg.json if present in the current / working directory. Alternatively, the environment variable FG_CAMERA_JSON can be set to specify a different location and name for the JSON file.

The JSON file contains an array named "Settings". Each array element consists of an object containing a set of configuration values for a specific camera type. The actual type of used camera is compared against the name-value pairs named "camera_type" for each set of configuration values (eFG_CAMERA_TYPE). The first matching set will be applied.

The following example contains configuration values for two camera types:

{
  "Settings":
  [
    {
      "Name": "EV76C560C",
      "camera_type": 5,
      "trigger_mode": 2,
      "gain_rgb": [512, 573, 683]
    },
    {
      "Name": "IMX568M",
      "camera_type": 44,
      "scan_param": [256, 480, 1920, 1080, 1, 0],
      "shutter_time": 3000,
      "gain": 200,
      "special_option":
      [
        {
          "option": "Mirror",
          "value": 3
        },
        {
          "option": "Compression",
          "value": 1
        }
      ]
    }
  ]
}

The name-value pair "Name" in the example is only used as comment for better readability.

The first configuration for the EV76C560C sensor changes the trigger mode to FG_TRIGGER_MODE_FREERUN (2) and configures the RGB gain.

The second configuration for the IMX568M sensor changes the AOI, exposure time and gain, and also configures two special options.

The following configuration values are currently supported:

Name	Data type	Associated function
scan_param	Array of six numbers	FG_set_scan_param()
shutter_time	Number	FG_set_shutter_time()
gain	Number	FG_set_gain()
black	Number	FG_set_black()
gain_rgb	Array of three numbers	FG_set_gain_rgb()
trigger_mode	Number	FG_set_trigger_mode()
special_option	Array of objects, each containing two name-value pairs as described below	FG_set_special_option()
special_option[].option	String containing the name of the special option
special_option[].value	Number containing the value for the special option

Note

Settings which are not specified in the configuration set will stay at their default.
Unknown name-value pairs are ignored.
Some settings require support by the hardware. For example, "gain_rgb" is not available for monochrome sensors.
FG_install_camera() fails if:
- known but unsupported settings are used
- values are out of range (except for shutter_time: the closest value possible is used)
- the JSON file contains syntax errors
- the environment variable FG_CAMERA_JSON is set, but the JSON file is not found
No error occurs if the configuration set for the camera type is not found in the JSON file (no matching camera_type value).

Functions
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 the output format.
UINT32 DLL_FG_API	FG_get_black (UINT32 *black)
	Returns the normalized black level.
UINT32 DLL_FG_API	FG_get_gain (UINT32 *gain)
	Returns the normalized gain value.
UINT32 DLL_FG_API	FG_get_gain_rgb (UINT32 gain_red, UINT32 gain_green, UINT32 *gain_blue)
	Returns the normalized color gain values for supported hardware.
UINT32 DLL_FG_API	FG_get_image_size (UINT32 width, UINT32 height, UINT32 *bytes)
	Returns the size of the image buffers.
UINT32 DLL_FG_API	FG_get_pixel_order (enum eFG_PIXEL_ORDER *pixel_order)
	Returns the order of pixel components within image buffers.
UINT32 DLL_FG_API	FG_get_scan_param (UINT32 scan_x, UINT32 scan_y, UINT32 scan_width, UINT32 scan_height, UINT32 image_scan_count, enum eFG_PIXEL_TYPE pixel_type)
	Returns the area of interest and the output format.
UINT32 DLL_FG_API	FG_get_shutter_time (UINT32 *shutter_time_us)
	Returns the exposure time in µs.
UINT32 DLL_FG_API	FG_get_trigger_mode (enum eFG_TRIGGER_MODE *trigger_mode)
	Returns the configured trigger mode.
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 the output format.
UINT32 DLL_FG_API	FG_set_black (UINT32 black)
	Sets the black level using a normalized value.
UINT32 DLL_FG_API	FG_set_gain (UINT32 gain)
	Sets the gain using a normalized value.
UINT32 DLL_FG_API	FG_set_gain_rgb (UINT32 gain_red, UINT32 gain_green, UINT32 gain_blue)
	Sets the color component gain values for supported hardware.
UINT32 DLL_FG_API	FG_set_pixel_order (enum eFG_PIXEL_ORDER pixel_order)
	Sets the order of pixel components within image buffers.
UINT32 DLL_FG_API	FG_set_scan_param (UINT32 scan_x, UINT32 scan_y, UINT32 scan_width, UINT32 scan_height, UINT32 image_scan_count, enum eFG_PIXEL_TYPE pixel_type)
	Sets the area of interest and output format.
UINT32 DLL_FG_API	FG_set_shutter_time (UINT32 shutter_time_us)
	Sets the exposure time in µs.
UINT32 DLL_FG_API	FG_set_trigger_mode (enum eFG_TRIGGER_MODE trigger_mode)
	Sets the trigger mode.

Function Documentation

◆ 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 the output format.

Parameters

x1	Pointer for storing the first column
y1	Pointer for storing the first row
x2	Pointer for storing the last column
y2	Pointer for storing the last row
pixel_type	Pointer for storing the pixel format

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

◆ FG_get_black()

UINT32 DLL_FG_API FG_get_black ( UINT32 * black )

Returns the normalized black level.

Parameters

black Pointer for storing the black level value (0...1023)

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

◆ FG_get_gain()

UINT32 DLL_FG_API FG_get_gain ( UINT32 * gain )

Returns the normalized gain value.

Parameters

gain	Pointer for storing the gain value (0...1023)

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

◆ FG_get_gain_rgb()

UINT32 DLL_FG_API FG_get_gain_rgb	(	UINT32 *	gain_red,
		UINT32 *	gain_green,
		UINT32 *	gain_blue )

Returns the normalized color gain values for supported hardware.

Parameters

gain_red	Pointer for storing the red gain value (0...1023)
gain_green	Pointer for storing the green gain value (0...1023)
gain_blue	Pointer for storing the blue gain value (0...1023)

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

◆ FG_get_image_size()

UINT32 DLL_FG_API FG_get_image_size	(	UINT32 *	width,
		UINT32 *	height,
		UINT32 *	bytes )

Returns the size of the image buffers.

NULL-pointer arguments will be ignored.

Parameters

width	Pointer for storing image width in pixels
height	Pointer for storing image height in pixels
bytes	Pointer for storing image size in bytes

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

◆ FG_get_pixel_order()

UINT32 DLL_FG_API FG_get_pixel_order ( enum eFG_PIXEL_ORDER * pixel_order )

Returns the order of pixel components within image buffers.

This function is mainly used to obtain the order of color components when using the bayer format. It can also be used to differentiate between monochrome and color sensors, because both can use the same pixel type FG_PIXEL_TYPE_Y_8 / FG_PIXEL_TYPE_Y_16.

The following table show possible combinations. Please check the corresponding sensor page for actually supported pixel types.

Sensor type	Pixel type eFG_PIXEL_TYPE	Pixel order eFG_PIXEL_ORDER	Description
Monochrome	FG_PIXEL_TYPE_Y_8, FG_PIXEL_TYPE_Y_16	FG_PIXEL_ORDER_Y	Luminosity for each pixel
Color	FG_PIXEL_TYPE_Y_8, FG_PIXEL_TYPE_Y_16	FG_PIXEL_ORDER_RG, FG_PIXEL_ORDER_BG, FG_PIXEL_ORDER_GR, FG_PIXEL_ORDER_GB	Raw Bayer values with the given order of color components
Color	FG_PIXEL_TYPE_RGB_24, FG_PIXEL_TYPE_RGBX_32	FG_PIXEL_ORDER_RGB, FG_PIXEL_ORDER_BGR	RGB components are present for each pixel

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

◆ FG_get_scan_param()

UINT32 DLL_FG_API FG_get_scan_param	(	UINT32 *	scan_x,
		UINT32 *	scan_y,
		UINT32 *	scan_width,
		UINT32 *	scan_height,
		UINT32 *	image_scan_count,
		enum eFG_PIXEL_TYPE *	pixel_type )

Returns the area of interest and the output format.

This function can be used as an alternative to FG_get_aoi().

NULL-pointer arguments will be ignored.

Parameters

scan_x	Pointer for storing the sensor AOI starting column
scan_y	Pointer for storing the sensor AOI starting row
scan_width	Pointer for storing the sensor AOI width
scan_height	Pointer for storing the sensor AOI height
image_scan_count	Pointer for storing the number of sensor scans for one image
pixel_type	Pointer for storing the pixel format

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

◆ FG_get_shutter_time()

UINT32 DLL_FG_API FG_get_shutter_time ( UINT32 * shutter_time_us )

Returns the exposure time in µs.

Parameters

shutter_time_us Pointer for storing the exposure time value

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

◆ FG_get_trigger_mode()

UINT32 DLL_FG_API FG_get_trigger_mode ( enum eFG_TRIGGER_MODE * trigger_mode )

Returns the configured trigger mode.

Parameters

trigger_mode Pointer for storing the trigger mode value

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

◆ 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 the output format.

If the full sensor resolution is not needed, it is possible to specify a smaller region for image acquisition. Depending on the sensor and pixel format, the maximum frame rate can be increased.

Depending on the hardware, some image preprocessing like demosaicing of RGB bayer pattern gets activated depending on the pixel type.
See description for supported pixel formats for the different sensors:

Note: The size and format can't be changed after allocating the first image buffer (FG_alloc_image()). Some sensors allow moving the AOI position wihtout changing the size. Uninstall the camera or use FG_stop_image() and release all buffers before changing the size.

Also see note about the image size for line scan sensors Dragster and GL7004.

Parameters

x1	first column [0 ... max width-2]
y1	first row [0 ... max height-1]
x2	last column [x1+1 ... max width-1]
y2	last row [y1+1 ... max height-1]
pixel_type	Pixel format

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

◆ FG_set_black()

UINT32 DLL_FG_API FG_set_black ( UINT32 black )

Sets the black level using a normalized value.

Use FG_get_black() after initialization to obtain the default value.

Parameters

black Black level value, 0...1023

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

◆ FG_set_gain()

UINT32 DLL_FG_API FG_set_gain ( UINT32 gain )

Sets the gain using a normalized value.

The default value is set to unity gain after initialization. Use FG_get_gain() after initialization to obtain the default value.

Using smaller values than unity gain can lead to lower saturation values (e.g. less than 255 for 8-bit format).

Parameters

gain	Gain value, 0...1023

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

◆ FG_set_gain_rgb()

UINT32 DLL_FG_API FG_set_gain_rgb	(	UINT32	gain_red,
		UINT32	gain_green,
		UINT32	gain_blue )

Sets the color component gain values for supported hardware.

The default value is set to unity gain after initialization. Use FG_get_gain_rgb() after initialization to obtain the default value.

Note

Support for RGB-gain depends on the sensor type.
Lower gain values than the default setting (unity gain) may lead to different saturation values for each color copmonent (e.g. less than 255 for 8-bit format). Only use higher values to avoid this situation.

Parameters

gain_red	Red gain, 0...1023
gain_green	Green gain, 0...1023
gain_blue	Blue gain, 0...1023

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

◆ FG_set_pixel_order()

UINT32 DLL_FG_API FG_set_pixel_order ( enum eFG_PIXEL_ORDER pixel_order )

Sets the order of pixel components within image buffers.

It can only be used to change the order of RGB components for pixel type FG_PIXEL_TYPE_RGB_24 on supported hardware.

Parameters

pixel_order Pixel order: FG_PIXEL_ORDER_RGB or FG_PIXEL_ORDER_BGR

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

◆ FG_set_scan_param()

UINT32 DLL_FG_API FG_set_scan_param	(	UINT32	scan_x,
		UINT32	scan_y,
		UINT32	scan_width,
		UINT32	scan_height,
		UINT32	image_scan_count,
		enum eFG_PIXEL_TYPE	pixel_type )

Sets the area of interest and output format.

This function can be used as an alternative to FG_set_aoi().

The sensor AOI is selected by using the scan_* parameters. For normal frame acquisition, the image_scan_count parameter is 1.

Line scan / multi-scan mode can be enabled by setting image_scan_count > 1. Multiple frames of the selected sensor region will be concatenated into the larger destination image. This mode is available for the VisionSensor PV3, the Lince5M181 sensor and for line scan cameras / sensors.

Parameters

scan_x	Sensor AOI starting column
scan_y	Sensor AOI starting row
scan_width	Sensor AOI width
scan_height	Sensor AOI height
image_scan_count	Number of sensor scans to complete one image
pixel_type	Pixel format

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

◆ FG_set_shutter_time()

UINT32 DLL_FG_API FG_set_shutter_time ( UINT32 shutter_time_us )

Sets the exposure time in µs.

The usable range depends on the sensor type. If the value is out of range, the function returns with an error, but it still configures to closes possible value. Use FG_get_shutter_time() to obtain the configured value.

Parameters

shutter_time_us Exposure time in µs

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)

◆ FG_set_trigger_mode()

UINT32 DLL_FG_API FG_set_trigger_mode ( enum eFG_TRIGGER_MODE trigger_mode )

Sets the trigger mode.

The following trigger modes can be used:

Software (FG_TRIGGER_MODE_SOFTWARE)
The function FG_trigger_image() must be used to trigger each image. This is the default setting for area scan cameras. It can't be used with line scan cameras.
Hardware (FG_TRIGGER_MODE_HARDWARE)
The camera waits for a trigger event. See also page Hardware platforms on how to use the hardware trigger.
Free-run (FG_TRIGGER_MODE_FREERUN)
The camera continuously delivers images as fast as possible. This is the default setting for line scan cameras.

Parameters

trigger_mode Trigger mode

Returns: FG_ERROR_CODE_NoError (0) for success, other values indicate an error (see eFG_ERROR_CODE)