Detailed Description

Performs pose estimation and feature triangulation from visual matches.

Data Structures
struct	dwReconstructorConfig
	Configuration parameters for a reconstructor. More...

Typedefs
typedef struct dwReconstructorObject const *	dwConstReconstructorHandle_t
	Handle representing a const reconstructor object. More...

typedef struct dwReconstructorObject *	dwReconstructorHandle_t
	Handle representing a reconstructor object. More...

Functions
DW_API_PUBLIC dwStatus	dwReconstructor_compactFeatureHistory (const uint32_t cameraIdx, const uint32_t d_validIndexCount, const uint32_t d_newToOldMap, dwReconstructorHandle_t obj)
	Compacts the internal feature history by keeping only selected features. More...

DW_API_PUBLIC dwStatus	dwReconstructor_compactWorldPoints (dwVector4f d_worldPoints, const uint32_t d_validIndexCount, const uint32_t *d_newToOldMap, dwReconstructorHandle_t obj)
	Compacts the world point array by keeping only selected features. More...

DW_API_PUBLIC dwStatus	dwReconstructor_enableCamerasForPoseEstimation (uint8_t const enabled[], dwReconstructorHandle_t obj)
	Marks the cameras to use for pose estimation. More...

DW_API_PUBLIC dwStatus	dwReconstructor_estimatePoseAsync (const dwTransformation3f previousRig2World, const dwTransformation3f predictedRig2World, const uint32_t listCount, const uint32_t const d_featureCounts[], const dwFeature2DStatus const d_statuses[], const dwVector2f const d_trackedLocations[], const dwVector4f const d_worldPoints[], dwReconstructorHandle_t obj)
	Uses all tracked features from all cameras to estimate the current rig pose. More...

DW_API_PUBLIC dwStatus	dwReconstructor_getCUDAStream (cudaStream_t *stream, dwReconstructorHandle_t obj)
	Gets CUDA stream used by the reconstructor. More...

DW_API_PUBLIC dwStatus	dwReconstructor_getEstimatedPose (dwTransformation3f *correctedRig2World, dwReconstructorHandle_t obj)
	Returns the estimated pose from a previous call to dwReconstructor_estimatePoseAsync. More...

DW_API_PUBLIC dwStatus	dwReconstructor_initConfig (dwReconstructorConfig *config)
	Initializes the reconstructor config with default values. More...

DW_API_PUBLIC dwStatus	dwReconstructor_initialize (dwReconstructorHandle_t obj, const dwReconstructorConfig config, cudaStream_t stream, dwContextHandle_t context)
	Creates and initializes a reconstructor. More...

DW_API_PUBLIC dwStatus	dwReconstructor_predictFeaturePosition (dwVector2f d_predictedLocations[], uint32_t cameraIdx, const dwTransformation3f previousRigToWorld, const dwTransformation3f predictedRigToWorld, const uint32_t *d_featureCount, const dwFeature2DStatus d_featureStatuses[], const dwVector2f d_featureLocations[], const dwVector4f d_worldPoints[], dwReconstructorHandle_t obj)
	Predicts the positions of features based on the predicted car motion. More...

DW_API_PUBLIC dwStatus	dwReconstructor_project (dwVector2f d_locations[], const dwTransformation3f rig2World, const uint32_t const d_pointCount[], const dwVector4f const d_worldPoints[], dwReconstructorHandle_t obj)
	Projects triangulated features back to the image. More...

DW_API_PUBLIC dwStatus	dwReconstructor_release (dwReconstructorHandle_t obj)
	Releases a reconstructor. More...

DW_API_PUBLIC dwStatus	dwReconstructor_reset (dwReconstructorHandle_t obj)
	Resets a reconstructor. More...

DW_API_PUBLIC dwStatus	dwReconstructor_setCUDAStream (cudaStream_t stream, dwReconstructorHandle_t obj)
	Sets the CUDA stream for CUDA related operations. More...

DW_API_PUBLIC dwStatus	dwReconstructor_triangulateFeatures (dwVector4f d_worldPoints, dwFeature2DStatus d_statuses, const uint32_t *d_featureCount, const uint32_t cameraIdx, dwReconstructorHandle_t obj)
	Triangulates the features of a camera from the internal feature and pose history. More...

