Detailed Description

Defines Point Cloud ICP module to align point clouds using iterative closest point algorithms.

Data Structures
struct	dwPointCloudICPParams
	Defines point cloud icp parameter. More...

struct	dwPointCloudICPResultStats
	Resulting statistics about the latest ICP run. More...

Typedefs
typedef bool(*	dwPointCloudICPConvergenceCheck) (const dwTransformation3f prevSrc2Tgt, const dwTransformation3f newSrc2Tgt, void *userData)
	Callback function to be executed by ICP module allowing user to overwrite default convergence criteria method. More...

typedef struct dwPointCloudICPObject *	dwPointCloudICPHandle_t

Enumerations
enum	dwPointCloudICPType { DW_POINT_CLOUD_ICP_TYPE_DEPTH_MAP }
	Defines a type of the Iterative Closest Point (ICP) algorithm. More...

Functions
DW_API_PUBLIC dwStatus	dwPointCloudICP_bindInput (const dwPointCloud sourcePCD, const dwPointCloud targetPCD, const dwTransformation3f *sourceToTarget, dwPointCloudICPHandle_t obj)
	Binds input buffers of a source and a target point clouds as well as a buffer with an initial transformation. More...

DW_API_PUBLIC dwStatus	dwPointCloudICP_bindOutput (dwTransformation3f *pose, dwPointCloudICPHandle_t obj)
	Binds an output buffer to the resulting transformation between a source and a target point clouds. More...

DW_API_PUBLIC dwStatus	dwPointCloudICP_getCUDAStream (cudaStream_t *stream, dwPointCloudICPHandle_t obj)
	Gets CUDA stream of point cloud icp. More...

DW_API_PUBLIC dwStatus	dwPointCloudICP_getDefaultParams (dwPointCloudICPParams *params)
	Gets default values of dwPointCloudICPParams object. More...

DW_API_PUBLIC dwStatus	dwPointCloudICP_getLastResultStats (dwPointCloudICPResultStats *resultStats, dwPointCloudICPHandle_t obj)
	Get statistics about latest point cloud ICP run, returns the costs for last pose (see a description of 'dwPointCloudICPResultStats' for details) More...

DW_API_PUBLIC dwStatus	dwPointCloudICP_getMaximumDepthMapSize (uint32_t *maxDepthMapSize)
	Get the maximum allowed size of the depth map in number of points supported by the ICP implementation. More...

DW_API_PUBLIC dwStatus	dwPointCloudICP_initialize (dwPointCloudICPHandle_t obj, const dwPointCloudICPParams params, dwContextHandle_t ctx)
	Initializes point cloud icp. More...

DW_API_PUBLIC dwStatus	dwPointCloudICP_process (dwPointCloudICPHandle_t obj)
	Estimates the transformation aligns two PointClouds. More...

DW_API_PUBLIC dwStatus	dwPointCloudICP_release (dwPointCloudICPHandle_t obj)
	Releases a handle of a point cloud icp created using 'dwPointCloudICP_initialize'. More...

DW_API_PUBLIC dwStatus	dwPointCloudICP_reset (dwPointCloudICPHandle_t obj)
	Resets pointers to the source, target point clouds and an output pose to a null pointer value. More...

DW_API_PUBLIC dwStatus	dwPointCloudICP_setConvergenceCriteriaCallback (dwPointCloudICPConvergenceCheck callback, void *userData, dwPointCloudICPHandle_t obj)
	Allows to set a user-defined callback to be executed for ICP convergence test. More...

DW_API_PUBLIC dwStatus	dwPointCloudICP_setConvergenceTolerance (float32_t angleTol, float32_t distanceTol, dwPointCloudICPHandle_t obj)
	Set tolerances used by the default ICP convergence criteria method. More...

DW_API_PUBLIC dwStatus	dwPointCloudICP_setCUDAStream (cudaStream_t const stream, dwPointCloudICPHandle_t obj)
	Sets CUDA stream of point cloud icp. More...

