Device calibration parameter definitions and API functions. More...

Collaboration diagram for Calibration:

Data Structures
union	argus_cal_offset_table_t
	Pixel Range Offset Table. More...

struct	xtalk_t
	Pixel Crosstalk Compensation Vector. More...

union	argus_cal_xtalk_table_t
	Pixel Crosstalk Vector Table. More...

struct	argus_cal_electrical_p2pxtalk_t
	Electrical Pixel-To-Pixel Crosstalk Compensation Parameters. More...

struct	argus_cal_optical_p2pxtalk_t
	Optical Pixel-To-Pixel Crosstalk Compensation Parameters. More...

struct	argus_cal_p2pxtalk_t
	Pixel-To-Pixel Crosstalk Compensation Parameters. More...

Functions
status_t	Argus_SetCalibrationGlobalRangeOffsets (argus_hnd_t *hnd, q0_15_t offset_low, q0_15_t offset_high)
	Sets the global range offset values to a specified device.

status_t	Argus_GetCalibrationGlobalRangeOffsets (argus_hnd_t hnd, q0_15_t offset_low, q0_15_t *offset_high)
	Gets the global range offset values from a specified device.

status_t	Argus_SetCalibrationPixelRangeOffsets (argus_hnd_t hnd, argus_cal_offset_table_t const value)
	Sets the relative pixel offset table to a specified device.

status_t	Argus_GetCalibrationPixelRangeOffsets (argus_hnd_t hnd, argus_cal_offset_table_t value)
	Gets the relative pixel offset table from a specified device.

status_t	Argus_ResetCalibrationPixelRangeOffsets (argus_hnd_t *hnd)
	Resets the relative pixel offset values for the specified device to the factory calibrated default values.

void	Argus_GetPixelRangeOffsets_Callback (argus_cal_offset_table_t *offsets, argus_mode_t const mode)
	A callback that returns the external pixel range offsets.

status_t	Argus_SetCalibrationRangeOffsetSequenceSampleTime (argus_hnd_t *hnd, uint16_t value)
	Sets the sample time for the range offset calibration sequence.

status_t	Argus_GetCalibrationRangeOffsetSequenceSampleTime (argus_hnd_t hnd, uint16_t value)
	Gets the sample time for the range offset calibration sequence.

status_t	Argus_SetCalibrationCrosstalkPixel2Pixel (argus_hnd_t hnd, argus_cal_p2pxtalk_t const value)
	Sets the pixel-to-pixel crosstalk compensation parameters to a specified device.

status_t	Argus_GetCalibrationCrosstalkPixel2Pixel (argus_hnd_t hnd, argus_cal_p2pxtalk_t value)
	Gets the pixel-to-pixel crosstalk compensation parameters from a specified device.

status_t	Argus_SetCalibrationCrosstalkVectorTable (argus_hnd_t hnd, argus_cal_xtalk_table_t const value)
	Sets the custom crosstalk vector table to a specified device.

status_t	Argus_GetCalibrationCrosstalkVectorTable (argus_hnd_t hnd, argus_cal_xtalk_table_t value)
	Gets the custom crosstalk vector table from a specified device.

status_t	Argus_ResetCalibrationCrosstalkVectorTable (argus_hnd_t *hnd)
	Resets the crosstalk vector table for the specified device to the factory calibrated default values.

status_t	Argus_SetCalibrationCrosstalkSequenceSampleTime (argus_hnd_t *hnd, uint16_t value)
	Sets the sample time for the crosstalk calibration sequence.

status_t	Argus_GetCalibrationCrosstalkSequenceSampleTime (argus_hnd_t hnd, uint16_t value)
	Gets the sample time for the crosstalk calibration sequence.

status_t	Argus_SetCalibrationCrosstalkSequenceAmplitudeThreshold (argus_hnd_t *hnd, uq12_4_t value)
	Sets the max. amplitude threshold for the crosstalk calibration sequence.

status_t	Argus_GetCalibrationCrosstalkSequenceAmplitudeThreshold (argus_hnd_t hnd, uq12_4_t value)
	Gets the max. amplitude threshold for the crosstalk calibration sequence.

status_t	Argus_ClearUserCalibration (argus_hnd_t *hnd)
	Clears all user calibration values from NVM for the specified device.