DW_API_PUBLIC dwStatus	dwReconstructor_updateHistory (int32_t rig2WorldHistoryIdx, const dwTransformation3f rig2World, const uint32_t listCount, const uint32_t const d_featureCounts[], const dwVector2f const d_trackedLocations[], dwReconstructorHandle_t obj)
	Updates the feature and pose history. More...

Data Structure Documentation

◆ dwReconstructorConfig

struct dwReconstructorConfig

Data Fields
uint32_t	maxFeatureCount	Specifies the maximum number of features for each camera.
uint32_t	maxPoseHistoryLength	Specifies the maximum size of the history.
float32_t	maxReprojectionErrorAngleRad	Specifies the max angle of the reprojection error (angle between tracked optical ray and triangulated optical ray) to consider the feature an outlier during triangulation. Observations with a reprojection error higher than this after triangulation are discarded.
float32_t	minNewObservationAngleRad	Specifies the minimum cosine of the angle between two optical rays to add a new one to the feature history.
float32_t	minRigDistance	Specifies the minimum distance between vehicle poses to add a new one to the list. Note Not implemented
uint8_t	minTriangulationEntries	Specifies the minimum number of entries in the feature history needed for triangulation.
float32_t	poseEstimationOutlierThresholdRad	Specifies the max angle of the reprojection error (angle between tracked optical ray and triangulated optical ray) to consider the feature an outlier during pose estimation. Observations with a reprojection error higher than this will have less influence in the pose estimation.
dwConstRigHandle_t	rig	Specifies the rig to use for reconstruction.

Typedef Documentation

◆ dwConstReconstructorHandle_t

typedef struct dwReconstructorObject const* dwConstReconstructorHandle_t

Handle representing a const reconstructor object.

Definition at line 82 of file SFM.h.

◆ dwReconstructorHandle_t

typedef struct dwReconstructorObject* dwReconstructorHandle_t

Handle representing a reconstructor object.

This object performs pose estimation and feature triangulation from visual matches.

Definition at line 79 of file SFM.h.

Function Documentation

◆ dwReconstructor_compactFeatureHistory()

DW_API_PUBLIC dwStatus dwReconstructor_compactFeatureHistory	(	const uint32_t	cameraIdx,
		const uint32_t *	d_validIndexCount,
		const uint32_t *	d_newToOldMap,
		dwReconstructorHandle_t	obj
	)

Compacts the internal feature history by keeping only selected features.

Note that this method must be called after dwFeature2DTracker_compact() or dwFeature2DTracker_process(DW_FEATURE2D_TRACKER_STAGE_COMPACT_GPU_ASYNC) to keep the feature lists synchronized.

Parameters

[in]	cameraIdx	Index of the camera to compact for.
[in]	d_validIndexCount	The number of valid indexes in the list. GPU pointer.
[in]	d_newToOldMap	Mapping array of compacted data to uncompacted sparse data. GPU pointer.
[in]	obj	The reconstructor object handle.

Note: d_newToOldMap must be got by dwFeature2DTracker_getNewToOldMap

◆ dwReconstructor_compactWorldPoints()

DW_API_PUBLIC dwStatus dwReconstructor_compactWorldPoints	(	dwVector4f *	d_worldPoints,
		const uint32_t *	d_validIndexCount,
		const uint32_t *	d_newToOldMap,
		dwReconstructorHandle_t	obj
	)

Compacts the world point array by keeping only selected features.

Note that this method must be called after dwFeature2DTracker_compact() or dwFeature2DTracker_process(DW_FEATURE2D_TRACKER_STAGE_COMPACT_GPU_ASYNC) to keep the feature lists synchronized.

Parameters

[in,out]	d_worldPoints	GPU array of 4-floats.
[in]	d_validIndexCount	The number of valid indexes in the list. GPU pointer.
[in]	d_newToOldMap	Mapping array of compacted data to uncompacted sparse data. GPU pointer.
[in]	obj	The reconstructor object handle.

◆ dwReconstructor_enableCamerasForPoseEstimation()

DW_API_PUBLIC dwStatus dwReconstructor_enableCamerasForPoseEstimation	(	uint8_t const	enabled[],
		dwReconstructorHandle_t	obj
	)

