Detailed Description

Defines producer/state related API.

Typical use case of a producer/state API is to (de)serialize a state to other processes/threads. A state will represent anything known to egomotion module up-to the last point of filter update. In most of the cases the state will store internally the history from the egomotion module and provide access to the history to query relative motion and absolute pose estimates.

The use-case is usually can be described like this:

dwEgomotionHandle_t egomotion = initializeEgomotion();
// get current state estimation
dwConstEgomotionStateHandle_t state;
dwEgomotion_createEmptyState(&state, egomotion);   // create empty state to feed egomotion to
...
dwEgomotion_getState(state, egomotion); // copy internal state
{
    // query state for a relative motion since last request
    dwTransformation3f motionLastToNow;
    dwEgomotionState_computeRelativeTransformation(&motionLastToNow, getLastTime(), getCurrentTime(), state);
    ...
    // query state for the latest known absolute estimation
    dwEgomotionResult estimation;
    dwEgomotionState_getEstimation(&estimation, state);
    ...
}
...

Data Structures
struct	dwEgomotionStateParams
	Defines egomotion state initialization parameters. More...

Typedefs
typedef struct dwEgomotionStateObject const *	dwConstEgomotionStateHandle_t

typedef struct dwEgomotionStateObject *	dwEgomotionStateHandle_t

Functions
DW_API_PUBLIC dwStatus	dwEgomotion_createEmptyState (dwEgomotionStateHandle_t *state, dwEgomotionHandle_t obj)
	Create empty state from the given egomotion module. More...

DW_API_PUBLIC dwStatus	dwEgomotion_getHistoryCapacity (size_t *capacity, dwEgomotionConstHandle_t obj)
	Returns the capacity of the history, i.e. More...

DW_API_PUBLIC dwStatus	dwEgomotion_getState (dwEgomotionStateHandle_t state, dwEgomotionConstHandle_t obj)
	Fills out already preallocated state handle. More...

DW_API_PUBLIC dwStatus	dwEgomotionState_computeRelativeTransformation (dwTransformation3f poseAtoB, dwEgomotionRelativeUncertainty uncertainty, dwTime_t timestamp_a, dwTime_t timestamp_b, dwConstEgomotionStateHandle_t obj)

DW_API_PUBLIC dwStatus	dwEgomotionState_copy (dwEgomotionStateHandle_t state, dwConstEgomotionStateHandle_t source)
	Copy existing egomotion state to preallocated state handle. More...

DW_API_PUBLIC dwStatus	dwEgomotionState_createEmpty (dwEgomotionStateHandle_t *state, dwEgomotionStateParams params, dwContextHandle_t ctx)
	Create empty state for a given motion model type. More...

DW_API_PUBLIC dwStatus	dwEgomotionState_deserialize (const uint8_t *buffer, size_t bufferSize, dwEgomotionStateHandle_t state)
	Deserialize the state from the provided buffer. More...

DW_API_PUBLIC dwStatus	dwEgomotionState_getEstimation (dwEgomotionResult *result, dwConstEgomotionStateHandle_t obj)

DW_API_PUBLIC dwStatus	dwEgomotionState_getEstimationTimestamp (dwTime_t *timestamp, dwConstEgomotionStateHandle_t obj)

DW_API_PUBLIC dwStatus	dwEgomotionState_getGyroscopeBias (dwVector3f *gyroBias, dwConstEgomotionStateHandle_t obj)

DW_API_PUBLIC dwStatus	dwEgomotionState_getHistoryCapacity (size_t *capacity, dwConstEgomotionStateHandle_t obj)

DW_API_PUBLIC dwStatus	dwEgomotionState_getHistoryElement (dwEgomotionResult pose, dwEgomotionUncertainty uncertainty, size_t index, dwConstEgomotionStateHandle_t obj)

DW_API_PUBLIC dwStatus	dwEgomotionState_getHistorySize (size_t *num, dwConstEgomotionStateHandle_t obj)

DW_API_PUBLIC dwStatus	dwEgomotionState_getMaxNumBytes (size_t *bufferSize, dwConstEgomotionStateHandle_t state)
	Get maximal number of bytes required for a buffer to contain serialized state. More...