DW_API_PUBLIC dwStatus	dwPointCloudICP_setMaxIterations (uint16_t maxIterations, dwPointCloudICPHandle_t obj)
	Set maximum number of iterations which need to be executed. More...

Data Structure Documentation

◆ dwPointCloudICPParams

struct dwPointCloudICPParams

Data Fields
float32_t	angleConvergenceTol	Angle convergence tolerance, change in radians between two consecutive iteration steps.
dwVector2ui	depthmapSize	If icpType is DW_POINT_CLOUD_ICP_TYPE_DEPTH_MAP, this defines the size of depthmap.
float32_t	distanceConvergenceTol	Distance convergence tolerance, change in units between two consecutive iteration steps.
dwPointCloudICPType	icpType	Type of the ICP implementation to be used.
uint16_t	maxIterations	Maximum number of iterations which need to be executed.
uint32_t	maxPoints	Maximum number of points that will be pushed to ICP optimization.
bool	usePriors	Controls whether or not ICP uses the initialization pose as a prior in the optimization.

◆ dwPointCloudICPResultStats

struct dwPointCloudICPResultStats

Data Fields
uint16_t	actualNumIterations	How many iterations were actually performed.
float32_t	inlierFraction	Fraction of points which are inliers to the final ICP pose.
uint32_t	numCorrespondences	Number of 3D points which qualify as valid correspondences.
float32_t	rmsCost	Weighted root mean square (RMS) cost after last ICP iteration.

Typedef Documentation

◆ dwPointCloudICPConvergenceCheck

typedef bool(* dwPointCloudICPConvergenceCheck) (const dwTransformation3f *prevSrc2Tgt, const dwTransformation3f *newSrc2Tgt, void *userData)

Callback function to be executed by ICP module allowing user to overwrite default convergence criteria method.

The method will receive original and new transformations as computed by the ICP module

Definition at line 97 of file PointCloudICP.h.

◆ dwPointCloudICPHandle_t

typedef struct dwPointCloudICPObject* dwPointCloudICPHandle_t

Definition at line 56 of file PointCloudICP.h.

Enumeration Type Documentation

◆ dwPointCloudICPType

enum dwPointCloudICPType

Defines a type of the Iterative Closest Point (ICP) algorithm.

Enumerator

DW_POINT_CLOUD_ICP_TYPE_DEPTH_MAP

Grid based depthmap representation for the lidar point cloud.

It is assumed that the structured point cloud passed for alignment was generated from a spinning lidar

Definition at line 61 of file PointCloudICP.h.

Function Documentation

◆ dwPointCloudICP_bindInput()

DW_API_PUBLIC dwStatus dwPointCloudICP_bindInput	(	const dwPointCloud *	sourcePCD,
		const dwPointCloud *	targetPCD,
		const dwTransformation3f *	sourceToTarget,
		dwPointCloudICPHandle_t	obj
	)

Binds input buffers of a source and a target point clouds as well as a buffer with an initial transformation.

Parameters

[in]	sourcePCD	Pointer to source point cloud input buffer. Must be in cartesian coordinate space.
[in]	targetPCD	Pointer to target point cloud input buffer. Must be in cartesian coordinate space.
[in]	sourceToTarget	Pointer to the initial transformation that transforms from source to target point cloud
[in]	obj	Handle to point cloud icp

Return values

DW_INVALID_ARGUMENT	when at least one of input arguments is not valid
DW_INVALID_HANDLE	when handle to point cloud icp is not valid
DW_SUCCESS	when operation succeeded

◆ dwPointCloudICP_bindOutput()

DW_API_PUBLIC dwStatus dwPointCloudICP_bindOutput	(	dwTransformation3f *	pose,
		dwPointCloudICPHandle_t	obj
	)

Binds an output buffer to the resulting transformation between a source and a target point clouds.

Parameters

[out]	pose	Pointer to the transformation that aligns the source point cloud with target point cloud
[in]	obj	Handle to point cloud icp module

Return values

DW_INVALID_ARGUMENT	when handle to a transformation is not valid
DW_INVALID_HANDLE	when handle to point cloud icp is not valid
DW_SUCCESS	when operation succeeded

