DriveWorks SDK Reference
3.0.4260 Release
For Test and Development only

Global Egomotion Interface

Detailed Description

Provides global location and orientation estimation functionality.

Note
SW Release Applicability: These APIs are available in both NVIDIA DriveWorks and NVIDIA DRIVE Software releases.

Data Structures

struct  dwGeoPointWGS84
 Location point defined by WGS84 coordinates. More...
 
struct  dwGlobalEgomotionParameters
 Holds initialization parameters for the global egomotion module. More...
 
struct  dwGlobalEgomotionResult
 Holds global egomotion state estimate. More...
 
struct  dwGlobalEgomotionUncertainty
 Holds global egomotion uncertainty estimate. More...
 
struct  dwGNSSCharacteristics
 GNSS Sensor characteristics. More...
 

Typedefs

typedef dwGeoPointWGS84 dwGeoPoint
 alias for the geo point More...
 
typedef struct dwGlobalEgomotionObject const * dwGlobalEgomotionConstHandle_t
 
typedef struct dwGlobalEgomotionObject * dwGlobalEgomotionHandle_t
 

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

◆ dwGeoPointWGS84

struct dwGeoPointWGS84
Data Fields
float64_t height height above WGS84 earth spheroid
float64_t lat latitude
float64_t lon longitude

◆ 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

dwGNSSCharacteristics sensorCharacteristics Sensor characteristics.

If this struct is zero initialized, default assumptions are made.

◆ dwGlobalEgomotionResult

struct dwGlobalEgomotionResult
Data Fields
dwQuaternionf orientation Rotation from rig coordinate system to ENU coordinate system.
dwGeoPointWGS84 position Position in WGS-84 reference system.
dwTime_t timestamp Estimate timestamp.
bool validOrientation Indicates validity of orientation estimate.
bool validPosition Indicates validity of position estimate.

◆ dwGlobalEgomotionUncertainty

struct dwGlobalEgomotionUncertainty
Data Fields
dwConfidence3f orientation Orientation uncertainty (roll [rad], pitch [rad], yaw [rad]).
dwConfidence3f position Position uncertainty (easting [m], northing [m], altitude [m]).
dwTime_t timestamp Estimate timestamp.
bool validOrientation Indicates validity of orientation uncertainty estimate.
bool validPosition Indicates validity of position uncertainty estimate.

◆ dwGNSSCharacteristics

struct dwGNSSCharacteristics
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

Typedef Documentation

◆ dwGeoPoint

alias for the geo point

Definition at line 111 of file GlobalEgomotion.h.

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

Function Documentation

◆ dwGlobalEgomotion_addGPSMeasurement()

DW_API_PUBLIC dwStatus dwGlobalEgomotion_addGPSMeasurement ( const dwGPSFrame measurement,
dwGlobalEgomotionHandle_t  handle 
)

Adds GPS measurement to the global egomotion module.

Parameters
[in]measurementGPS measurement.
[in]handleGlobal 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_SUCCESS

◆ 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]egomotionResultState estimate provided by relative egomotion.
[in]egomotionUncertaintyUncertainty estimate provided by relative egomotion.
[in]handleGlobal 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.
The rotation estimate shall be in DW_EGOMOTION_LOCAL_FRAME, this method will return DW_NOT_SUPPORTED otherwise.
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
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

◆ 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 and does not limit it. The uncertainty estimates are not extrapolated and held constant.

This method does not modify the filter state.

Parameters
[out]resultGlobal state estimate.
[out]uncertaintyGlobal state uncertainty estimate (optional, can be null).
[in]timestampTimestamp for which to provide position estimate.
[in]handleGlobal 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

◆ dwGlobalEgomotion_getEstimate()

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

Get current filter state estimate.

Parameters
[out]resultCurrent filter state estimate.
[out]uncertaintyCurrent global state uncertainty estimate (optional, can be null).
[in]handleGlobal 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

◆ 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]resultGlobal state estimate.
[out]uncertaintyGlobal state uncertainty estimate (optional, can be null).
[in]indexIndex into the history, in the range [0, dwGlobalEgomotion_getHistorySize), with 0 being most recent estimate and last element pointing to oldest estimate.
[in]handleGlobal 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

◆ 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]numA pointer to the number of estimates in the history.
[in]handleGlobal Egomotion module handle.
Returns
DW_INVALID_ARGUMENT - if the provided pointer is invalid
DW_INVALID_HANDLE - if the provided handle is invalid
DW_SUCCESS

◆ dwGlobalEgomotion_getTimestamp()

DW_API_PUBLIC dwStatus dwGlobalEgomotion_getTimestamp ( dwTime_t timestamp,
dwGlobalEgomotionConstHandle_t  handle 
)

Get timestamp of current filter estimate.

Parameters
[out]timestampTimestamp of current filter estimate.
[in]handleGlobal 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

◆ dwGlobalEgomotion_initialize()

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

Initializes the global egomotion module.

Parameters
[out]handleA pointer to the handle for the created module.
[in]paramsA pointer to the configuration parameters of the module.
[in]ctxSpecifies 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

◆ 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]paramsPointer to a parameter struct to be filled out with sensor parameters
[in]rigConfigurationHandle to a rig configuration to retrieve parameters from
[in]gpsSensorNamename 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
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

◆ 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]handleGlobal Egomotion handle to be released.
Returns
DW_INVALID_HANDLE - if the provided egomotion handle is invalid.
DW_SUCCESS

◆ 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]handleGlobal Egomotion handle to be reset.
Returns
DW_INVALID_HANDLE - if the provided handle is invalid.
DW_SUCCESS