Marks the cameras to use for pose estimation.

Cameras with their flag set to false are ignored and the value of the feature list and pointers are ignored for that camera during pose estimation.

Parameters

[in]	enabled	Array of flags to indicate that a camera is enabled. Camera i is enabled if enabled[i] != 0. Size of the buffer must be the same as the rig's camera count.
[in]	obj	The reconstructor object handle.

Returns: DW_SUCCESS
DW_INVALID_HANDLE - If the given context handle is invalid,i.e. null or of wrong type
DW_BAD_CAST
DW_INVALID_ARGUMENT

◆ dwReconstructor_estimatePoseAsync()

DW_API_PUBLIC dwStatus dwReconstructor_estimatePoseAsync	(	const dwTransformation3f *	previousRig2World,
		const dwTransformation3f *	predictedRig2World,
		const uint32_t	listCount,
		const uint32_t *const	d_featureCounts[],
		const dwFeature2DStatus *const	d_statuses[],
		const dwVector2f *const	d_trackedLocations[],
		const dwVector4f *const	d_worldPoints[],
		dwReconstructorHandle_t	obj
	)

Uses all tracked features from all cameras to estimate the current rig pose.

Processes all cameras simultaneously.

Parameters

[in]	previousRig2World	A pointer to the position of the rig in the previous frame.
[in]	predictedRig2World	A pointer to the initial estimate of the rig's pose. The reconstructor refines this initial estimate based on the tracked features.
[in]	listCount	The number of feature lists provided in the following parameters. This must match the number of cameras in the rig.
[in]	d_statuses	A pointer to the status of the tracked features. Features with an invalid status are ignored. Pointers to GPU memory.
[in]	d_featureCounts	A pointer to the number of tracked features. There is one feature count per feature list. Pointers to GPU memory.
[in]	d_trackedLocations	A pointer to the 2D position of the tracked features in the images. One list per camera in the rig. List i has listCount[i] elements. Pointer to GPU memory.
[in]	d_worldPoints	A pointer to the 3D position of the tracked features in the images. One list per camera in the rig. List i has listCount[i] elements. Pointer to GPU memory.
[in]	obj	The reconstructor object handle.

Returns: DW_SUCCESS
DW_INVALID_HANDLE - If the given context handle is invalid,i.e. null or of wrong type
DW_BAD_CAST
DW_INVALID_ARGUMENT

◆ dwReconstructor_getCUDAStream()

DW_API_PUBLIC dwStatus dwReconstructor_getCUDAStream	(	cudaStream_t *	stream,
		dwReconstructorHandle_t	obj
	)

Gets CUDA stream used by the reconstructor.

Parameters

[out]	stream	The CUDA stream currently used
[in]	obj	A handle to the feature list module.

Returns: DW_INVALID_HANDLE if the given context handle is invalid,i.e. null or of wrong type
or DW_SUCCESS otherwise.

◆ dwReconstructor_getEstimatedPose()

DW_API_PUBLIC dwStatus dwReconstructor_getEstimatedPose	(	dwTransformation3f *	correctedRig2World,
		dwReconstructorHandle_t	obj
	)

Returns the estimated pose from a previous call to dwReconstructor_estimatePoseAsync.

Parameters

[out]	correctedRig2World	The corrected rig to world pose.
[in]	obj	The reconstructor object handle.

Returns: DW_SUCCESS
DW_INVALID_HANDLE - If the given context handle is invalid,i.e. null or of wrong type
DW_BAD_CAST
DW_INVALID_ARGUMENT

◆ dwReconstructor_initConfig()

DW_API_PUBLIC dwStatus dwReconstructor_initConfig ( dwReconstructorConfig * config )

Initializes the reconstructor config with default values.

Parameters

[out] config Config to initialize.

Returns: DW_SUCCESS, DW_INVALID_ARGUMENT

◆ dwReconstructor_initialize()

DW_API_PUBLIC dwStatus dwReconstructor_initialize	(	dwReconstructorHandle_t *	obj,
		const dwReconstructorConfig *	config,
		cudaStream_t	stream,
		dwContextHandle_t	context
	)