DW_API_PUBLIC dwStatus	dwEgomotionState_getMotionModel (dwMotionModel *model, dwConstEgomotionStateHandle_t obj)

DW_API_PUBLIC dwStatus	dwEgomotionState_getUncertainty (dwEgomotionUncertainty *result, dwConstEgomotionStateHandle_t obj)

DW_API_PUBLIC dwStatus	dwEgomotionState_release (dwEgomotionStateHandle_t state)
	Releases the egomotion state previously created with `dwEgomotionState_createEmpty()`. More...

DW_API_PUBLIC dwStatus	dwEgomotionState_serialize (size_t numBytes, uint8_t buffer, size_t bufferSize, dwConstEgomotionStateHandle_t state)
	Serialize the state out into the provided buffer. More...

Data Structure Documentation

◆ dwEgomotionStateParams

struct dwEgomotionStateParams

Data Fields
size_t	historySize	Maximal number of elements to keep in history.
dwMotionModel	type	Type of the motion model used to hold data by the state.

Typedef Documentation

◆ dwConstEgomotionStateHandle_t

typedef struct dwEgomotionStateObject const* dwConstEgomotionStateHandle_t

Definition at line 88 of file EgomotionState.h.

◆ dwEgomotionStateHandle_t

typedef struct dwEgomotionStateObject* dwEgomotionStateHandle_t

Definition at line 87 of file EgomotionState.h.

Function Documentation

◆ dwEgomotion_createEmptyState()

DW_API_PUBLIC dwStatus dwEgomotion_createEmptyState	(	dwEgomotionStateHandle_t *	state,
		dwEgomotionHandle_t	obj
	)

Create empty state from the given egomotion module.

The call is equivalent to calling dwEgomotionState_createEmpty() with the right selection of parameters.

Parameters

[out]	state	Return here state handle of an empty state.
[in]	obj	Handle of the motion model.

Returns: DW_INVALID_ARGUMENT - if given state handle is null
DW_INVALID_HANDLE - if context handle is invalid
DW_SUCCESS

Note: Ownership of the state goes back to caller. The state has to be released with dwEgomotionState_release().

◆ dwEgomotion_getHistoryCapacity()

DW_API_PUBLIC dwStatus dwEgomotion_getHistoryCapacity	(	size_t *	capacity,
		dwEgomotionConstHandle_t	obj
	)

Returns the capacity of the history, i.e.

