Detailed Description

Provides global location and orientation estimation functionality.

Data Structures
struct	dwGlobalEgomotionGNSSCharacteristics
	GNSS Sensor characteristics. More...

struct	dwGlobalEgomotionParameters
	Holds initialization parameters for the global egomotion module. More...

Typedefs
typedef struct dwGlobalEgomotionObject const *	dwGlobalEgomotionConstHandle_t

typedef struct dwGlobalEgomotionObject *	dwGlobalEgomotionHandle_t

typedef dwGlobalEgomotionGNSSCharacteristics	dwGNSSCharacteristics

Functions
DW_API_PUBLIC dwStatus	dwGlobalEgomotion_addGPSMeasurement (const dwGPSFrame *measurement, dwGlobalEgomotionHandle_t handle)
	Adds GPS measurement to the global egomotion module. More...

DW_API_PUBLIC dwStatus	dwGlobalEgomotion_addRelativeMotion (const dwEgomotionResult egomotionResult, const dwEgomotionUncertainty egomotionUncertainty, dwGlobalEgomotionHandle_t handle)
	Adds relative egomotion estimate to the global egomotion module. More...

DW_API_PUBLIC dwStatus	dwGlobalEgomotion_computeEstimate (dwGlobalEgomotionResult result, dwGlobalEgomotionUncertainty uncertainty, dwTime_t timestamp, dwGlobalEgomotionConstHandle_t handle)
	Computes global state estimate at given timestamp, if necessary by linear interpolation between available history entries. More...

DW_API_PUBLIC dwStatus	dwGlobalEgomotion_getEstimate (dwGlobalEgomotionResult result, dwGlobalEgomotionUncertainty uncertainty, dwGlobalEgomotionConstHandle_t handle)
	Get current filter state estimate. More...

DW_API_PUBLIC dwStatus	dwGlobalEgomotion_getHistoryEntry (dwGlobalEgomotionResult result, dwGlobalEgomotionUncertainty uncertainty, size_t index, dwGlobalEgomotionConstHandle_t handle)
	Returns an entry from the history array. More...

DW_API_PUBLIC dwStatus	dwGlobalEgomotion_getHistorySize (size_t *num, dwGlobalEgomotionConstHandle_t handle)
	Returns the number of estimates currently stored in the history. More...

DW_API_PUBLIC dwStatus	dwGlobalEgomotion_getTimestamp (dwTime_t *timestamp, dwGlobalEgomotionConstHandle_t handle)
	Get timestamp of current filter estimate. More...

DW_API_PUBLIC dwStatus	dwGlobalEgomotion_initialize (dwGlobalEgomotionHandle_t handle, const dwGlobalEgomotionParameters params, dwContextHandle_t ctx)
	Initializes the global egomotion module. More...

DW_API_PUBLIC dwStatus	dwGlobalEgomotion_initParamsFromRig (dwGlobalEgomotionParameters params, dwConstRigHandle_t rigConfiguration, const char gpsSensorName)
	Initialize global egomotion parameters from a provided RigConfiguration. More...

DW_API_PUBLIC dwStatus	dwGlobalEgomotion_release (dwGlobalEgomotionHandle_t handle)
	Releases the global egomotion module. More...

DW_API_PUBLIC dwStatus	dwGlobalEgomotion_reset (dwGlobalEgomotionHandle_t handle)
	Resets the state estimate and all history of the global egomotion module. More...

Data Structure Documentation

◆ dwGlobalEgomotionGNSSCharacteristics

struct dwGlobalEgomotionGNSSCharacteristics

Data Fields
dwVector3f	antennaPosition	GNSS antenna position in the rig coordinate system [m].
float32_t	horizontalNoiseMeter	Expected horizontal position noise (CEP) of the GNSS sensor [m] A default value of 2.5 [m] will be assumed if no parameter, i.e. 0 or nan, passed
float32_t	verticalNoiseMeter	Expected vertical position noise (CEP) of the GNSS sensor [m] A default value of 5 [m] will be assumed if no parameter, i.e. 0 or nan, passed