Creates and initializes a reconstructor.

Parameters

[out]	obj	A pointer to the reconstructor handle is returned here.
[in]	config	Spcifies the configuration parameters for the reconstructor.
[in]	stream	Specifies the CUDA stream to use for all reconstructor operations.
[in]	context	Specifies the handle to the context under which it is created.

Returns: DW_SUCCESS
DW_INVALID_HANDLE - If the given context handle is invalid,i.e. null or of wrong type
DW_BAD_CAST
DW_INVALID_ARGUMENT

◆ dwReconstructor_predictFeaturePosition()

DW_API_PUBLIC dwStatus dwReconstructor_predictFeaturePosition	(	dwVector2f	d_predictedLocations[],
		uint32_t	cameraIdx,
		const dwTransformation3f *	previousRigToWorld,
		const dwTransformation3f *	predictedRigToWorld,
		const uint32_t *	d_featureCount,
		const dwFeature2DStatus	d_featureStatuses[],
		const dwVector2f	d_featureLocations[],
		const dwVector4f	d_worldPoints[],
		dwReconstructorHandle_t	obj
	)

Predicts the positions of features based on the predicted car motion.

If the feature has been triangulated, it reprojects it using the predicted pose. Else, if the feature is below the horizon, it uses the homography induced by the ground plane to predict the feature movement. If it is above the horizon and it has not been triangulated, the current location is copied as the prediction.

Parameters

[out]	d_predictedLocations	GPU buffer of dwVector2f. This is where the predicted locations are returned. The buffer must be at least d_featureCount long.
[in]	cameraIdx	Index of the camera.
[in]	previousRigToWorld	The position of the rig corresponding to the observations in d_featureLocations.
[in]	predictedRigToWorld	The predicted position of the rig corresponding to d_predictedLocations.
[in]	d_featureCount	GPU pointer to the number of features to predict.
[in]	d_featureStatuses	GPU array. Status of each feature. Non-active features are ignored.
[in]	d_featureLocations	GPU array of dwVector2f. The last observed feature locations. Must have d_featureCount valid entries.
[in]	d_worldPoints	GPU array of dwVector4f. The triangulated 3D positions of the features. If a triangulation is not available the 4th component should be zero. Must have d_featureCount valid entries.
[in]	obj	The reconstructor object handle.

◆ dwReconstructor_project()

DW_API_PUBLIC dwStatus dwReconstructor_project	(	dwVector2f *	d_locations[],
		const dwTransformation3f *	rig2World,
		const uint32_t *const	d_pointCount[],
		const dwVector4f *const	d_worldPoints[],
		dwReconstructorHandle_t	obj
	)

Projects triangulated features back to the image.

This can be used to predict locations for the feature tracker. Processes all cameras simultaneously.

Parameters

[out]	d_locations	A GPU pointer to the projection results.
[in]	rig2World	A pointer to the current position of the rig (vehicle).
[in]	d_pointCount	A GPU pointer to the number of points in each feature buffer.
[in]	d_worldPoints	A GPU pointer to the list of triangulated points.
[in]	obj	Specifies the reconstructor object handle.

◆ dwReconstructor_release()

DW_API_PUBLIC dwStatus dwReconstructor_release ( dwReconstructorHandle_t obj )

Releases a reconstructor.

This method releases all resources associated with a reconstructor.

Note: This method renders the handle unusable.

Parameters

[in] obj Specifies the object handle to release.

Returns: DW_SUCCESS
DW_INVALID_HANDLE - If the given context handle is invalid,i.e. null or of wrong type
DW_BAD_CAST

◆ dwReconstructor_reset()

DW_API_PUBLIC dwStatus dwReconstructor_reset ( dwReconstructorHandle_t obj )

Resets a reconstructor.

Parameters

[in] obj Specifies the reconstructor handle to reset.

Returns: DW_SUCCESS
DW_INVALID_HANDLE - If the given context handle is invalid,i.e. null or of wrong type
DW_BAD_CAST

◆ dwReconstructor_setCUDAStream()

DW_API_PUBLIC dwStatus dwReconstructor_setCUDAStream	(	cudaStream_t	stream,
		dwReconstructorHandle_t	obj
	)

