Detailed Description

Functions for setting common camera parameters.

Note: Some camera parameters may be taken into acount with a delay of one frame.

Normalized parameter values

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

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 value after initialization also depends on the hardware. For example, unity gain can correspond to a value of 256 or 512 for different sensor types.

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. More...

UINT32 DLL_FG_API	FG_get_black (UINT32 *black)
	Returns the normalized black level. More...

UINT32 DLL_FG_API	FG_get_gain (UINT32 *gain)
	Returns the normalized gain value. More...

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. More...

UINT32 DLL_FG_API	FG_get_image_size (UINT32 width, UINT32 height, UINT32 *bytes)
	Returns the size of the image buffers. More...

UINT32 DLL_FG_API	FG_get_pixel_order (enum eFG_PIXEL_ORDER *pixel_order)
	Returns the order of pixel components within image buffers. More...

UINT32 DLL_FG_API	FG_get_scan_param (UINT32 scan_x, UINT32 scan_y, UINT32 scan_width, UINT32 scan_height, UINT32 image_height, enum eFG_PIXEL_TYPE pixel_type)
	Returns the area of interest and the output format. More...

UINT32 DLL_FG_API	FG_get_shutter_time (UINT32 *shutter_time_us)
	Returns the exposure time in µs. More...

UINT32 DLL_FG_API	FG_get_trigger_mode (enum eFG_TRIGGER_MODE *trigger_mode)
	Returns the configured trigger mode. More...

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. More...

UINT32 DLL_FG_API	FG_set_black (UINT32 black)
	Sets the black level using a normalized value. More...

UINT32 DLL_FG_API	FG_set_gain (UINT32 gain)
	Sets the gain using a normalized value. More...

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. More...

UINT32 DLL_FG_API	FG_set_scan_param (UINT32 scan_x, UINT32 scan_y, UINT32 scan_width, UINT32 scan_height, UINT32 image_height, enum eFG_PIXEL_TYPE pixel_type)
	Sets the area of interest and output format. More...

UINT32 DLL_FG_API	FG_set_shutter_time (UINT32 shutter_time_us)
	Sets the exposure time in µs. More...

UINT32 DLL_FG_API	FG_set_trigger_mode (enum eFG_TRIGGER_MODE trigger_mode)
	Sets the trigger mode. More...

Function Documentation

◆ FG_get_aoi()

UINT32 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 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 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 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 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 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	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 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 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 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 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 Dragster line scan sensors.

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 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 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 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.

Please avoid using smaller values than unity gain, because this leads to different saturation values for each color copmonent (less than 255 for 8-bit format).

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_scan_param()

UINT32 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 mode can be enabled by setting image_scan_count > 1. The acquired lines from multiple frames of the selected sensor region will be concatenated into the larger destination image. Line scan mode is available for the EV2S02M / EV2S05M and the Lince5M181 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 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 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 VisionCam XM and VisionSensor PV 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)