void	Argus_GetCrosstalkVectorTable_Callback (argus_cal_xtalk_table_t *xtalk, argus_mode_t const mode)
	A callback that returns the external crosstalk vector table.

status_t	Argus_GetCalibrationGoldenPixel (argus_hnd_t const hnd, uint8_t x, uint8_t *y)
	Gets the currently calibrated Golden Pixel coordinates.

Detailed Description

Device calibration parameter definitions and API functions.

The calibration concept of the Time-of-Flight measurement device is made up of three parts:

Factory calibration data which is provided in the devices EEPROM. This data is read and applied upon device initialization.
Online calibration is executed along with the actual distance measurements. Therefore, ambient information, e.g. temperature or voltage levels, are gathered during measurements. The information is then utilized to adjust the device configuration and evaluation algorithms accordingly.
User calibration parameters are applied on top of this. These parameters are provided in order to adopt the device to the user application, e.g. cover glass calibration. These parameters must be set (if required) by the given API.

Calibration API

Function Documentation

◆ Argus_ClearUserCalibration()

status_t Argus_ClearUserCalibration ( argus_hnd_t * hnd )

Clears all user calibration values from NVM for the specified device.

The user calibration values are stored in the non-volatile memory (NVM) if corresponding NVM hardware layer is implemented. This method clears the user calibration data from the non-volatile memory.

Warning: This does not reset the currently set calibration values to factory defaults!

Parameters

hnd	The API handle; contains all internal states and data.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_GetCalibrationCrosstalkPixel2Pixel()

status_t Argus_GetCalibrationCrosstalkPixel2Pixel	(	argus_hnd_t *	hnd,
		argus_cal_p2pxtalk_t *	value
	)

Gets the pixel-to-pixel crosstalk compensation parameters from a specified device.

Parameters

hnd	The API handle; contains all internal states and data.
value	The current pixel-to-pixel crosstalk compensation parameters.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_GetCalibrationCrosstalkSequenceAmplitudeThreshold()

status_t Argus_GetCalibrationCrosstalkSequenceAmplitudeThreshold	(	argus_hnd_t *	hnd,
		uq12_4_t *	value
	)

Gets the max. amplitude threshold for the crosstalk calibration sequence.

The maximum amplitude threshold defines a maximum crosstalk vector amplitude before causing an error message. If the crosstalk is too high, there is usually an issue with the measurement setup, i.e. there is still a measurement signal detected.

Parameters

hnd	The API handle; contains all internal states and data.
value	The current max. amplitude threshold value in UQ12.4 format.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_GetCalibrationCrosstalkSequenceSampleTime()

status_t Argus_GetCalibrationCrosstalkSequenceSampleTime	(	argus_hnd_t *	hnd,
		uint16_t *	value
	)

Gets the sample time for the crosstalk calibration sequence.

Gets the measurement sample acquisition time for executing the crosstalk calibration sequence and generate the crosstalk data.
Units: msec.

Parameters

hnd	The API handle; contains all internal states and data.
value	The current crosstalk calibration sequence sample time.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_GetCalibrationCrosstalkVectorTable()

status_t Argus_GetCalibrationCrosstalkVectorTable	(	argus_hnd_t *	hnd,
		argus_cal_xtalk_table_t *	value
	)

Gets the custom crosstalk vector table from a specified device.

The crosstalk vectors are subtracted from the raw sampling data in the data evaluation phase.

The crosstalk vector table is a three dimensional array of type xtalk_t. The argus_cal_xtalk_table_t is the corresponding typedef for the required data.

The dimensions are:

size(0) = ARGUS_DFM_FRAME_COUNT (Dual-frequency mode A- or B-frame)
size(1) = ARGUS_PIXELS_X (Pixel count in x-direction)
size(2) = ARGUS_PIXELS_Y (Pixel count in y-direction)

Parameters

hnd	The API handle; contains all internal states and data.
value	The current crosstalk vector table.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_GetCalibrationGlobalRangeOffsets()

status_t Argus_GetCalibrationGlobalRangeOffsets	(	argus_hnd_t *	hnd,
		q0_15_t *	offset_low,
		q0_15_t *	offset_high
	)

Gets the global range offset values from a specified device.