Sets the CUDA stream for CUDA related operations.

Note: The ownership of the stream remains by the callee.

Parameters

[in]	stream	The CUDA stream to be used. Default is the one passed during dwReconstructor_initialize.
[in]	obj	A handle to the reconstructor module to set CUDA stream for.

Returns: DW_INVALID_HANDLE if the given context handle is invalid, i.e. null or of wrong type
or DW_SUCCESS otherwise.

◆ dwReconstructor_triangulateFeatures()

DW_API_PUBLIC dwStatus dwReconstructor_triangulateFeatures	(	dwVector4f *	d_worldPoints,
		dwFeature2DStatus *	d_statuses,
		const uint32_t *	d_featureCount,
		const uint32_t	cameraIdx,
		dwReconstructorHandle_t	obj
	)

Triangulates the features of a camera from the internal feature and pose history.

Processes only a single camera.

Parameters

[out]	d_worldPoints	A pointer to the list of triangulated points. This list must hold at least maxFeatureCount items. Pointer must be 16-byte aligned.
[out]	d_statuses	A pointer to the list of feature statuses. If the reprojection error is too high, a feature is marked here as invalid. Otherwise, the status is unchanged.
[in]	d_featureCount	A pointer to the number of tracked features. Pointer to GPU memory.
[in]	cameraIdx	Specifies the index of the camera in the rig that this call should triangulate for.
[in]	obj	Specifies the reconstructor object handle.

Returns: DW_SUCCESS
DW_INVALID_HANDLE - If the given context handle is invalid,i.e. null or of wrong type
DW_BAD_CAST
DW_INVALID_ARGUMENT

◆ dwReconstructor_updateHistory()

DW_API_PUBLIC dwStatus dwReconstructor_updateHistory	(	int32_t *	rig2WorldHistoryIdx,
		const dwTransformation3f *	rig2World,
		const uint32_t	listCount,
		const uint32_t *const	d_featureCounts[],
		const dwVector2f *const	d_trackedLocations[],
		dwReconstructorHandle_t	obj
	)

Updates the feature and pose history.

Pose history is updated if the vehicle moves or rotates enough. Feature history is updated if the tracked location provides new information for triangulation.

This method receives the features tracked by each camera in the rig. There must be one feature list per camera in the rig. Thus, listCount must be equal to the number of cameras in the rig.

Processes all cameras simultaneously.

Parameters

[out]	rig2WorldHistoryIdx	A pointer to the index of the rig's pose in the internal pose history list. -1 if it was not added to the history. You can pass NULL.
[in]	rig2World	A pointer to the current position of the rig (vehicle).
[in]	listCount	Specifies the number of feature lists provided in the following parameters. This must match the number of cameras in the rig.
[in]	d_featureCounts	A pointer to the number of tracked features. There is one feature count per feature list. Pointers to GPU memory.
[in]	d_trackedLocations	A pointer to the 2D position of the tracked features in the images. One list per camera in the rig. List i has listCount[i] elements. Pointer to GPU memory.
[in]	obj	Specifies the reconstructor object handle.

Returns: DW_SUCCESS, DW_INVALID_HANDLE, DW_BAD_CAST, DW_INVALID_ARGUMENT

Detailed Description

Data Structures

Typedefs

Functions

Data Structure Documentation

◆ dwReconstructorConfig

Typedef Documentation

◆ dwConstReconstructorHandle_t

◆ dwReconstructorHandle_t

Function Documentation

◆ dwReconstructor_compactFeatureHistory()

◆ dwReconstructor_compactWorldPoints()

◆ dwReconstructor_enableCamerasForPoseEstimation()

◆ dwReconstructor_estimatePoseAsync()

◆ dwReconstructor_getCUDAStream()

◆ dwReconstructor_getEstimatedPose()

◆ dwReconstructor_initConfig()

◆ dwReconstructor_initialize()

◆ dwReconstructor_predictFeaturePosition()

◆ dwReconstructor_project()

◆ dwReconstructor_release()

◆ dwReconstructor_reset()

◆ dwReconstructor_setCUDAStream()

◆ dwReconstructor_triangulateFeatures()

◆ dwReconstructor_updateHistory()