Provides global location and orientation estimation functionality.
- Note
- SW Release Applicability: These APIs are available in both NVIDIA DriveWorks and NVIDIA DRIVE Software releases.
|
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...
|
|
◆ dwGeoPointWGS84
◆ 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
|
◆ dwGeoPoint
◆ dwGlobalEgomotionConstHandle_t
◆ dwGlobalEgomotionHandle_t
◆ dwGlobalEgomotion_addGPSMeasurement()
Adds GPS measurement to the global egomotion module.
- 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_SUCCESS
◆ dwGlobalEgomotion_addRelativeMotion()
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.
-
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()
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] | 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
◆ dwGlobalEgomotion_getEstimate()
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
◆ dwGlobalEgomotion_getHistoryEntry()
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
◆ dwGlobalEgomotion_getHistorySize()
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
◆ dwGlobalEgomotion_getTimestamp()
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
◆ dwGlobalEgomotion_initialize()
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
◆ dwGlobalEgomotion_initParamsFromRig()
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
- 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()
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
◆ dwGlobalEgomotion_reset()
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