The global range offsets are subtracted from the raw range values. There are two distinct values that are applied in low or high power stage setting respectively.

Parameters

hnd	The API handle; contains all internal states and data.
offset_low	The current range offset for the low power stage in meter and Q0.15 format.
offset_high	The current global range offset for the high power stage in meter and Q0.15 format.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_GetCalibrationGoldenPixel()

status_t Argus_GetCalibrationGoldenPixel	(	argus_hnd_t const *	hnd,
		uint8_t *	x,
		uint8_t *	y
	)

Gets the currently calibrated Golden Pixel coordinates.

The Golden Pixel is the pixel that is located at the center of the receiving light beam. Thus it it the one that receives the most signal and plays a central role in 1D measurement systems.

The function fills the provided x and y parameters with the Golden Pixel coordinates. Typical values are x = 5 and y = 1 or 2. But the actual values depend on the specific sensor.

Please also note the utility functions provided in the Pixel Channel Mapping module to convert between pixel coordinates and channel numbers or shift pixel maps by a position offset (ShiftSelectedPixels) or generate pixel masks centered around the Golden Pixel (FillPixelMask).

Parameters

hnd	The API handle; contains all internal states and data.
x	The Golden Pixel x-coordinate.
y	The Golden Pixel y-coordinate.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_GetCalibrationPixelRangeOffsets()

status_t Argus_GetCalibrationPixelRangeOffsets	(	argus_hnd_t *	hnd,
		argus_cal_offset_table_t *	value
	)

Gets the relative pixel offset table from a specified device.

The relative pixel offset values are subtracted from the raw range values for each individual pixel. Note that a global range offset is applied additionally. The relative pixel offset values are meant to be with respect to the average range of all pixels, i.e. the average of all relative offsets should be 0!

The crosstalk vector table is a two dimensional array of type q0_15_t, wrapped within the argus_cal_offset_table_t structure.

The dimensions are:

size(0) = ARGUS_PIXELS_X (Pixel count in x-direction)
size(1) = ARGUS_PIXELS_Y (Pixel count in y-direction)

Parameters

hnd	The API handle; contains all internal states and data.
value	The current relative range offset in meter and Q0.15 format.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_GetCalibrationRangeOffsetSequenceSampleTime()

status_t Argus_GetCalibrationRangeOffsetSequenceSampleTime	(	argus_hnd_t *	hnd,
		uint16_t *	value
	)

Gets the sample time for the range offset calibration sequence.

Gets the measurement sample acquisition time for executing the range offset calibration sequence and generate the offset data.
Units: msec.

Parameters

hnd	The API handle; contains all internal states and data.
value	The current range offset calibration sequence sample time.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_GetCrosstalkVectorTable_Callback()

void Argus_GetCrosstalkVectorTable_Callback	(	argus_cal_xtalk_table_t *	xtalk,
		argus_mode_t const	mode
	)

A callback that returns the external crosstalk vector table.

The function needs to be implemented by the host application in order to set the external crosstalk vector table upon system initialization. If not defined in user code, the default implementation will return an all zero vector table, assuming there is no (additional) external crosstalk.

If defined in user code, the function must fill all vector values in the provided

crosstalk parameter with external crosstalk: values. The values can be obtained by the calibration routine.

Example usage:

status_t Argus_GetCrosstalkVectorTable_Callback(
                argus_cal_xtalk_table_t * xtalk)
{
    memset(xtalk, 0, sizeof(argus_cal_xtalk_table_t));
 
    // Set crosstalk vectors in Q11.4 format.
    // Note on dual-frequency frame index: 0 = A-Frame; 1 = B-Frame
    xtalk.FrameA[0][0].dS = -9;     xtalk.FrameB[0][0].dC = -11;
    xtalk.FrameA[0][1].dS = -13;    xtalk.FrameB[0][1].dC = -16;
    xtalk.FrameA[0][2].dS = 6;      xtalk.FrameB[0][2].dC = -18;
    // etc.
}

Parameters

xtalk	The crosstalk vector array; to be filled with data.
mode	The current measurement mode.

◆ Argus_GetPixelRangeOffsets_Callback()

void Argus_GetPixelRangeOffsets_Callback	(	argus_cal_offset_table_t *	offsets,
		argus_mode_t const	mode
	)

