Match3D

Functions to calculate the distance and transformation between two point clouds. More...

Data Structures
struct	CVM3DMatchParameters
	Controls CVM3DMatchDownsampledPointClouds. More...

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

Detailed Description

Functions to calculate the distance and transformation between two point clouds.

Function Documentation

CVM3DMatchDownsampledPointClouds()

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

This function matches the PointCloudScene to PointCloudModel.

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]	PointCloudModel	First point cloud.
[in]	MaxModelPoints	Maximum number of model points to use.
[in]	PointCloudScene	Second point cloud to be matched to model.
[in]	MaxScenePoints	Maximum number of scene points to use.
[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 scene to the model.

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 scene to a model:

// 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
(
  hModel, 500, 
  hScene, 1000, 
  matchParameter, 
  finalRmsDistance, numIterationsNeeded, transformation
);
 
// test if result is ok and finalRmsDistance is close enough
 
CVCOMPOSITE hTransformedScene = nullptr;
CVC3DCreateTransformedPointCloud(hScene, transformation, hTransformedScene);
 
// now hModel and hTransformedScene are aligned
  
// free memory
ReleaseObject(hTransformedScene);
ReleaseObject(hScene);
ReleaseObject(hModel);

CVM3DMatchPointCloudsAdvanced()

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

This function matches the PointCloudScene to PointCloudModel.

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]	PointCloudModel	First point cloud.
[in]	MaxModelPoints	Maximum number of model points to use.
[in]	PointCloudScene	Second point cloud to be matched to model.
[in]	MaxScenePoints	Maximum number of scene points to use.
[in]	MatchParameter	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 scene to the model.

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 scene to a model:

// 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
(
  hModel, 500, 
  hScene, 1000, 
  matchParameter, 
  finalRmsDistance, numIterationsNeeded, transformation
);
 
// test if result is ok and finalRmsDistance is close enough
 
CVCOMPOSITE hTransformedScene = nullptr;
CVC3DCreateTransformedPointCloud(hScene, transformation, hTransformedScene);
 
// now hModel and hTransformedScene are aligned
  
// free memory
ReleaseObject(hTransformedScene);
ReleaseObject(hScene);
ReleaseObject(hModel);

CVM3DRmsDistanceOfPointClouds()

cvbres_t CVM3DRmsDistanceOfPointClouds	(	CVCOMPOSITE	PointCloudModel,
		CVCOMPOSITE	PointCloudScene,
		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 PointCloudScene is transformed from the PointCloudModel (rotation- and translation-wise).

Parameters

[in]	PointCloudModel	First point cloud.
[in]	PointCloudScene	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.