Match3D

Match3D ICP (alignment of two point clouds). More...

Data Structures
struct	CVM3DMatchExtendedParameters
	Controls CVM3DMatchPointCloudsAdvanced. More...
struct	CVM3DMatchParameters
	Controls CVM3DMatchDownsampledPointClouds. More...

Enumerations
enum	CVM3DCorrespondenceType { CVM3DCT_ClassicICP , CVM3DCT_ConsensICP , CVM3DCT_ConsensusICP }
	Correspondence type used for algorithm in CVM3DMatchPointCloudsAdvanced. More...

Functions
cvbres_t	CVM3DMatchDownsampledPointClouds (CVCOMPOSITE PointCloudScene, cvbint64_t MaxScenePoints, CVCOMPOSITE PointCloudModel, cvbint64_t MaxModelPoints, const CVM3DMatchParameters &MatchParameter, double &FinalRmsDistance, cvbval_t &NumIterationsNeeded, CVC3DTransformation &Transformation)
	This function matches PointCloudModel to PointCloudScene. More...
cvbres_t	CVM3DMatchPointCloudsAdvanced (CVCOMPOSITE PointCloudScene, cvbint64_t MaxScenePoints, CVCOMPOSITE PointCloudModel, cvbint64_t MaxModelPoints, const CVM3DMatchExtendedParameters &MatchParameters, double &FinalNorm, cvbval_t &NumIterationsNeeded, CVC3DTransformation &Transformation)
	This function matches PointCloudModel to PointCloudScene. More...
cvbres_t	CVM3DRmsDistanceOfPointClouds (CVCOMPOSITE PointCloudScene, CVCOMPOSITE PointCloudModel, double &RmsDistance)
	This function approximates the root mean square of distances between PointCloudModel and PointCloudScene. More...

Detailed Description

Match3D ICP (alignment of two point clouds).

This library allows the alignment of two 3D point clouds. The alignment is based on the iterative closest point(ICP) algorithm.

Enumeration Type Documentation

CVM3DCorrespondenceType

enum CVM3DCorrespondenceType

Correspondence type used for algorithm in CVM3DMatchPointCloudsAdvanced.

Enumerator
CVM3DCT_ClassicICP	Classic ICP following Arun, 1987.
CVM3DCT_ConsensusICP	Extended ICP taking shape correspondence into consideration.

Function Documentation

CVM3DMatchDownsampledPointClouds()

cvbres_t CVM3DMatchDownsampledPointClouds	(	CVCOMPOSITE	PointCloudScene,
		cvbint64_t	MaxScenePoints,
		CVCOMPOSITE	PointCloudModel,
		cvbint64_t	MaxModelPoints,
		const CVM3DMatchParameters &	MatchParameter,
		double &	FinalRmsDistance,
		cvbval_t &	NumIterationsNeeded,
		CVC3DTransformation &	Transformation
	)

This function matches PointCloudModel to PointCloudScene.

If MaxModelPoints and/or MaxScenePoints points are lower than the actual number of points in the model/scene point cloud, the point clouds are downsampled by randomly removing points.

Note

This function matches two point clouds by the iterative closest point algorithm (ICP), see: The algorithm follows Arun KS, Huang TS, Blostein SD(1987) Least-squares fitting of two 3D point sets. IEEE Trans Pattern Anal Machine Intell 9:698–700.

Parameters

[in]	PointCloudScene	Scene point cloud.
[in]	MaxScenePoints	Maximum number of scene points to use. If zero, all points will be used.
[in]	PointCloudModel	Model point cloud to be matched to scene.
[in]	MaxModelPoints	Maximum number of model points to use. If zero, all points will be used.
[in]	MatchParameter	Parameters that control the algorithm.
[out]	FinalRmsDistance	Final root mean square of distances between model and scene.
[out]	NumIterationsNeeded	Number of iterations needed.
[out]	Transformation	Affine transformation (rotation matrix and translation vector) which maps the model to the scene.

Returns

• CVC_ERROR (CVC_E_OK) on success
• CVC_ERROR (CVC_E_WRONGOBJECT) if PointCloudModel or PointCloudScene are not a valid point cloud IComposite.
• CVC_ERROR (CVC_E_NOTENOUGHDATA) if any resulting point cloud (e.g. due to max points parameter) has fewer than 4 points.
• CVC_ERROR (CVC_E_MEMORY) if an allocation failed.

See also

CVM3DRmsDistanceOfPointClouds, CVC3DCreateTransformedPointCloud (CVCore3D library).

Example to align a model to a scene:

// load point cloud from ply-file
CVCOMPOSITE hModel = nullptr;
CVC3DLoadFile("Model.ply", CVC3DPCF_DTFloat | CVC3DPCF_XYZ, hModel);  
CVCOMPOSITE hScene = nullptr;
CVC3DLoadFile("Scene.ply", CVC3DPCF_DTFloat | CVC3DPCF_XYZ, hScene);  
  
// input parameter
CVM3DMatchParameters matchParameter = CVM3DDefaultParameters;
matchParameter.MaxIterations     = 20;
matchParameter.DeltaRmsThreshold = 1e-4;
matchParameter.MaxDistanceStdDev = 1;
  
// output parameter
double finalRmsDistance = 0.0;
cvbval_t numIterationsNeeded = -1;
CVC3DTransformation transformation = { 0 };
  