◆ dwGlobalEgomotionParameters

struct dwGlobalEgomotionParameters

Data Fields
size_t	historySize	Size of history array, in number of state estimates it holds. A default value is 1000 is used if this is left zero-initialized.
float32_t	rotationalDrift	Expected magnitude of relative egomotion rotational drift [deg/s] A default value of 10 [deg/h] will be assumed if no parameter, i.e. 0 or nan, passed
dwGlobalEgomotionGNSSCharacteristics	sensorCharacteristics	Sensor characteristics. If this struct is zero initialized, default assumptions are made.

Typedef Documentation

◆ dwGlobalEgomotionConstHandle_t

typedef struct dwGlobalEgomotionObject const* dwGlobalEgomotionConstHandle_t

Definition at line 61 of file GlobalEgomotion.h.

◆ dwGlobalEgomotionHandle_t

typedef struct dwGlobalEgomotionObject* dwGlobalEgomotionHandle_t

Definition at line 60 of file GlobalEgomotion.h.

◆ dwGNSSCharacteristics

typedef dwGlobalEgomotionGNSSCharacteristics dwGNSSCharacteristics

Definition at line 81 of file GlobalEgomotion.h.

Function Documentation

◆ dwGlobalEgomotion_addGPSMeasurement()

DW_API_PUBLIC dwStatus dwGlobalEgomotion_addGPSMeasurement	(	const dwGPSFrame *	measurement,
		dwGlobalEgomotionHandle_t	handle
	)

Adds GPS measurement to the global egomotion module.

Valid GPS measurements must contain longitude, latitude and altitude signals. When present, the data is further monitored with e.g. timestamp monotonicity checks.

Parameters

[in]	measurement	GPS measurement.
[in]	handle	Global Egomotion handle.

Note: providing GPS measurements only isn't sufficient to generate a state estimate, call dwGlobalEgomotion_addRelativeMotion() to provide the relative egomotion state estimate and generate new estimates.

Returns: DW_INVALID_HANDLE - if the provided handle is invalid
DW_INVALID_ARGUMENT - if measurement timestamp isn't more recent than previous
DW_SUCCESS - GPS data was added to global egomotion

API Group

Init: Yes
Runtime: Yes
De-Init: Yes

◆ dwGlobalEgomotion_addRelativeMotion()

DW_API_PUBLIC dwStatus dwGlobalEgomotion_addRelativeMotion	(	const dwEgomotionResult *	egomotionResult,
		const dwEgomotionUncertainty *	egomotionUncertainty,
		dwGlobalEgomotionHandle_t	handle
	)

Adds relative egomotion estimate to the global egomotion module.

Parameters

[in]	egomotionResult	State estimate provided by relative egomotion.
[in]	egomotionUncertainty	Uncertainty estimate provided by relative egomotion.
[in]	handle	Global Egomotion handle.

Note

the state and state uncertainty estimates are required to at least have the following flags set:

DW_EGOMOTION_ROTATION
DW_EGOMOTION_LIN_VEL_X
DW_EGOMOTION_ANG_VEL_Z If any of those flags isn't set, the provided estimate will be ignored and this method will return DW_NOT_AVAILABLE.

Returns: DW_INVALID_ARGUMENT - if any input arguments are invalid
DW_INVALID_HANDLE - if the provided handle is invalid
DW_NOT_AVAILABLE - if the relative egomotion estimates are missing required flags or the timestamp isn't more recent that previous
DW_NOT_SUPPORTED - if the relative egomotion rotation estimate is not relative to local frame
DW_NOT_READY - no new estimate was added to history; filter missing GPS data or estimate timestamp isn't more recent than current estimate timestamp.
DW_SUCCESS - a new estimate has been added to the history

API Group

Init: Yes
Runtime: Yes
De-Init: Yes

◆ dwGlobalEgomotion_computeEstimate()

DW_API_PUBLIC dwStatus dwGlobalEgomotion_computeEstimate	(	dwGlobalEgomotionResult *	result,
		dwGlobalEgomotionUncertainty *	uncertainty,
		dwTime_t	timestamp,
		dwGlobalEgomotionConstHandle_t	handle
	)