A callback that returns the external pixel range offsets.

The function needs to be implemented by the host application in order to set the external pixel range offsets values upon system initialization. If not defined in user code, the default implementation will return an all zero offset table, assuming there is no (additional) external pixel range offset values.

If defined in user code, the function must fill all offset values in the provided

offsets parameter with external range offset: values. The values can be obtained by the calibration routine.

Example usage:

status_t Argus_GetPixelRangeOffsets_Callback(argus_cal_offset_table_t offsets)
{
    memset(offsets, 0, sizeof(argus_cal_offset_t));
 
    // Set offset values in meter and Q0.15 format.
    offsets.Table[0][0] = -3542;
    offsets.Table[0][1] = -4385;
    offsets.Table[0][2] = 2953;
    // etc.
}

Parameters

offsets	The pixel range offsets in meter and Q0.15 format; to be filled with data.
mode	The current measurement mode.

◆ Argus_ResetCalibrationCrosstalkVectorTable()

status_t Argus_ResetCalibrationCrosstalkVectorTable ( argus_hnd_t * hnd )

Resets the crosstalk vector table for the specified device to the factory calibrated default values.

The crosstalk vectors are subtracted from the raw sampling data in the data evaluation phase.

The factory defaults are device specific calibrated values.

Parameters

hnd	The API handle; contains all internal states and data.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_ResetCalibrationPixelRangeOffsets()

status_t Argus_ResetCalibrationPixelRangeOffsets ( argus_hnd_t * hnd )

Resets the relative pixel offset values for the specified device to the factory calibrated default values.

The relative pixel offset values are subtracted from the raw range values for each individual pixel. Note that a global range offset is applied additionally.

The factory defaults are device specific values.

Parameters

hnd	The API handle; contains all internal states and data.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_SetCalibrationCrosstalkPixel2Pixel()

status_t Argus_SetCalibrationCrosstalkPixel2Pixel	(	argus_hnd_t *	hnd,
		argus_cal_p2pxtalk_t const *	value
	)

Sets the pixel-to-pixel crosstalk compensation parameters to a specified device.

Parameters

hnd	The API handle; contains all internal states and data.
value	The new pixel-to-pixel crosstalk compensation parameters.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_SetCalibrationCrosstalkSequenceAmplitudeThreshold()

status_t Argus_SetCalibrationCrosstalkSequenceAmplitudeThreshold	(	argus_hnd_t *	hnd,
		uq12_4_t	value
	)

Sets the max. amplitude threshold for the crosstalk calibration sequence.

The maximum amplitude threshold defines a maximum crosstalk vector amplitude before causing an error message. If the crosstalk is too high, there is usually an issue with the measurement setup, i.e. there is still a measurement signal detected.

Parameters

hnd	The API handle; contains all internal states and data.
value	The new crosstalk calibration sequence maximum amplitude threshold value in UQ12.4 format.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_SetCalibrationCrosstalkSequenceSampleTime()

status_t Argus_SetCalibrationCrosstalkSequenceSampleTime	(	argus_hnd_t *	hnd,
		uint16_t	value
	)

Sets the sample time for the crosstalk calibration sequence.

Sets the measurement sample acquisition time for executing the crosstalk calibration sequence and generate the crosstalk data.
Units: msec.

Parameters

hnd	The API handle; contains all internal states and data.
value	The new crosstalk calibration sequence sample time.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_SetCalibrationCrosstalkVectorTable()

status_t Argus_SetCalibrationCrosstalkVectorTable	(	argus_hnd_t *	hnd,
		argus_cal_xtalk_table_t const *	value
	)

Sets the custom crosstalk vector table to a specified device.

The crosstalk vectors are subtracted from the raw sampling data in the data evaluation phase.

The crosstalk vector table is a three dimensional array of type xtalk_t. The argus_cal_xtalk_table_t is the corresponding typedef for the required data.

The dimensions are:

size(0) = ARGUS_DFM_FRAME_COUNT (Dual-frequency mode A- or B-frame)
size(1) = ARGUS_PIXELS_X (Pixel count in x-direction)
size(2) = ARGUS_PIXELS_Y (Pixel count in y-direction)