// match point clouds
cvbres_t result = CVM3DMatchDownsampledPointClouds
(
  hScene, 1000, 
  hModel, 500, 
  matchParameter, 
  finalRmsDistance, numIterationsNeeded, transformation
);
 
// test if result is ok and finalRmsDistance is close enough
 
CVCOMPOSITE hTransformedModel = nullptr;
CVC3DCreateTransformedPointCloud(hModel, transformation, hTransformedModel);
 
// now hScene and hTransformedModel are aligned
  
// free memory
ReleaseObject(hTransformedModel);
ReleaseObject(hScene);
ReleaseObject(hModel);

CVM3DMatchPointCloudsAdvanced()

cvbres_t CVM3DMatchPointCloudsAdvanced	(	CVCOMPOSITE	PointCloudScene,
		cvbint64_t	MaxScenePoints,
		CVCOMPOSITE	PointCloudModel,
		cvbint64_t	MaxModelPoints,
		const CVM3DMatchExtendedParameters &	MatchParameters,
		double &	FinalNorm,
		cvbval_t &	NumIterationsNeeded,
		CVC3DTransformation &	Transformation
	)

This function matches PointCloudModel to PointCloudScene.

If MaxModelPoints and/or MaxScenePoints points are lower than the actual number of points in the model/scene point cloud, the point clouds are downsampled by randomly removing points.

Note

This function matches two point clouds by an extended iterative closest point algorithm (ICP). This method does take shape correspondence into consideration. The parameter CorrespondenceThreshold in MatchParameters controls this behaviour. A value of 0 will result in the classical ICP method.

Parameters

[in]	PointCloudScene	Scene point cloud.
[in]	MaxScenePoints	Maximum number of scene points to use. If zero, all points will be used.
[in]	PointCloudModel	Model point cloud to be matched to scene.
[in]	MaxModelPoints	Maximum number of model points to use. If zero, all points will be used.
[in]	MatchParameters	Parameters that control the algorithm.
[out]	FinalNorm	Normed distance when the matching ended
[out]	NumIterationsNeeded	Number of iterations needed.
[out]	Transformation	Affine transformation (rotation matrix and translation vector) which maps the model to the scene.

Returns

• CVC_ERROR (CVC_E_OK) on success
• CVC_ERROR (CVC_E_WRONGOBJECT) if PointCloudModel or PointCloudScene are not a valid point cloud IComposite.
• CVC_ERROR (CVC_E_NOTENOUGHDATA) if any resulting point cloud (e.g. due to max points parameter) has fewer than 4 points.
• CVC_ERROR (CVC_E_MEMORY) if an allocation failed.

See also

CVM3DRmsDistanceOfPointClouds, CVC3DCreateTransformedPointCloud (CVCore3D library).

Example to align a model to a scene:

// load point cloud from ply-file
CVCOMPOSITE hModel = nullptr;
CVC3DLoadFile("Model.ply", CVC3DPCF_DTFloat | CVC3DPCF_XYZ, hModel);  
CVCOMPOSITE hScene = nullptr;
CVC3DLoadFile("Scene.ply", CVC3DPCF_DTFloat | CVC3DPCF_XYZ, hScene);  
  
// input parameter
CVM3DMatchParameters matchParameter = CVM3DExtendedDefaultParameters;
matchParameter.MaxIterations = 20;
matchParameter.Tolerance = 1e-9;
matchParameter.MinImprovement = 1e-5;
matchParameter.CorrespondenceThreshold = .8;
matchParameter.ConvergenceRadius = 1e-4;
  
// output parameter
double finalRmsDistance = 0.0;
cvbval_t numIterationsNeeded = -1;
CVC3DTransformation transformation = { 0 };
  
// match point clouds
cvbres_t result = CVM3DMatchPointCloudsAdvanced
(
  hScene, 1000, 
  hModel, 500, 
  matchParameter, 
  finalRmsDistance, numIterationsNeeded, transformation
);
 
// test if result is ok and finalRmsDistance is close enough
 
CVCOMPOSITE hTransformedModel = nullptr;
CVC3DCreateTransformedPointCloud(hModel, transformation, hTransformedModel);
 
// now hScene and hTransformedModel are aligned
  
// free memory
ReleaseObject(hTransformedModel);
ReleaseObject(hScene);
ReleaseObject(hModel);

CVM3DRmsDistanceOfPointClouds()

cvbres_t CVM3DRmsDistanceOfPointClouds	(	CVCOMPOSITE	PointCloudScene,
		CVCOMPOSITE	PointCloudModel,
		double &	RmsDistance
	)

This function approximates the root mean square of distances between PointCloudModel and PointCloudScene.

Matches the points from PointCloudModel to PointCloudScene via nearest neighbor search using the __L__2 norm.

Note

The resulting RmsDistance becomes more unreliable the further the PointCloudModel is transformed from the PointCloudScene (rotation- and translation-wise).

Parameters

[in]	PointCloudScene	First point cloud.
[in]	PointCloudModel	Second point cloud.
[out]	RmsDistance	Variable to receive the RMS of distances.

Returns

• CVC_ERROR (CVC_E_OK) on success
• CVC_ERROR (CVC_E_WRONGOBJECT) if PointCloudModel or PointCloudScene are not a valid point cloud IComposite.
• CVC_ERROR (CVC_E_NOTENOUGHDATA) if any point cloud is empty.
• CVC_ERROR (CVC_E_MEMORY) if an allocation failed.