Producer/State API

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_computeBodyTransformation (dwTransformation3f *const transformationAToB, dwEgomotionRelativeUncertainty *const uncertainty, dwTime_t const timestamp, dwCoordinateSystem const coordinateSystemA, dwCoordinateSystem const coordinateSystemB, dwConstEgomotionStateHandle_t const obj)
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 *bufferCapacity, 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 bufferCapacity, 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	Handle to be set with pointer to created 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 - if the call was successful.

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 capacity of the history is desired as egomotion uses internally.

Parameters

[out]	capacity	Capacity to be set with history capacity of given egomotion instance.
[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]	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 is no state estimation available on egomotion yet.
DW_INVALID_HANDLE - if the provided egomotion or state handle are invalid.
DW_SUCCESS - if the call was successful.

dwEgomotionState_computeBodyTransformation()

DW_API_PUBLIC dwStatus dwEgomotionState_computeBodyTransformation	(	dwTransformation3f *const	transformationAToB,
		dwEgomotionRelativeUncertainty *const	uncertainty,
		dwTime_t const	timestamp,
		dwCoordinateSystem const	coordinateSystemA,
		dwCoordinateSystem const	coordinateSystemB,
		dwConstEgomotionStateHandle_t const	obj
	)

See also

dwEgomotion_computeBodyTransformation

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

[in]	state	Handle of pre-allocated egomotion state to be filled with a copy.
[in]	source	Handle of the existing egomotion state to be copied.

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 - if the call was successful.

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	Handle to be set with pointer to created 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 - if the call was successful.

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 - if the call was successful.

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 *	bufferCapacity,
		dwConstEgomotionStateHandle_t	state
	)

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

Parameters

[out]	bufferCapacity	Capacity to be set with number of bytes required to hold serialized state.
[in]	state	State handle to be serialized

Returns

DW_INVALID_ARGUMENT - if the provided bufferCapacity is nullptr.
DW_INVALID_HANDLE - if provided handle is invalid
DW_SUCCESS - if the call was successful.

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 - if the call was successful.

dwEgomotionState_serialize()

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

Serialize the state out into the provided buffer.

Parameters

[out]	numBytes	Size to be set with number of bytes written to buffer. The number is always lower than or equal dwEgomotionState_getMaxNumBytes.
[out]	buffer	Buffer to be filled with serialized state.
[in]	bufferCapacity	Capacity 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 bufferCapacity isn't enough to hold the state DW_INVALID_HANDLE - if provided handle is invalid
DW_SUCCESS - if the call was successful.