◆ dwPointCloudICP_getCUDAStream()

DW_API_PUBLIC dwStatus dwPointCloudICP_getCUDAStream	(	cudaStream_t *	stream,
		dwPointCloudICPHandle_t	obj
	)

Gets CUDA stream of point cloud icp.

Parameters

[out]	stream	Pointer to CUDA stream handle
[in]	obj	Handle to point cloud icp

Return values

DW_INVALID_HANDLE	when handle to point cloud icp is not valid
DW_INVALID_ARGUMENT	when handle a CUDA stream is not valid
DW_SUCCESS	when operation succeeded

◆ dwPointCloudICP_getDefaultParams()

DW_API_PUBLIC dwStatus dwPointCloudICP_getDefaultParams ( dwPointCloudICPParams * params )

Gets default values of dwPointCloudICPParams object.

Parameters

[out] params Pointer to point cloud icp parameters

Return values

DW_INVALID_ARGUMENT	when handle to icp parameters is not valid
DW_SUCCESS	when operation succeeded

◆ dwPointCloudICP_getLastResultStats()

DW_API_PUBLIC dwStatus dwPointCloudICP_getLastResultStats	(	dwPointCloudICPResultStats *	resultStats,
		dwPointCloudICPHandle_t	obj
	)

Get statistics about latest point cloud ICP run, returns the costs for last pose (see a description of 'dwPointCloudICPResultStats' for details)

Parameters

[out]	resultStats	Struct with stats about latest ICP run
[in]	obj	Handle to point cloud icp

Return values

DW_INVALID_HANDLE	when handle to point cloud icp is not valid
DW_INVALID_ARGUMENT	when handle to statistic results is not valid
DW_SUCCESS	when operation succeeded

◆ dwPointCloudICP_getMaximumDepthMapSize()

DW_API_PUBLIC dwStatus dwPointCloudICP_getMaximumDepthMapSize ( uint32_t * maxDepthMapSize )

Get the maximum allowed size of the depth map in number of points supported by the ICP implementation.

Width x height of the depth map has to be less than this number.

Parameters

[out] maxDepthMapSize - return maximal size in number of points supported by the ICP implementation.

Return values

DW_INVALID_HANDLE	when handle to point cloud icp is not valid
DW_SUCCESS	when operation succeeded

◆ dwPointCloudICP_initialize()

DW_API_PUBLIC dwStatus dwPointCloudICP_initialize	(	dwPointCloudICPHandle_t *	obj,
		const dwPointCloudICPParams *	params,
		dwContextHandle_t	ctx
	)

Initializes point cloud icp.

Parameters

[out]	obj	Handle to point cloud icp
[in]	params	Pointer to point cloud icp parameters
[in]	ctx	Handle to the context

Return values

DW_INVALID_ARGUMENT	when at least one of input arguments is not valid or an ICP type is not valid
DW_SUCCESS	when operation succeeded

◆ dwPointCloudICP_process()

DW_API_PUBLIC dwStatus dwPointCloudICP_process ( dwPointCloudICPHandle_t obj )

Estimates the transformation aligns two PointClouds.

Parameters

[in] obj Handle to point cloud icp

Return values

DW_INVALID_HANDLE	when handle to point cloud icp is not valid
DW_CALL_NOT_ALLOWED	- when input or output buffers are not bound
DW_SUCCESS	when operation succeeded

◆ dwPointCloudICP_release()

DW_API_PUBLIC dwStatus dwPointCloudICP_release ( dwPointCloudICPHandle_t obj )

Releases a handle of a point cloud icp created using 'dwPointCloudICP_initialize'.

Parameters

[in] obj Handle to point cloud icp

Return values

DW_INVALID_HANDLE	when handle to point cloud icp is not valid
DW_SUCCESS	when operation succeeded

◆ dwPointCloudICP_reset()

DW_API_PUBLIC dwStatus dwPointCloudICP_reset ( dwPointCloudICPHandle_t obj )

Resets pointers to the source, target point clouds and an output pose to a null pointer value.

