DriveWorks SDK Reference
3.5.78 Release
For Test and Development only

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 (const uint8_t 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 84 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 81 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]cameraIdxIndex of the camera to compact for.
[in]d_validIndexCountThe number of valid indexes in the list. GPU pointer.
[in]d_newToOldMapMapping array of compacted data to uncompacted sparse data. GPU pointer.
[in]objThe 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_worldPointsGPU array of 4-floats.
[in]d_validIndexCountThe number of valid indexes in the list. GPU pointer.
[in]d_newToOldMapMapping array of compacted data to uncompacted sparse data. GPU pointer.
[in]objThe reconstructor object handle.

◆ dwReconstructor_enableCamerasForPoseEstimation()

DW_API_PUBLIC dwStatus dwReconstructor_enableCamerasForPoseEstimation ( const uint8_t  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]enabledArray 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]objThe 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]previousRig2WorldA pointer to the position of the rig in the previous frame.
[in]predictedRig2WorldA pointer to the initial estimate of the rig's pose. The reconstructor refines this initial estimate based on the tracked features.
[in]listCountThe number of feature lists provided in the following parameters. This must match the number of cameras in the rig.
[in]d_statusesA pointer to the status of the tracked features. Features with an invalid status are ignored. Pointers to GPU memory.
[in]d_featureCountsA pointer to the number of tracked features. There is one feature count per feature list. Pointers to GPU memory.
[in]d_trackedLocationsA 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_worldPointsA 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]objThe 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]streamThe CUDA stream currently used
[in]objA 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]correctedRig2WorldThe corrected rig to world pose.
[in]objThe 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]configConfig 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]objA pointer to the reconstructor handle is returned here.
[in]configSpcifies the configuration parameters for the reconstructor.
[in]streamSpecifies the CUDA stream to use for all reconstructor operations.
[in]contextSpecifies 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_predictedLocationsGPU buffer of dwVector2f. This is where the predicted locations are returned. The buffer must be at least d_featureCount long.
[in]cameraIdxIndex of the camera.
[in]previousRigToWorldThe position of the rig corresponding to the observations in d_featureLocations.
[in]predictedRigToWorldThe predicted position of the rig corresponding to d_predictedLocations.
[in]d_featureCountGPU pointer to the number of features to predict.
[in]d_featureStatusesGPU array. Status of each feature. Non-active features are ignored.
[in]d_featureLocationsGPU array of dwVector2f. The last observed feature locations. Must have d_featureCount valid entries.
[in]d_worldPointsGPU 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]objThe 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_locationsA GPU pointer to the projection results.
[in]rig2WorldA pointer to the current position of the rig (vehicle).
[in]d_pointCountA GPU pointer to the number of points in each feature buffer.
[in]d_worldPointsA GPU pointer to the list of triangulated points.
[in]objSpecifies 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]objSpecifies 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]objSpecifies 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]streamThe CUDA stream to be used. Default is the one passed during dwReconstructor_initialize.
[in]objA 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_worldPointsA pointer to the list of triangulated points. This list must hold at least maxFeatureCount items. Pointer must be 16-byte aligned.
[out]d_statusesA 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_featureCountA pointer to the number of tracked features. Pointer to GPU memory.
[in]cameraIdxSpecifies the index of the camera in the rig that this call should triangulate for.
[in]objSpecifies 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]rig2WorldHistoryIdxA 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]rig2WorldA pointer to the current position of the rig (vehicle).
[in]listCountSpecifies the number of feature lists provided in the following parameters. This must match the number of cameras in the rig.
[in]d_featureCountsA pointer to the number of tracked features. There is one feature count per feature list. Pointers to GPU memory.
[in]d_trackedLocationsA 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]objSpecifies the reconstructor object handle.
Returns
DW_SUCCESS, DW_INVALID_HANDLE, DW_BAD_CAST, DW_INVALID_ARGUMENT