Computes global state estimate at given timestamp, if necessary by linear interpolation between available history entries.

This API currently supports linear extrapolation, limited to 1 second. The uncertainty estimates are not extrapolated and held constant.

This method does not modify the filter state.

Parameters

[out]	result	Global state estimate.
[out]	uncertainty	Global state uncertainty estimate (optional, can be null).
[in]	timestamp	Timestamp for which to provide position estimate.
[in]	handle	Global Egomotion module handle.

Returns: DW_INVALID_ARGUMENT - if provided pointers are invalid
DW_INVALID_HANDLE - if the provided handle is invalid
DW_NOT_AVAILABLE - no state estimate available yet
DW_SUCCESS - estimates successfully returned

API Group

Init: Yes
Runtime: Yes
De-Init: Yes

◆ dwGlobalEgomotion_getEstimate()

DW_API_PUBLIC dwStatus dwGlobalEgomotion_getEstimate	(	dwGlobalEgomotionResult *	result,
		dwGlobalEgomotionUncertainty *	uncertainty,
		dwGlobalEgomotionConstHandle_t	handle
	)

Get current filter state estimate.

Parameters

[out]	result	Current filter state estimate.
[out]	uncertainty	Current global state uncertainty estimate (optional, can be null).
[in]	handle	Global Egomotion module handle.

Returns: DW_INVALID_ARGUMENT - if provided pointers are invalid
DW_INVALID_HANDLE - if the provided handle is invalid
DW_NOT_AVAILABLE - no state estimate available yet
DW_SUCCESS - estimates successfully returned

API Group

Init: Yes
Runtime: Yes
De-Init: Yes

◆ dwGlobalEgomotion_getHistoryEntry()

DW_API_PUBLIC dwStatus dwGlobalEgomotion_getHistoryEntry	(	dwGlobalEgomotionResult *	result,
		dwGlobalEgomotionUncertainty *	uncertainty,
		size_t	index,
		dwGlobalEgomotionConstHandle_t	handle
	)

Returns an entry from the history array.

Parameters

[out]	result	Global state estimate.
[out]	uncertainty	Global state uncertainty estimate (optional, can be null).
[in]	index	Index into the history, in the range [0, `dwGlobalEgomotion_getHistorySize`), with 0 being most recent estimate and last element pointing to oldest estimate.
[in]	handle	Global Egomotion module handle.

Returns: DW_NOT_AVAILABLE - no state estimate available yet, or the requested index is outside of the available history range
DW_INVALID_ARGUMENT - if the provided pointer is invalid
DW_INVALID_HANDLE - if the provided handle is invalid
DW_SUCCESS - history entry successfully returned

API Group

Init: Yes
Runtime: Yes
De-Init: Yes

◆ dwGlobalEgomotion_getHistorySize()

DW_API_PUBLIC dwStatus dwGlobalEgomotion_getHistorySize	(	size_t *	num,
		dwGlobalEgomotionConstHandle_t	handle
	)

Returns the number of estimates currently stored in the history.

Parameters

[out]	num	A pointer to the number of estimates in the history.
[in]	handle	Global Egomotion module handle.

Returns: DW_INVALID_ARGUMENT - if the provided pointer is invalid
DW_INVALID_HANDLE - if the provided handle is invalid
DW_SUCCESS - state history successfully returned

API Group

Init: Yes
Runtime: Yes
De-Init: Yes

◆ dwGlobalEgomotion_getTimestamp()

DW_API_PUBLIC dwStatus dwGlobalEgomotion_getTimestamp	(	dwTime_t *	timestamp,
		dwGlobalEgomotionConstHandle_t	handle
	)

Get timestamp of current filter estimate.

Parameters

[out]	timestamp	Timestamp of current filter estimate.
[in]	handle	Global Egomotion module handle.

Returns: DW_INVALID_ARGUMENT - if provided timestamp pointer is invalid
DW_INVALID_HANDLE - if the provided handle is invalid
DW_NOT_AVAILABLE - no state estimate available yet
DW_SUCCESS - timestamp successfully returned