Parameters

[in] obj Handle to point cloud icp

Return values

DW_INVALID_HANDLE	when handle to point cloud icp is not valid
DW_SUCCESS	when operation succeeded.

◆ dwPointCloudICP_setConvergenceCriteriaCallback()

DW_API_PUBLIC dwStatus dwPointCloudICP_setConvergenceCriteriaCallback	(	dwPointCloudICPConvergenceCheck	callback,
		void *	userData,
		dwPointCloudICPHandle_t	obj
	)

Allows to set a user-defined callback to be executed for ICP convergence test.

If nullptr, the default test will be used.

Parameters

[in]	callback	Method to execute to test for convergence
[in]	userData	User data to be passed to the convergence callback
[in]	obj	Handle to point cloud icp

Return values

DW_INVALID_HANDLE	when handle to point cloud icp is not valid
DW_SUCCESS	when operation succeeded

◆ dwPointCloudICP_setConvergenceTolerance()

DW_API_PUBLIC dwStatus dwPointCloudICP_setConvergenceTolerance	(	float32_t	angleTol,
		float32_t	distanceTol,
		dwPointCloudICPHandle_t	obj
	)

Set tolerances used by the default ICP convergence criteria method.

Parameters

[in]	angleTol	Change in angular parameters between two consecutive iteration steps, radians
[in]	distanceTol	Change in translation between two consecutive iteration steps, the same units as a source point cloud
[in]	obj	The initialized pointcloud ICP Module.

Return values

DW_INVALID_HANDLE	when handle to point cloud icp is not valid
DW_SUCCESS	when operation succeeded

Note: both tolerances has to be fulfilled, to declare convergence (i.e. it is a binary AND).

◆ dwPointCloudICP_setCUDAStream()

DW_API_PUBLIC dwStatus dwPointCloudICP_setCUDAStream	(	cudaStream_t const	stream,
		dwPointCloudICPHandle_t	obj
	)

Sets CUDA stream of point cloud icp.

Parameters

[in]	stream	Handle to CUDA stream
[in]	obj	Handle to point cloud icp

Return values

DW_INVALID_HANDLE	when handle to point cloud icp or a CUDA stream is not valid
DW_SUCCESS	when operation succeeded

◆ dwPointCloudICP_setMaxIterations()

DW_API_PUBLIC dwStatus dwPointCloudICP_setMaxIterations	(	uint16_t	maxIterations,
		dwPointCloudICPHandle_t	obj
	)

Set maximum number of iterations which need to be executed.

Note that ICP might converge earlier, due to the tolerances set in dwPointCloudICP_setConvergenceTolerance().

Parameters

[in]	maxIterations	Maximal number of iterations to execute.
[in]	obj	The initialized pointcloud ICP Module.

Return values

DW_INVALID_HANDLE	when handle to point cloud icp is not valid
DW_SUCCESS	when operation succeeded

Detailed Description

Data Structures

Typedefs

Enumerations

Functions

Data Structure Documentation

◆ dwPointCloudICPParams

◆ dwPointCloudICPResultStats

Typedef Documentation

◆ dwPointCloudICPConvergenceCheck

◆ dwPointCloudICPHandle_t

Enumeration Type Documentation

◆ dwPointCloudICPType

Function Documentation

◆ dwPointCloudICP_bindInput()

◆ dwPointCloudICP_bindOutput()

◆ dwPointCloudICP_getCUDAStream()

◆ dwPointCloudICP_getDefaultParams()

◆ dwPointCloudICP_getLastResultStats()

◆ dwPointCloudICP_getMaximumDepthMapSize()

◆ dwPointCloudICP_initialize()

◆ dwPointCloudICP_process()

◆ dwPointCloudICP_release()

◆ dwPointCloudICP_reset()

◆ dwPointCloudICP_setConvergenceCriteriaCallback()

◆ dwPointCloudICP_setConvergenceTolerance()

◆ dwPointCloudICP_setCUDAStream()

◆ dwPointCloudICP_setMaxIterations()