same parameter as passed with `dwEgomotionParameters.historySize' or default value used instead. Returned capacity can be used by dwEgomotionState_createEmpty() for initialization of the empty state, if same size of the history is desired as egomotion does uses internally.

Parameters

[out]	capacity	A pointer where to return the capacity of the history.
[in]	obj	Egomotion handle.

Returns: DW_INVALID_ARGUMENT - if the provided pointer is nullptr, or the given handle is invalid.
DW_SUCCESS

◆ dwEgomotion_getState()

DW_API_PUBLIC dwStatus dwEgomotion_getState	(	dwEgomotionStateHandle_t	state,
		dwEgomotionConstHandle_t	obj
	)

Fills out already preallocated state handle.

Given state handle can have a reduced history size. Only as many history elements get copied into the target state as it can fit. A reduced history reduces memory overhead during serialization/deserialization.

Parameters

[in,out]	state	Preallocated state to be filled with latest state
[in]	obj	Egomotion const handle.

Returns: DW_INVALID_ARGUMENT - if given state type does not match that one of the egomotion
DW_NOT_AVAILABLE - if there not state state estimation available on egomotion yet.
DW_INVALID_HANDLE - if the provided egomotion or state handle are invalid.
DW_SUCCESS

◆ dwEgomotionState_computeRelativeTransformation()

DW_API_PUBLIC dwStatus dwEgomotionState_computeRelativeTransformation	(	dwTransformation3f *	poseAtoB,
		dwEgomotionRelativeUncertainty *	uncertainty,
		dwTime_t	timestamp_a,
		dwTime_t	timestamp_b,
		dwConstEgomotionStateHandle_t	obj
	)

See also: dwEgomotion_computeRelativeTransformation()

◆ dwEgomotionState_copy()

DW_API_PUBLIC dwStatus dwEgomotionState_copy	(	dwEgomotionStateHandle_t	state,
		dwConstEgomotionStateHandle_t	source
	)

Copy existing egomotion state to preallocated state handle.

Parameters

[out]	state	Handle of the preallocated egomotion state.
[in]	source	Handle of the existing egomotion state.

Returns: DW_INVALID_HANDLE - if the provided egomotion state handle are invalid.
DW_NOT_AVAILABLE - if there not state estimation available on egomotion yet.
DW_SUCCESS

◆ dwEgomotionState_createEmpty()

DW_API_PUBLIC dwStatus dwEgomotionState_createEmpty	(	dwEgomotionStateHandle_t *	state,
		dwEgomotionStateParams	params,
		dwContextHandle_t	ctx
	)

Create empty state for a given motion model type.

An empty state can be used to deserialize from a binary buffer into the state. After deserialization state can be queried with state API for it's content. The state can contain internally a history of up-to passed amount of elements.

Parameters

[out]	state	Return here state handle of an empty state.
[in]	params	Parameters to initialize the state
[in]	ctx	Handle of the context.

Returns: DW_INVALID_ARGUMENT - if given state handle is null
DW_NOT_SUPPORTED - if given motion model is not supported by the state
DW_INVALID_HANDLE - if context handle is invalid
DW_SUCCESS

Note: Ownership of the state goes back to caller. The state has to be released with dwEgomotionState_release().; If passed historySize is smaller than the egomotion internal history capacity, any retrieval of the state with dwEgomotion_getState() will fill out this state's only with as much data as can fit, dropping oldest entries. This in turn would mean that calls to dwEgomotionState_computeRelativeTransformation() might not succeed if requested for timestamp outside of the covered history.

◆ dwEgomotionState_deserialize()

DW_API_PUBLIC dwStatus dwEgomotionState_deserialize	(	const uint8_t *	buffer,
		size_t	bufferSize,
		dwEgomotionStateHandle_t	state
	)

Deserialize the state from the provided buffer.

Parameters

[in]	buffer	Buffer containing serialized state
[in]	bufferSize	Size of the buffer provided
[in]	state	State handle to be deserialized

Returns: DW_INVALID_ARGUMENT - if the provided buffer is nullptr.
DW_OUT_OF_BOUNDS - if the provided bufferSize isn't enough to hold the state
DW_BUFFER_FULL - if the state's history isn't large enough to hold the deserialized state
DW_INVALID_VERSION - if the version of the data in the stream doesn't match current
DW_INVALID_HANDLE - if provided handle is invalid
DW_SUCCESS

◆ dwEgomotionState_getEstimation()

DW_API_PUBLIC dwStatus dwEgomotionState_getEstimation	(	dwEgomotionResult *	result,
		dwConstEgomotionStateHandle_t	obj
	)

See also: dwEgomotion_getEstimation()

◆ dwEgomotionState_getEstimationTimestamp()

DW_API_PUBLIC dwStatus dwEgomotionState_getEstimationTimestamp	(	dwTime_t *	timestamp,
		dwConstEgomotionStateHandle_t	obj
	)

See also: dwEgomotion_getEstimationTimestamp()

◆ dwEgomotionState_getGyroscopeBias()

DW_API_PUBLIC dwStatus dwEgomotionState_getGyroscopeBias	(	dwVector3f *	gyroBias,
		dwConstEgomotionStateHandle_t	obj
	)

See also: dwEgomotion_getGyroscopeBias()

◆ dwEgomotionState_getHistoryCapacity()

DW_API_PUBLIC dwStatus dwEgomotionState_getHistoryCapacity	(	size_t *	capacity,
		dwConstEgomotionStateHandle_t	obj
	)

See also: dwEgomotion_getHistoryCapacity()

◆ dwEgomotionState_getHistoryElement()

DW_API_PUBLIC dwStatus dwEgomotionState_getHistoryElement	(	dwEgomotionResult *	pose,
		dwEgomotionUncertainty *	uncertainty,
		size_t	index,
		dwConstEgomotionStateHandle_t	obj
	)

See also: dwEgomotion_getHistoryElement()

◆ dwEgomotionState_getHistorySize()

DW_API_PUBLIC dwStatus dwEgomotionState_getHistorySize	(	size_t *	num,
		dwConstEgomotionStateHandle_t	obj
	)

See also: dwEgomotion_getHistorySize()

◆ dwEgomotionState_getMaxNumBytes()

DW_API_PUBLIC dwStatus dwEgomotionState_getMaxNumBytes	(	size_t *	bufferSize,
		dwConstEgomotionStateHandle_t	state
	)

Get maximal number of bytes required for a buffer to contain serialized state.

Parameters

[out]	bufferSize	Size of the buffer required to hold serialized state
[in]	state	State handle to be serialized

Returns: DW_INVALID_ARGUMENT - if the provided bufferSize is nullptr.
DW_INVALID_HANDLE - if provided handle is invalid
DW_SUCCESS

◆ dwEgomotionState_getMotionModel()

DW_API_PUBLIC dwStatus dwEgomotionState_getMotionModel	(	dwMotionModel *	model,
		dwConstEgomotionStateHandle_t	obj
	)

See also: dwEgomotion_getMotionModel()

◆ dwEgomotionState_getUncertainty()

DW_API_PUBLIC dwStatus dwEgomotionState_getUncertainty	(	dwEgomotionUncertainty *	result,
		dwConstEgomotionStateHandle_t	obj
	)

See also: dwEgomotion_getUncertainty()

◆ dwEgomotionState_release()

DW_API_PUBLIC dwStatus dwEgomotionState_release ( dwEgomotionStateHandle_t state )

Releases the egomotion state previously created with dwEgomotionState_createEmpty().

Parameters

[in] state State handle to be released.

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

◆ dwEgomotionState_serialize()

DW_API_PUBLIC dwStatus dwEgomotionState_serialize	(	size_t *	numBytes,
		uint8_t *	buffer,
		size_t	bufferSize,
		dwConstEgomotionStateHandle_t	state
	)

Serialize the state out into the provided buffer.

Parameters

[out]	numBytes	number of bytes used to dump out the state. The number is always lower or equal to `dwEgomotionState_getMaxNumBytes()`
[out]	buffer	Buffer where the state will be serialized to
[in]	bufferSize	Size of the buffer provided, i.e. must be at least `dwEgomotionState_getMaxNumBytes()` large
[in]	state	State handle to be serialized

Returns: DW_INVALID_ARGUMENT - if the provided pointers are nullptr.
DW_OUT_OF_BOUNDS - if the provided bufferSize isn't enough to hold the state DW_INVALID_HANDLE - if provided handle is invalid
DW_SUCCESS

Detailed Description

Data Structures

Typedefs

Functions

Data Structure Documentation

◆ dwEgomotionStateParams

Typedef Documentation

◆ dwConstEgomotionStateHandle_t

◆ dwEgomotionStateHandle_t

Function Documentation

◆ dwEgomotion_createEmptyState()

◆ dwEgomotion_getHistoryCapacity()

◆ dwEgomotion_getState()

◆ dwEgomotionState_computeRelativeTransformation()

◆ dwEgomotionState_copy()

◆ dwEgomotionState_createEmpty()

◆ dwEgomotionState_deserialize()

◆ dwEgomotionState_getEstimation()

◆ dwEgomotionState_getEstimationTimestamp()

◆ dwEgomotionState_getGyroscopeBias()

◆ dwEgomotionState_getHistoryCapacity()

◆ dwEgomotionState_getHistoryElement()

◆ dwEgomotionState_getHistorySize()

◆ dwEgomotionState_getMaxNumBytes()

◆ dwEgomotionState_getMotionModel()

◆ dwEgomotionState_getUncertainty()

◆ dwEgomotionState_release()

◆ dwEgomotionState_serialize()