API Group

Init: Yes
Runtime: Yes
De-Init: Yes

◆ dwGlobalEgomotion_initialize()

DW_API_PUBLIC dwStatus dwGlobalEgomotion_initialize	(	dwGlobalEgomotionHandle_t *	handle,
		const dwGlobalEgomotionParameters *	params,
		dwContextHandle_t	ctx
	)

Initializes the global egomotion module.

Parameters

[out]	handle	A pointer to the handle for the created module.
[in]	params	A pointer to the configuration parameters of the module.
[in]	ctx	Specifies the handler to the context under which the module is created.

Returns: DW_INVALID_ARGUMENT - if provided parameters are invalid
DW_INVALID_HANDLE - if the provided handle is invalid
DW_SUCCESS - if initialization succeeded

API Group

Init: Yes
Runtime: No
De-Init: No

◆ dwGlobalEgomotion_initParamsFromRig()

DW_API_PUBLIC dwStatus dwGlobalEgomotion_initParamsFromRig	(	dwGlobalEgomotionParameters *	params,
		dwConstRigHandle_t	rigConfiguration,
		const char *	gpsSensorName
	)

Initialize global egomotion parameters from a provided RigConfiguration.

This will read out relevant sensor parameters and apply them on top of default parameters.

Parameters

[out]	params	Pointer to a parameter struct to be filled out with sensor parameters
[in]	rigConfiguration	Handle to a rig configuration to retrieve parameters from
[in]	gpsSensorName	name of the GPS sensor to be used

Returns: DW_INVALID_ARGUMENT - if provided params pointer or rig handle are invalid
DW_FILE_INVALID - if provided sensor could not be found in the rig config
DW_SUCCESS - if initialization of parameters succeeded

Note

Clears any existing parameters set in params.

Following parameters are extracted from the rig configuration: GPS sensor:

Position of the sensor -> dwGlobalEgomotionParameters.sensorCharacteristics.antennaPosition

API Group

Init: Yes
Runtime: No
De-Init: No

◆ dwGlobalEgomotion_release()

DW_API_PUBLIC dwStatus dwGlobalEgomotion_release ( dwGlobalEgomotionHandle_t handle )

Releases the global egomotion module.

Note: This method renders the handle unusable.

Parameters

[in] handle Global Egomotion handle to be released.

Returns: DW_INVALID_HANDLE - if the provided egomotion handle is invalid.
DW_SUCCESS - if release succeeded

API Group

Init: Yes
Runtime: No
De-Init: Yes

◆ dwGlobalEgomotion_reset()

DW_API_PUBLIC dwStatus dwGlobalEgomotion_reset ( dwGlobalEgomotionHandle_t handle )

Resets the state estimate and all history of the global egomotion module.

Parameters

[in] handle Global Egomotion handle to be reset.

Returns: DW_INVALID_HANDLE - if the provided handle is invalid.
DW_SUCCESS - if reset succeeded

API Group

Init: Yes
Runtime: Yes
De-Init: Yes

Detailed Description

Data Structures

Typedefs

Functions

Data Structure Documentation

◆ dwGlobalEgomotionGNSSCharacteristics

◆ dwGlobalEgomotionParameters

Typedef Documentation

◆ dwGlobalEgomotionConstHandle_t

◆ dwGlobalEgomotionHandle_t

◆ dwGNSSCharacteristics

Function Documentation

◆ dwGlobalEgomotion_addGPSMeasurement()

◆ dwGlobalEgomotion_addRelativeMotion()

◆ dwGlobalEgomotion_computeEstimate()

◆ dwGlobalEgomotion_getEstimate()

◆ dwGlobalEgomotion_getHistoryEntry()

◆ dwGlobalEgomotion_getHistorySize()

◆ dwGlobalEgomotion_getTimestamp()

◆ dwGlobalEgomotion_initialize()

◆ dwGlobalEgomotion_initParamsFromRig()

◆ dwGlobalEgomotion_release()

◆ dwGlobalEgomotion_reset()