Its recommended to use the built-in crosstalk calibration sequence (see Argus_ExecuteXtalkCalibrationSequence) to determine the crosstalk vector table.

If a constant table for all device needs to be incorporated into the sources, the Argus_GetCrosstalkVectorTable_Callback should be used.

Parameters

hnd	The API handle; contains all internal states and data.
value	The new crosstalk vector table.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_SetCalibrationGlobalRangeOffsets()

status_t Argus_SetCalibrationGlobalRangeOffsets	(	argus_hnd_t *	hnd,
		q0_15_t	offset_low,
		q0_15_t	offset_high
	)

Sets the global range offset values to a specified device.

The global range offsets are subtracted from the raw range values. There are two distinct values that are applied in low or high power stage setting respectively.

Parameters

hnd	The API handle; contains all internal states and data.
offset_low	The new global range offset for the low power stage in meter and Q0.15 format.
offset_high	The new global range offset for the high power stage in meter and Q0.15 format.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_SetCalibrationPixelRangeOffsets()

status_t Argus_SetCalibrationPixelRangeOffsets	(	argus_hnd_t *	hnd,
		argus_cal_offset_table_t const *	value
	)

Sets the relative pixel offset table to a specified device.

The relative pixel offset values are subtracted from the raw range values for each individual pixel. Note that a global range offset is applied additionally. The relative pixel offset values are meant to be with respect to the average range of all pixels, i.e. the average of all relative offsets should be 0!

The crosstalk vector table is a two dimensional array of type q0_15_t, wrapped within the argus_cal_offset_table_t structure.

The dimensions are:

size(0) = ARGUS_PIXELS_X (Pixel count in x-direction)
size(1) = ARGUS_PIXELS_Y (Pixel count in y-direction)

Its recommended to use the built-in pixel offset calibration sequence (see Argus_ExecuteRelativeRangeOffsetCalibrationSequence) to determine the offset table for the current device.

If a constant offset table for all device needs to be incorporated into the sources, the Argus_GetPixelRangeOffsets_Callback should be used.

Parameters

hnd	The API handle; contains all internal states and data.
value	The new relative range offset in meter and Q0.15 format.

Returns: Returns the status (STATUS_OK on success).

◆ Argus_SetCalibrationRangeOffsetSequenceSampleTime()

status_t Argus_SetCalibrationRangeOffsetSequenceSampleTime	(	argus_hnd_t *	hnd,
		uint16_t	value
	)

Sets the sample time for the range offset calibration sequence.

Gets the measurement sample acquisition time for executing the range offset calibration sequence and generate the offset data.
Units: msec.

Parameters

hnd	The API handle; contains all internal states and data.
value	The new range offset calibration sequence sample time.

Returns: Returns the status (STATUS_OK on success).

Data Structures

Functions

Detailed Description

Function Documentation

◆ Argus_ClearUserCalibration()

◆ Argus_GetCalibrationCrosstalkPixel2Pixel()

◆ Argus_GetCalibrationCrosstalkSequenceAmplitudeThreshold()

◆ Argus_GetCalibrationCrosstalkSequenceSampleTime()

◆ Argus_GetCalibrationCrosstalkVectorTable()

◆ Argus_GetCalibrationGlobalRangeOffsets()

◆ Argus_GetCalibrationGoldenPixel()

◆ Argus_GetCalibrationPixelRangeOffsets()

◆ Argus_GetCalibrationRangeOffsetSequenceSampleTime()

◆ Argus_GetCrosstalkVectorTable_Callback()

◆ Argus_GetPixelRangeOffsets_Callback()

◆ Argus_ResetCalibrationCrosstalkVectorTable()

◆ Argus_ResetCalibrationPixelRangeOffsets()

◆ Argus_SetCalibrationCrosstalkPixel2Pixel()

◆ Argus_SetCalibrationCrosstalkSequenceAmplitudeThreshold()

◆ Argus_SetCalibrationCrosstalkSequenceSampleTime()

◆ Argus_SetCalibrationCrosstalkVectorTable()

◆ Argus_SetCalibrationGlobalRangeOffsets()

◆ Argus_SetCalibrationPixelRangeOffsets()

◆ Argus_SetCalibrationRangeOffsetSequenceSampleTime()