3D Calibration

Calibration for 2½D and 3D data. More...

Modules
	1) Configuration of AQS12 Segmentor
	Functions to configure the AQS12 Segmentor object.
	2) AQS12 Segmentation and Point Extraction
	Functions to segment the faces of the AQS12 and to extract intersection points.
	3) Configuration of Calibration
	Functions to configure calibration configuration object.

Enumerations
enum	CVMExtrinsicTransformationModel { CVMETM_None = 0 , CVMETM_AffineTransformation = 1 , CVMETM_SpecificTransformationParameters = 2 }
	Model for estimation of extrinsic transformation. More...
enum	CVMIntrinsicCorrectionModel { CVMICM_XZHomography = 1 }
	Contains the possible intrinsic calibration correction models. This enumeration is only used by deprecated functions. More...

Functions
cvbres_t	CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPiece (CVCOMPOSITE DenseCloud, CVMAQS12SEGMENTOR3D Segmentor, CVMAQS12CALCONFIG CalConfig, CVC3DTransformation &TransformationLaserPlaneInclination, CVC3DPointD Residuals[12])
	Calculates the affine transformation TransformationLaserPlaneInclination from the given DenseCloud of an AQS12 calibration piece. This transformation corrects errors induced by an inclined laser plane. More...
cvbres_t	CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPieceRect (CVCOMPOSITE DenseCloud, cvbdim_t Left, cvbdim_t Top, cvbdim_t Right, cvbdim_t Bottom, CVMAQS12SEGMENTOR3D Segmentor, CVMAQS12CALCONFIG CalConfig, CVC3DTransformation &TransformationLaserPlaneInclination, CVC3DPointD Residuals[12])
	Calculates the affine transformation TransformationLaserPlaneInclination from the given DenseCloud of an AQS12 calibration piece. This transformation corrects errors induced by an inclined laser plane. More...
cvbres_t	CVMAQS12CalculateCorrectionOfLaserPlaneInclinationWithParamsFromPiece (CVCOMPOSITE DenseCloud, CVMAQS12SEGMENTOR3D Segmentor, CVMAQS12CALCONFIG CalConfig, CVC3DTransformation &TransformationLaserPlaneInclination, CVC3DAffineTransformationParameters &TransformationParameters, CVC3DPointD Residuals[12])
	Calculates the affine transformation TransformationLaserPlaneInclination from the given DenseCloud of an AQS12 calibration piece. This transformation corrects errors induced by an inclined laser plane. More...
cvbres_t	CVMAQS12CalculateCorrectionOfLaserPlaneInclinationWithParamsFromPieceRect (CVCOMPOSITE DenseCloud, cvbdim_t Left, cvbdim_t Top, cvbdim_t Right, cvbdim_t Bottom, CVMAQS12SEGMENTOR3D Segmentor, CVMAQS12CALCONFIG CalConfig, CVC3DTransformation &TransformationLaserPlaneInclination, CVC3DAffineTransformationParameters &TransformationParameters, CVC3DPointD Residuals[12])
	Calculates the affine transformation TransformationLaserPlaneInclination from the given DenseCloud of an AQS12 calibration piece. This transformation corrects errors induced by an inclined laser plane. More...
cvbres_t	CVMAQS12CalculateExtrinsicMatrix (IMG RangeMapImage, cvbdim_t PlaneIndex, CVC3DCALIBRATOR Calibrator, const CVC3DPointD Points[12], double TopBasePlaneDistance, CVC3DTransformation &ExtrinsicTransformation, CVC3DPointD Residuals[12])
	Calculates the ExtrinsicTransformation from the given RangeMapImage of an AQS12 calibration piece. More...
cvbres_t	CVMAQS12CalculateExtrinsicMatrixRect (IMG RangeMapImage, cvbdim_t PlaneIndex, cvbdim_t Left, cvbdim_t Top, cvbdim_t Right, cvbdim_t Bottom, CVC3DCALIBRATOR Calibrator, const CVC3DPointD Points[12], double TopBasePlaneDistance, CVC3DTransformation &ExtrinsicTransformation, CVC3DPointD Residuals[12])
	Calculates the ExtrinsicTransformation from the given RangeMapImage of an AQS12 calibration piece. More...
cvbres_t	CVMAQS12CalculateRigidBodyTransformationFromPiece (CVCOMPOSITE DenseCloud, CVMAQS12SEGMENTOR3D Segmentor, const CVC3DPointD Points[12], double TopBasePlaneDistance, CVC3DTransformation &ExtrinsicTransformation, CVC3DPointD Residuals[12])
	Calculates the rigid body transformation (rotation matrix and translation) from the given DenseCloud of an AQS12 calibration piece.The transformation is estimated by the Nelder-Mead method. The rigid body transformation is part of the extrinsic calibration. More...
cvbres_t	CVMAQS12CalculateRigidBodyTransformationFromPieceRect (CVCOMPOSITE DenseCloud, cvbdim_t Left, cvbdim_t Top, cvbdim_t Right, cvbdim_t Bottom, CVMAQS12SEGMENTOR3D Segmentor, const CVC3DPointD Points[12], double TopBasePlaneDistance, CVC3DTransformation &ExtrinsicTransformation, CVC3DPointD Residuals[12])
	Calculates the rigid body transformation (rotation matrix and translation) from the given DenseCloud of an AQS12 calibration piece. The transformation is estimated by the Nelder-Mead method. The rigid body transformation is part of the extrinsic calibration. More...
cvbres_t	CVMAQS12CalculateRigidBodyTransformationWithParamsFromPiece (CVCOMPOSITE DenseCloud, CVMAQS12SEGMENTOR3D Segmentor, const CVC3DPointD Points[12], double TopBasePlaneDistance, CVC3DTransformation &ExtrinsicTransformation, CVC3DAffineTransformationParameters &TransformationParameters, CVC3DPointD Residuals[12])
	Calculates the rigid body transformation (rotation matrix and translation) from the given DenseCloud of an AQS12 calibration piece.The transformation is estimated by the Nelder-Mead method. The rigid body transformation is part of the extrinsic calibration. More...
cvbres_t	CVMAQS12CalculateRigidBodyTransformationWithParamsFromPieceRect (CVCOMPOSITE DenseCloud, cvbdim_t Left, cvbdim_t Top, cvbdim_t Right, cvbdim_t Bottom, CVMAQS12SEGMENTOR3D Segmentor, const CVC3DPointD Points[12], double TopBasePlaneDistance, CVC3DTransformation &ExtrinsicTransformation, CVC3DAffineTransformationParameters &TransformationParameters, CVC3DPointD Residuals[12])
	Calculates the rigid body transformation (rotation matrix and translation) from the given DenseCloud of an AQS12 calibration piece. The transformation is estimated by the Nelder-Mead method. The rigid body transformation is part of the extrinsic calibration. More...
cvbres_t	CVMAQS12CreateCalibrator (IMG RangeMapImage, cvbdim_t PlaneIndex, const CVC3DPointD Points[12], double TopBasePlaneDistance, CVMIntrinsicCorrectionModel Model, CVC3DCALIBRATOR &Calibrator, CVC3DPointD Residuals[12])
	Creates an intrinsic/extrinsic Calibrator from the given RangeMapImage of an AQS12 calibration piece. More...
cvbres_t	CVMAQS12CreateCalibratorRect (IMG RangeMapImage, cvbdim_t PlaneIndex, cvbdim_t Left, cvbdim_t Top, cvbdim_t Right, cvbdim_t Bottom, const CVC3DPointD Points[12], double TopBasePlaneDistance, CVMIntrinsicCorrectionModel Model, CVC3DCALIBRATOR &Calibrator, CVC3DPointD Residuals[12])
	Creates an intrinsic/extrinsic Calibrator from the given RangeMapImage of an AQS12 calibration piece. More...
cvbres_t	CVMAQS12CreateFaceSegmentationImage (IMG RangeMapImage, cvbdim_t PlaneIndex, IMG &LabelImage)
	Segments the given RangeMapImage into the different faces of the AQS12 calibration piece. More...
cvbres_t	CVMAQS12CreateFaceSegmentationImageRect (IMG RangeMapImage, cvbdim_t PlaneIndex, cvbdim_t Left, cvbdim_t Top, cvbdim_t Right, cvbdim_t Bottom, IMG &LabelImage)
	Segments the given RangeMapImage into the different faces of the AQS12 calibration piece. More...
cvbres_t	CVMAQS12CreateIntrinsicCalibratorFromPiece (IMG RangeMapImage, cvbdim_t PlaneIndex, CVMAQS12SEGMENTOR2D Segmentor, CVMAQS12CALCONFIG CalConfig, CVC3DCALIBRATOR &Calibrator, CVC3DPointD Residuals[12])
	Creates an intrinsic Calibrator from the given RangeMapImage of an AQS12 calibration piece. More...
cvbres_t	CVMAQS12CreateIntrinsicCalibratorFromPieceRect (IMG RangeMapImage, cvbdim_t PlaneIndex, cvbdim_t Left, cvbdim_t Top, cvbdim_t Right, cvbdim_t Bottom, CVMAQS12SEGMENTOR2D Segmentor, CVMAQS12CALCONFIG CalConfig, CVC3DCALIBRATOR &Calibrator, CVC3DPointD Residuals[12])
	Creates an intrinsic Calibrator from the given RangeMapImage of an AQS12 calibration piece. More...
cvbres_t	CVMCalculateAffineTransformation (const CVC3DPointD *ReferencePoints, const CVC3DPointD *MeasuredPoints, cvbdim_t PointsLength, CVC3DTransformation &Transformation)
	Calculates an affine transformation from given reference points (which are assumed to be correct) and measured points. The transformation is calculated by a singular value decomposition. More...
cvbres_t	CVMCalculateCorrectionOfLaserPlaneInclinationWithParams (const CVC3DPointD *ReferencePoints, const CVC3DPointD *MeasuredPoints, cvbdim_t PointsLength, CVMExtrinsicTransformationModel Model, cvbbool_t CalculateEncoderStep, CVC3DTransformation &Transformation, CVC3DAffineTransformationParameters &TransformationParameters, CVC3DPointD *Residuals)
	Calculates an affine transformation (correcting the inclination of the laser plane) from given reference points and measured points. More...
cvbres_t	CVMCalculateRigidBodyTransformation (const CVC3DPointD *ReferencePoints, const CVC3DPointD *MeasuredPoints, cvbdim_t PointsLength, CVC3DTransformation &Transformation)
	Calculates a rigid body transformation (rotation matrix and translation) from given reference points (which are assumed to be correct) and measured points. The transformation is estimated by the Nelder-Mead method. More...
cvbres_t	CVMCalculateRigidBodyTransformationWithParams (const CVC3DPointD *ReferencePoints, const CVC3DPointD *MeasuredPoints, cvbdim_t PointsLength, CVC3DTransformation &Transformation, CVC3DAffineTransformationParameters &TransformationParameters, CVC3DPointD *Residuals)
	Calculates a rigid body transformation (rotation matrix and translation) from given reference points (which are assumed to be correct) and measured points. The transformation is estimated by the Nelder-Mead method. More...
cvbres_t	CVMFindSpheres (CVCOMPOSITE DenseCloud, double radius, double sensitivity, TSphere *spheres, int &numspheres, int maxnumspheres)
	Detect spheres of a given radius in dense point clouds. More...
cvbres_t	CVMWrite3DCalibrator (CVC3DCALIBRATOR Calibrator, const char *FileName)
	Writes a 3D calibration file (ASCII string version). More...
cvbres_t	CVMWrite3DCalibratorW (CVC3DCALIBRATOR Calibrator, const wchar_t *FileName)
	Writes a 3D calibration file (Unicode string version). More...

Detailed Description

Calibration for 2½D and 3D data.

Calibration defines and functions.

Enumeration Type Documentation

CVMExtrinsicTransformationModel

enum CVMExtrinsicTransformationModel

Model for estimation of extrinsic transformation.

Enumerator
CVMETM_None	Extrinsic transformation will not be estimated.
CVMETM_AffineTransformation	Elements of affine matrix m11,..., m33 are estimated.
CVMETM_SpecificTransformationParameters	Transformation parameters like rotation, scale and shear are estimated (recommended). Note: When using this model, you can enable or disable the estimation of the encoder step, i.e. scale in Y via function CVMAQS12CalConfigSetCalculateEncoderStep.

CVMIntrinsicCorrectionModel

enum CVMIntrinsicCorrectionModel

Contains the possible intrinsic calibration correction models. This enumeration is only used by deprecated functions.

Enumerator
CVMICM_XZHomography	Pin hole camera homography transformation for range maps acquired by a laser triangulation camera. In case of laser plane calibration (e.g. in CVMAQS12CreateCalibrator) a 3x3 homogeneous matrix is created that is applied to the x and z components only. The y coordinate must be adjusted via extrinsic calibration as this depends on the acquisition speed.

Function Documentation

CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPiece()

cvbres_t CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPiece	(	CVCOMPOSITE	DenseCloud,
		CVMAQS12SEGMENTOR3D	Segmentor,
		CVMAQS12CALCONFIG	CalConfig,
		CVC3DTransformation &	TransformationLaserPlaneInclination,
		CVC3DPointD	Residuals[12]
	)

Calculates the affine transformation TransformationLaserPlaneInclination from the given DenseCloud of an AQS12 calibration piece. This transformation corrects errors induced by an inclined laser plane.

This is the full image variant of CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPieceRect. Detailed information can be found there.

Parameters

[in]	DenseCloud	Handle of dense point cloud.
[in]	Segmentor	Segmentor created by the function CVMAQS12CreateSegmentorForDensePointCloud.
[in]	CalConfig	Calibration configuration created by the function CVMAQS12CreateInstrinsicCalConfig.
[out]	TransformationLaserPlaneInclination	Variable to receive the affine transformation, which corrects erros induced by an inclined laser plane.
[out]	Residuals	Optional pointer to 12 point array to contain the residuals; nullptr if not needed.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_PARAMETER) if Points is nullptr or TopBasePlaneDistance is invalid.
• CVC_ERROR(CVC_E_WRONGOBJECT) if DenseCloud or Segmentor is invalid or DenseCloud is not dense.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if calibration piece could not be located properly.
• CVC_ERROR(CVC_E_MEMORY) if not enough memory was available intermediate processing.

See also

CVMAQS12CreateIntrinsicCalibratorFromPiece, CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPieceRect, CVMAQS12CreateSegmentorForDensePointCloud, CVC3DCalibratorSetCorrectionOfLaserPlaneInclination, CVMCalculateAffineTransformation

CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPieceRect()

cvbres_t CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPieceRect	(	CVCOMPOSITE	DenseCloud,
		cvbdim_t	Left,
		cvbdim_t	Top,
		cvbdim_t	Right,
		cvbdim_t	Bottom,
		CVMAQS12SEGMENTOR3D	Segmentor,
		CVMAQS12CALCONFIG	CalConfig,
		CVC3DTransformation &	TransformationLaserPlaneInclination,
		CVC3DPointD	Residuals[12]
	)

Calculates the affine transformation TransformationLaserPlaneInclination from the given DenseCloud of an AQS12 calibration piece. This transformation corrects errors induced by an inclined laser plane.

Note

In this function, the area of interest is selected from the xy plane of a dense point cloud. So this function does not work with sparse point clouds. For sparse point clouds crop the desired area first and then use function CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPiece.

This function expects a point cloud showing the AQS12 calibration piece in the following orientation:

The LabelImage will have the same dimension as RangeMapImage and a cvbdatatype_t of 8 (Mono 8bpp).

Label	Value	Comment
Ignore	0	not part of calibration piece
Base	1	part of the base plane.
Top face	2	part of the top face.
Face 0°	3	part of 0° face (right)
Face 40°	4	part of 40° face (right/down)
Face 140°	5	part of 140° face (left/down)
Face 180°	6	part of 180° face (left)
Face 220°	7	part of 220° face (left/top)
Face 320°	8	part of 320° face (right/top)

Attention

The following constraints for the point cloud have to be met:

• The point cloud must be dense.
• The AQS12 may not be tilted. The xy plane must be parallel to the base plane of the AQS12.
• Disturbing background must be eliminated by setting these points to non-confident. You can create a calibrated dense point cloud with function CVC3DCreateCalibratedPointCloudFromRangeMap. Before creating the cloud, set the range map ignore value with function CVC3DCalibratorSetRangeMapIgnoreValue. All pixels with this value will be interpreted as non-confident.

Note

The region of interest must be selected on the grid of the dense point cloud. Left, top, right and bottom are indices for row and column.

If the CVMETM_SpecificTransformationParameters model is specified in the calibration configuration object CalConfig, it is recommended to use function CVMAQS12CalculateCorrectionOfLaserPlaneInclinationWithParamsFromPieceRect instead. This function returns additionally the tranformation parameters.

Parameters

[in]	DenseCloud	Handle of dense point cloud.
[in]	Left	First column for region of interest in dense cloud.
[in]	Top	First row for region of interest in dense cloud.
[in]	Right	Last column for region of interest in dense cloud (inclusive).
[in]	Bottom	Last row for region of interest in dense cloud (inclusive).
[in]	Segmentor	Segmentor created by the function CVMAQS12CreateSegmentorForDensePointCloud.
[in]	CalConfig	Calibration configuration created by the function CVMAQS12CreateInstrinsicCalConfig.
[out]	TransformationLaserPlaneInclination	Variable to receive the affine transformation, which corrects erros induced by an inclined laser plane.
[out]	Residuals	Optional pointer to 12 point array to contain the residuals; nullptr if not needed.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_PARAMETER) if Points is nullptr or TopBasePlaneDistance or aoi is invalid.
• CVC_ERROR(CVC_E_WRONGOBJECT) if DenseCloud or Segmentor is invalid or DenseCloud is not dense.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if calibration piece could not be located properly.
• CVC_ERROR(CVC_E_MEMORY) if not enough memory was available intermediate processing.

See also

CVMAQS12CreateIntrinsicCalibratorFromPiece, CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPiece, CVMAQS12CreateSegmentorForDensePointCloud, CVC3DCalibratorSetCorrectionOfLaserPlaneInclination, CVMCalculateAffineTransformation

Example

The following C++11 code shows how to calculate the correction of the laser plane inclination.

#include <iostream>
#include <memory>
#include <vector>
 
#include "iCVCUtilities.h"
#include "CVCError.h"
#include "iCVMetric.h"
 
using ObjPtr = std::unique_ptr<void, void(*)(OBJ)>;
ObjPtr CreateObjPtr(OBJ handle)
{
  return ObjPtr(handle, [](OBJ pObj) { ReleaseObject(pObj); });
}
 
int main()
{
  // reference points
  static const constexpr CVC3DPointD ReferencePoints[12] =
  {
    {   0,  40,     60 },
    {  10,  53.333, 60 },
    {  10,  96.667, 60 },
    {   0, 110,     60 },
    { -10,  96.667, 60 },
    { -10,  53.333, 60 },
    {   0,   0,     30 },
    {  30,  40,     30 },
    {  30, 110,     30 },
    {   0, 150,     30 },
    { -30, 110,     30 },
    { -30,  40,     30 },
  };
  static const constexpr double ReferenceTopBasePlaneDistance = 60;
 
  // load range map of AQS12
  std::vector<wchar_t> path(260);
  GetCVBDirectoryW(path.data(), path.size());
  auto rgFile = std::wstring(path.data()) + std::wstring(L"Tutorial/Metric/Images/RangeMap_CalibrationPattern.tif");
  IMG rangeMap = nullptr;
  if (!LoadImageFileT(rgFile.c_str(), rangeMap))
    return CVC_ERROR(CVC_E_ERROR);
  auto pRangeMap = CreateObjPtr(rangeMap);
 
  // load calibration parameter
  CVC3DCALIBRATOR calib = nullptr;
  auto calFile = std::wstring(path.data()) + std::wstring(L"Tutorial/Metric/Images/SI_Calibration.json");
  if (auto error = CVC3DLoadCalibratorW(calFile.c_str(), calib))
    return error;
  auto pCalib = CreateObjPtr(calib);
 
  // create calibrated point cloud
  CVCOMPOSITE cloud = nullptr;
  if (auto error = CVC3DCreateCalibratedPointCloudFromRangeMap(rangeMap, calib, CVC3DPCF_XYZConfidence |
  CVC3DPCF_DTDouble | CVC3DPCF_NoExtrinsic, cloud))
    return error;
  auto pCloud = CreateObjPtr(cloud);
 
  // create calibration configuration object
  CVMAQS12CALCONFIG config = nullptr;
  if (auto error = CVMAQS12CreateInstrinsicCalConfig(ReferencePoints, ReferenceTopBasePlaneDistance, config))
    return error;
  if (auto error = CVMAQS12CalConfigSetCalculateHomography(config, false))
    return error;
  auto pConfig = CreateObjPtr(config);
 
  // create AQS12 segmentor for dense point clouds
  CVMAQS12SEGMENTOR3D segmentor = nullptr;
  if (auto error = CVMAQS12CreateSegmentorForDensePointCloud(CVMAQS12SegmentationMethod::CVMSM_KmeansClustering,
  segmentor))
    return error;
  auto pSegmentor = CreateObjPtr(segmentor);
 
  // estimate correction of laser plane inclination (affine transformation)
  CVC3DPointD residuals[12] = { 0 };
  CVC3DTransformation affineTrafo = { 0 };
  if (auto error = CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPiece(cloud, segmentor, config,
  affineTrafo, residuals))
    return error;
 
  // save affine transformation to calibrator object
  if (auto error = CVC3DCalibratorSetCorrectionOfLaserPlaneInclination(calib, affineTrafo))
    return error;
 
  return CVC_ERROR(CVC_E_OK);
}

CVMAQS12CalculateCorrectionOfLaserPlaneInclinationWithParamsFromPiece()

cvbres_t CVMAQS12CalculateCorrectionOfLaserPlaneInclinationWithParamsFromPiece	(	CVCOMPOSITE	DenseCloud,
		CVMAQS12SEGMENTOR3D	Segmentor,
		CVMAQS12CALCONFIG	CalConfig,
		CVC3DTransformation &	TransformationLaserPlaneInclination,
		CVC3DAffineTransformationParameters &	TransformationParameters,
		CVC3DPointD	Residuals[12]
	)

Calculates the affine transformation TransformationLaserPlaneInclination from the given DenseCloud of an AQS12 calibration piece. This transformation corrects errors induced by an inclined laser plane.

This is the full image variant of CVMAQS12CalculateCorrectionOfLaserPlaneInclinationWithParamsFromPieceRect. Detailed information can be found there.

Parameters

[in]	DenseCloud	Handle of dense point cloud.
[in]	Segmentor	Segmentor created by the function CVMAQS12CreateSegmentorForDensePointCloud.
[in]	CalConfig	Calibration configuration created by the function CVMAQS12CreateInstrinsicCalConfig.
[out]	TransformationLaserPlaneInclination	Variable to receive the affine transformation, which corrects erros induced by an inclined laser plane. If CVMETM_AffineTransformation model is specified, the struct contains solely NaNs.
[out]	TransformationParameters	Variable to receive the transformation parameters.
[out]	Residuals	Optional pointer to 12 point array to contain the residuals; nullptr if not needed.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_PARAMETER) if Points is nullptr, TopBasePlaneDistance or calbration configuration is invalid.
• CVC_ERROR(CVC_E_WRONGOBJECT) if DenseCloud or Segmentor is invalid or DenseCloud is not dense.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if calibration piece could not be located properly.
• CVC_ERROR(CVC_E_MEMORY) if not enough memory was available intermediate processing.

See also

CVMAQS12CreateIntrinsicCalibratorFromPiece, CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPieceRect, CVMAQS12CreateSegmentorForDensePointCloud, CVC3DCalibratorSetCorrectionOfLaserPlaneInclination, CVMCalculateAffineTransformation

CVMAQS12CalculateCorrectionOfLaserPlaneInclinationWithParamsFromPieceRect()

cvbres_t CVMAQS12CalculateCorrectionOfLaserPlaneInclinationWithParamsFromPieceRect	(	CVCOMPOSITE	DenseCloud,
		cvbdim_t	Left,
		cvbdim_t	Top,
		cvbdim_t	Right,
		cvbdim_t	Bottom,
		CVMAQS12SEGMENTOR3D	Segmentor,
		CVMAQS12CALCONFIG	CalConfig,
		CVC3DTransformation &	TransformationLaserPlaneInclination,
		CVC3DAffineTransformationParameters &	TransformationParameters,
		CVC3DPointD	Residuals[12]
	)

Calculates the affine transformation TransformationLaserPlaneInclination from the given DenseCloud of an AQS12 calibration piece. This transformation corrects errors induced by an inclined laser plane.

Note

In this function, the area of interest is selected from the xy plane of a dense point cloud. So this function does not work with sparse point clouds. For sparse point clouds crop the desired area first and then use function CVMAQS12CalculateCorrectionOfLaserPlaneInclinationWithParamsFromPiece.

This function expects a point cloud showing the AQS12 calibration piece in the following orientation:

The LabelImage will have the same dimension as RangeMapImage and a cvbdatatype_t of 8 (Mono 8bpp).

Label	Value	Comment
Ignore	0	not part of calibration piece
Base	1	part of the base plane.
Top face	2	part of the top face.
Face 0°	3	part of 0° face (right)
Face 40°	4	part of 40° face (right/down)
Face 140°	5	part of 140° face (left/down)
Face 180°	6	part of 180° face (left)
Face 220°	7	part of 220° face (left/top)
Face 320°	8	part of 320° face (right/top)

Attention

The following constraints for the point cloud have to be met:

• The point cloud must be dense.
• The AQS12 may not be tilted. The xy plane must be parallel to the base plane of the AQS12.
• Disturbing background must be eliminated by setting these points to non-confident. You can create a calibrated dense point cloud with function CVC3DCreateCalibratedPointCloudFromRangeMap. Before creating the cloud, set the range map ignore value with function CVC3DCalibratorSetRangeMapIgnoreValue. All pixels with this value will be interpreted as non-confident.

Note

The region of interest must be selected on the grid of the dense point cloud. Left, top, right and bottom are indices for row and column.

Parameters

[in]	DenseCloud	Handle of dense point cloud.
[in]	Left	First column for region of interest in dense cloud.
[in]	Top	First row for region of interest in dense cloud.
[in]	Right	Last column for region of interest in dense cloud (inclusive).
[in]	Bottom	Last row for region of interest in dense cloud (inclusive).
[in]	Segmentor	Segmentor created by the function CVMAQS12CreateSegmentorForDensePointCloud.
[in]	CalConfig	Calibration configuration created by the function CVMAQS12CreateInstrinsicCalConfig.
[out]	TransformationLaserPlaneInclination	Variable to receive the affine transformation, which corrects erros induced by an inclined laser plane.
[out]	TransformationParameters	Variable to receive the transformation parameters. If CVMETM_AffineTransformation model is specified, the struct contains solely NaNs.
[out]	Residuals	Optional pointer to 12 point array to contain the residuals; nullptr if not needed.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_PARAMETER) if Points is nullptr or TopBasePlaneDistance or aoi is invalid.
• CVC_ERROR(CVC_E_WRONGOBJECT) if DenseCloud or Segmentor is invalid or DenseCloud is not dense.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if calibration piece could not be located properly.
• CVC_ERROR(CVC_E_MEMORY) if not enough memory was available intermediate processing.

See also

CVMAQS12CreateIntrinsicCalibratorFromPiece, CVMAQS12CalculateCorrectionOfLaserPlaneInclinationWithParamsFromPiece, CVMAQS12CreateSegmentorForDensePointCloud, CVC3DCalibratorSetCorrectionOfLaserPlaneInclination, CVC3DCalibratorSetCorrectionOfLaserPlaneInclinationParameters, CVMCalculateCorrectionOfLaserPlaneInclinationWithParams

CVMAQS12CalculateExtrinsicMatrix()

cvbres_t CVMAQS12CalculateExtrinsicMatrix	(	IMG	RangeMapImage,
		cvbdim_t	PlaneIndex,
		CVC3DCALIBRATOR	Calibrator,
		const CVC3DPointD	Points[12],
		double	TopBasePlaneDistance,
		CVC3DTransformation &	ExtrinsicTransformation,
		CVC3DPointD	Residuals[12]
	)

Calculates the ExtrinsicTransformation from the given RangeMapImage of an AQS12 calibration piece.

This is the full image variant of CVMAQS12CalculateExtrinsicMatrixRect. Detailed information can be found there.

Attention

Only RangeMapImage objects up to four gigapixels are supported.

Parameters

[in]	RangeMapImage	Handle of 2½D image.
[in]	PlaneIndex	Plane of RangeMapImage to use in the range of [0 .. ImageDimension[.
[in]	Calibrator	Optional calibrator to apply to the RangeMapImage (no extrinsic transformation is done).
[in]	Points	The 12 reference points in world coordinates.
[in]	TopBasePlaneDistance	Optional distance between the top plane and the base plane in world coordinate units (same as Points); can be 0 if base plane is at z = 0.
[out]	ExtrinsicTransformation	Variable to receive the extrinsic transformation.
[out]	Residuals	Optional pointer to 12 point array to contain the difference between the reference Points and the ExtrinsicTransformation result; nullptr if not needed.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_INVALIDDIMENSION) if PlaneIndex is out of range.
• CVC_ERROR(CVC_E_PARAMETER) if Points is nullptr or TopBasePlaneDistance is invalid.
• CVC_ERROR(CVC_E_WRONGOBJECT) if RangeMapImage is neither a IImageVPA nor IPlaneEnum object or Calibrator is non-nullptr and invalid.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if calibration piece could not be located properly.
• CVC_ERROR(CVC_E_MEMORY) if not enough memory was available intermediate processing.

CVMAQS12CalculateExtrinsicMatrixRect()

cvbres_t CVMAQS12CalculateExtrinsicMatrixRect	(	IMG	RangeMapImage,
		cvbdim_t	PlaneIndex,
		cvbdim_t	Left,
		cvbdim_t	Top,
		cvbdim_t	Right,
		cvbdim_t	Bottom,
		CVC3DCALIBRATOR	Calibrator,
		const CVC3DPointD	Points[12],
		double	TopBasePlaneDistance,
		CVC3DTransformation &	ExtrinsicTransformation,
		CVC3DPointD	Residuals[12]
	)

Calculates the ExtrinsicTransformation from the given RangeMapImage of an AQS12 calibration piece.

This function expects a range map showing the AQS12 calibration piece in the following orientation:

The 12 Points are interpreted as indicated by the corner points above. As the points 7 to 12 are higher than the base plane, you need to give the TopBasePlaneDistance. The top plane is defined by the points 1 to 6.

If a Calibrator is given, the RangeMapImage is calibrated with it before calculating the extrinsic calibration based on the real world Points.

Attention

Only RangeMapImage objects up to four gigapixels are supported.

Parameters

[in]	RangeMapImage	Handle of 2½D image.
[in]	PlaneIndex	Plane of RangeMapImage to use in the range of [0 .. ImageDimension[.
[in]	Left	Left border of region of interest in pixels.
[in]	Top	Top border of region of interest in pixels.
[in]	Right	Right border of region of interest in pixels (inclusive).
[in]	Bottom	Bottom border of region of interest in pixels (inclusive).
[in]	Calibrator	Optional calibrator to apply to the RangeMapImage (no extrinsic transformation is done).
[in]	Points	The 12 reference points in world coordinates.
[in]	TopBasePlaneDistance	Optional distance between the top plane and the base plane in world coordinate units (same as Points); can be 0 if base plane is at z = 0.
[out]	ExtrinsicTransformation	Variable to receive the extrinsic transformation.
[out]	Residuals	Optional pointer to 12 point array to contain the difference between the reference Points and the ExtrinsicTransformation result; nullptr if not needed.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_INVALIDDIMENSION) if PlaneIndex is out of range.
• CVC_ERROR(CVC_E_PARAMETER) if the region of interest is outside the bounds of RangeMapImage, Points is nullptr or TopBasePlaneDistance is invalid.
• CVC_ERROR(CVC_E_WRONGOBJECT) if RangeMapImage is neither a IImageVPA nor IPlaneEnum object or Calibrator is non-nullptr and invalid.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if calibration piece could not be located properly.
• CVC_ERROR(CVC_E_MEMORY) if not enough memory was available intermediate processing.

CVMAQS12CalculateRigidBodyTransformationFromPiece()

cvbres_t CVMAQS12CalculateRigidBodyTransformationFromPiece	(	CVCOMPOSITE	DenseCloud,
		CVMAQS12SEGMENTOR3D	Segmentor,
		const CVC3DPointD	Points[12],
		double	TopBasePlaneDistance,
		CVC3DTransformation &	ExtrinsicTransformation,
		CVC3DPointD	Residuals[12]
	)

Calculates the rigid body transformation (rotation matrix and translation) from the given DenseCloud of an AQS12 calibration piece.The transformation is estimated by the Nelder-Mead method. The rigid body transformation is part of the extrinsic calibration.

This is the full image variant of CVMAQS12CalculateRigidBodyTransformationFromPieceRect. Detailed information can be found there.

Parameters

[in]	DenseCloud	Handle of dense point cloud.
[in]	Segmentor	Segmentor created by the function CVMAQS12CreateSegmentorForDensePointCloud.
[in]	Points	The 12 reference points in world coordinates.
[in]	TopBasePlaneDistance	Optional distance between the top plane and the base plane in world coordinate units (same as Points); can be 0 if base plane is at z = 0.
[out]	ExtrinsicTransformation	Variable to transformation.
[out]	Residuals	Optional pointer to 12 point array to contain the residuals; nullptr if not needed.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_PARAMETER) if Points is nullptr or TopBasePlaneDistance is invalid.
• CVC_ERROR(CVC_E_WRONGOBJECT) if DenseCloud or Segmentor is invalid or DenseCloud is not dense.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if calibration piece could not be located properly.
• CVC_ERROR(CVC_E_MEMORY) if not enough memory was available intermediate processing.

See also

CVMAQS12CalculateRigidBodyTransformationFromPieceRect, CVMCalculateRigidBodyTransformation, CVMAQS12CreateSegmentorForDensePointCloud

CVMAQS12CalculateRigidBodyTransformationFromPieceRect()

cvbres_t CVMAQS12CalculateRigidBodyTransformationFromPieceRect	(	CVCOMPOSITE	DenseCloud,
		cvbdim_t	Left,
		cvbdim_t	Top,
		cvbdim_t	Right,
		cvbdim_t	Bottom,
		CVMAQS12SEGMENTOR3D	Segmentor,
		const CVC3DPointD	Points[12],
		double	TopBasePlaneDistance,
		CVC3DTransformation &	ExtrinsicTransformation,
		CVC3DPointD	Residuals[12]
	)

Calculates the rigid body transformation (rotation matrix and translation) from the given DenseCloud of an AQS12 calibration piece. The transformation is estimated by the Nelder-Mead method. The rigid body transformation is part of the extrinsic calibration.

Note

In this function, the area of interest is selected from the xy plane of a dense point cloud. So this function does not work with sparse point clouds. For sparse point clouds crop the desired area first and then use function CVMAQS12CalculateRigidBodyTransformationFromPiece.

This function expects a point cloud showing the AQS12 calibration piece in the following orientation:

The LabelImage will have the same dimension as RangeMapImage and a cvbdatatype_t of 8 (Mono 8bpp).

Label	Value	Comment
Ignore	0	not part of calibration piece
Base	1	part of the base plane.
Top face	2	part of the top face.
Face 0°	3	part of 0° face (right)
Face 40°	4	part of 40° face (right/down)
Face 140°	5	part of 140° face (left/down)
Face 180°	6	part of 180° face (left)
Face 220°	7	part of 220° face (left/top)
Face 320°	8	part of 320° face (right/top)

Attention

The following constraints for the point cloud have to be met:

• The point cloud must be dense.
• The AQS12 may not be tilted. The xy plane must be parallel to the base plane of the AQS12.
• Disturbing background must be eliminated by setting these points to non-confident. You can create a calibrated dense point cloud with function CVC3DCreateCalibratedPointCloudFromRangeMap. Before creating the cloud, set the range map ignore value with function CVC3DCalibratorSetRangeMapIgnoreValue. All pixels with this value will be interpreted as non-confident.

Note

The region of interest must be selected on the grid of the dense point cloud. Left, top, right and bottom are indices for row and column.

Parameters

[in]	DenseCloud	Handle of dense point cloud.
[in]	Left	First column for region of interest in dense cloud.
[in]	Top	First row for region of interest in dense cloud.
[in]	Right	Last column for region of interest in dense cloud (inclusive).
[in]	Bottom	Last row for region of interest in dense cloud (inclusive).
[in]	Segmentor	Segmentor created by the function CVMAQS12CreateSegmentorForDensePointCloud.
[in]	Points	The 12 reference points in world coordinates.
[in]	TopBasePlaneDistance	Optional distance between the top plane and the base plane in world coordinate units (same as Points); can be 0 if base plane is at z = 0.
[out]	ExtrinsicTransformation	Variable to transformation.
[out]	Residuals	Optional pointer to 12 point array to contain the residuals; nullptr if not needed.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_PARAMETER) if Points is nullptr or TopBasePlaneDistance or aoi is invalid.
• CVC_ERROR(CVC_E_WRONGOBJECT) if DenseCloud or Segmentor is invalid or DenseCloud is not dense.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if calibration piece could not be located properly.
• CVC_ERROR(CVC_E_MEMORY) if not enough memory was available intermediate processing.

See also

CVMAQS12CalculateRigidBodyTransformationFromPiece, CVMCalculateRigidBodyTransformation, CVMAQS12CreateSegmentorForDensePointCloud

CVMAQS12CalculateRigidBodyTransformationWithParamsFromPiece()

cvbres_t CVMAQS12CalculateRigidBodyTransformationWithParamsFromPiece	(	CVCOMPOSITE	DenseCloud,
		CVMAQS12SEGMENTOR3D	Segmentor,
		const CVC3DPointD	Points[12],
		double	TopBasePlaneDistance,
		CVC3DTransformation &	ExtrinsicTransformation,
		CVC3DAffineTransformationParameters &	TransformationParameters,
		CVC3DPointD	Residuals[12]
	)

Calculates the rigid body transformation (rotation matrix and translation) from the given DenseCloud of an AQS12 calibration piece.The transformation is estimated by the Nelder-Mead method. The rigid body transformation is part of the extrinsic calibration.

This is the full image variant of CVMAQS12CalculateRigidBodyTransformationFromPieceRect. Detailed information can be found there.

Parameters

[in]	DenseCloud	Handle of dense point cloud.
[in]	Segmentor	Segmentor created by the function CVMAQS12CreateSegmentorForDensePointCloud.
[in]	Points	The 12 reference points in world coordinates.
[in]	TopBasePlaneDistance	Optional distance between the top plane and the base plane in world coordinate units (same as Points); can be 0 if base plane is at z = 0.
[out]	ExtrinsicTransformation	Variable to transformation.
[out]	TransformationParameters	Variable to receive the transformation parameters.
[out]	Residuals	Optional pointer to 12 point array to contain the residuals; nullptr if not needed.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_PARAMETER) if Points is nullptr or TopBasePlaneDistance is invalid.
• CVC_ERROR(CVC_E_WRONGOBJECT) if DenseCloud or Segmentor is invalid or DenseCloud is not dense.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if calibration piece could not be located properly.
• CVC_ERROR(CVC_E_MEMORY) if not enough memory was available intermediate processing.

See also

CVMAQS12CalculateRigidBodyTransformationWithParamsFromPieceRect, CVMCalculateRigidBodyTransformationWithParams, CVMAQS12CreateSegmentorForDensePointCloud

CVMAQS12CalculateRigidBodyTransformationWithParamsFromPieceRect()

cvbres_t CVMAQS12CalculateRigidBodyTransformationWithParamsFromPieceRect	(	CVCOMPOSITE	DenseCloud,
		cvbdim_t	Left,
		cvbdim_t	Top,
		cvbdim_t	Right,
		cvbdim_t	Bottom,
		CVMAQS12SEGMENTOR3D	Segmentor,
		const CVC3DPointD	Points[12],
		double	TopBasePlaneDistance,
		CVC3DTransformation &	ExtrinsicTransformation,
		CVC3DAffineTransformationParameters &	TransformationParameters,
		CVC3DPointD	Residuals[12]
	)

Calculates the rigid body transformation (rotation matrix and translation) from the given DenseCloud of an AQS12 calibration piece. The transformation is estimated by the Nelder-Mead method. The rigid body transformation is part of the extrinsic calibration.

Note

In this function, the area of interest is selected from the xy plane of a dense point cloud. So this function does not work with sparse point clouds. For sparse point clouds crop the desired area first and then use function CVMAQS12CalculateRigidBodyTransformationFromPiece.

This function expects a point cloud showing the AQS12 calibration piece in the following orientation:

The LabelImage will have the same dimension as RangeMapImage and a cvbdatatype_t of 8 (Mono 8bpp).

Label	Value	Comment
Ignore	0	not part of calibration piece
Base	1	part of the base plane.
Top face	2	part of the top face.
Face 0°	3	part of 0° face (right)
Face 40°	4	part of 40° face (right/down)
Face 140°	5	part of 140° face (left/down)
Face 180°	6	part of 180° face (left)
Face 220°	7	part of 220° face (left/top)
Face 320°	8	part of 320° face (right/top)

Attention

The following constraints for the point cloud have to be met:

• The point cloud must be dense.
• The AQS12 may not be tilted. The xy plane must be parallel to the base plane of the AQS12.
• Disturbing background must be eliminated by setting these points to non-confident. You can create a calibrated dense point cloud with function CVC3DCreateCalibratedPointCloudFromRangeMap. Before creating the cloud, set the range map ignore value with function CVC3DCalibratorSetRangeMapIgnoreValue. All pixels with this value will be interpreted as non-confident.

Note

The region of interest must be selected on the grid of the dense point cloud. Left, top, right and bottom are indices for row and column.

Parameters

[in]	DenseCloud	Handle of dense point cloud.
[in]	Left	First column for region of interest in dense cloud.
[in]	Top	First row for region of interest in dense cloud.
[in]	Right	Last column for region of interest in dense cloud (inclusive).
[in]	Bottom	Last row for region of interest in dense cloud (inclusive).
[in]	Segmentor	Segmentor created by the function CVMAQS12CreateSegmentorForDensePointCloud.
[in]	Points	The 12 reference points in world coordinates.
[in]	TopBasePlaneDistance	Optional distance between the top plane and the base plane in world coordinate units (same as Points); can be 0 if base plane is at z = 0.
[out]	ExtrinsicTransformation	Variable to transformation.
[out]	TransformationParameters	Variable to receive the transformation parameters.
[out]	Residuals	Optional pointer to 12 point array to contain the residuals; nullptr if not needed.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_PARAMETER) if Points is nullptr or TopBasePlaneDistance or aoi is invalid.
• CVC_ERROR(CVC_E_WRONGOBJECT) if DenseCloud or Segmentor is invalid or DenseCloud is not dense.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if calibration piece could not be located properly.
• CVC_ERROR(CVC_E_MEMORY) if not enough memory was available intermediate processing.

See also

CVMAQS12CalculateRigidBodyTransformationWithParamsFromPiece, CVMCalculateRigidBodyTransformation, CVMAQS12CreateSegmentorForDensePointCloud

CVMAQS12CreateCalibrator()

cvbres_t CVMAQS12CreateCalibrator	(	IMG	RangeMapImage,
		cvbdim_t	PlaneIndex,
		const CVC3DPointD	Points[12],
		double	TopBasePlaneDistance,
		CVMIntrinsicCorrectionModel	Model,
		CVC3DCALIBRATOR &	Calibrator,
		CVC3DPointD	Residuals[12]
	)

Creates an intrinsic/extrinsic Calibrator from the given RangeMapImage of an AQS12 calibration piece.

This is the full image variant of CVMAQS12CreateCalibratorRect. Detailed information can be found there.

Note

If this function returns successfully you need to release the returned Calibrator via ReleaseObject if not needed anymore.

Parameters

[in]	RangeMapImage	Handle of 2½D image.
[in]	PlaneIndex	Plane of RangeMapImage to use in the range of [0 .. ImageDimension[.
[in]	Points	The 12 reference points in world coordinates.
[in]	TopBasePlaneDistance	Optional distance between the top plane and the base plane in world coordinate units (same as Points); can be 0 if base plane is at z = 0.
[in]	Model	Calibration model to apply (so far only CVMICM_XZHomography is supported).
[out]	Calibrator	Variable to receive the newly created calibrator object.
[out]	Residuals	Optional pointer to 12 point array to contain the difference between the reference Points and the Calibrator result; nullptr if not needed.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_INVALIDDIMENSION) if PlaneIndex is out of range.
• CVC_ERROR(CVC_E_PARAMETER) if Points is nullptr, TopBasePlaneDistance is invalid or Model is not supported.
• CVC_ERROR(CVC_E_WRONGOBJECT) if RangeMapImage is neither a IImageVPA nor IPlaneEnum object.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if calibration piece could not be located properly.
• CVC_ERROR(CVC_E_MEMORY) if not enough memory was available intermediate processing.

See also

CVMAQS12CreateCalibratorRect, CVMAQS12CalculateExtrinsicMatrix

CVMAQS12CreateCalibratorRect()

cvbres_t CVMAQS12CreateCalibratorRect	(	IMG	RangeMapImage,
		cvbdim_t	PlaneIndex,
		cvbdim_t	Left,
		cvbdim_t	Top,
		cvbdim_t	Right,
		cvbdim_t	Bottom,
		const CVC3DPointD	Points[12],
		double	TopBasePlaneDistance,
		CVMIntrinsicCorrectionModel	Model,
		CVC3DCALIBRATOR &	Calibrator,
		CVC3DPointD	Residuals[12]
	)

Creates an intrinsic/extrinsic Calibrator from the given RangeMapImage of an AQS12 calibration piece.

This function expects a range map showing the AQS12 calibration piece in the following orientation:

The 12 Points are interpreted as indicated by the corner points above. As the points 7 to 12 are higher than the base plane, you need to give the TopBasePlaneDistance. The top plane is defined by the points 1 to 6.

The resulting Calibrator contains the intrinsic calibration as specified by Model and the extrinsic calibration based on the real world Points.

Note

If this function returns successfully you need to release the returned Calibrator via ReleaseObject if not needed anymore.

Attention

Only RangeMapImage objects up to four gigapixels are supported.

Parameters

[in]	RangeMapImage	Handle of 2½D image.
[in]	PlaneIndex	Plane of RangeMapImage to use in the range of [0 .. ImageDimension[.
[in]	Left	Left border of region of interest in pixels.
[in]	Top	Top border of region of interest in pixels.
[in]	Right	Right border of region of interest in pixels (inclusive).
[in]	Bottom	Bottom border of region of interest in pixels (inclusive).
[in]	Points	The 12 reference points in world coordinates.
[in]	TopBasePlaneDistance	Optional distance between the top plane and the base plane in world coordinate units (same as Points); can be 0 if base plane is at z = 0.
[in]	Model	Calibration model to apply (so far only CVMICM_XZHomography is supported).
[out]	Calibrator	Variable to receive the newly created calibrator object.
[out]	Residuals	Optional pointer to 12 point array to contain the difference between the reference Points and the Calibrator result; nullptr if not needed.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_INVALIDDIMENSION) if PlaneIndex is out of range.
• CVC_ERROR(CVC_E_PARAMETER) if the region of interest is outside the bounds of RangeMapImage, Points is nullptr, TopBasePlaneDistance is invalid or Model is not supported.
• CVC_ERROR(CVC_E_WRONGOBJECT) if RangeMapImage is neither a IImageVPA nor IPlaneEnum object.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if calibration piece could not be located properly.
• CVC_ERROR(CVC_E_MEMORY) if not enough memory was available intermediate processing.

See also

CVMAQS12CreateCalibrator, CVMAQS12CalculateExtrinsicMatrix

CVMAQS12CreateFaceSegmentationImage()

cvbres_t CVMAQS12CreateFaceSegmentationImage	(	IMG	RangeMapImage,
		cvbdim_t	PlaneIndex,
		IMG &	LabelImage
	)

Segments the given RangeMapImage into the different faces of the AQS12 calibration piece.

This is the full image variant of CVMAQS12CreateFaceSegmentationImageRect. Detailed information can be found there.

Note

If this function returns successfully you need to release the returned LabelImage via ReleaseObject if not needed anymore.

Parameters

[in]	RangeMapImage	Handle of 2½D image.
[in]	PlaneIndex	Plane of RangeMapImage to use in the range of [0 .. ImageDimension[.
[out]	LabelImage	Variable to receive the result image handle.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_INVALIDDIMENSION) if PlaneIndex is out of range.
• CVC_ERROR(CVC_E_WRONGOBJECT) if RangeMapImage is neither a IImageVPA nor IPlaneEnum object.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if calibration piece could not be located properly.
• CVC_ERROR(CVC_E_MEMORY) if not enough memory was available to create the label image.

CVMAQS12CreateFaceSegmentationImageRect()

cvbres_t CVMAQS12CreateFaceSegmentationImageRect	(	IMG	RangeMapImage,
		cvbdim_t	PlaneIndex,
		cvbdim_t	Left,
		cvbdim_t	Top,
		cvbdim_t	Right,
		cvbdim_t	Bottom,
		IMG &	LabelImage
	)

Segments the given RangeMapImage into the different faces of the AQS12 calibration piece.

This function expects a range map showing the AQS12 calibration piece in the following orientation:

The LabelImage will have the same dimension as RangeMapImage and a cvbdatatype_t of 8 (Mono 8bpp). Everything outside of the ROI will be set to Ignore.

Label	Value	Comment
Ignore	0	not part of calibration piece
Base	1	part of the base plane.
Top face	2	part of the top face.
Face 0°	3	part of 0° face (right)
Face 40°	4	part of 40° face (right/down)
Face 140°	5	part of 140° face (left/down)
Face 180°	6	part of 180° face (left)
Face 220°	7	part of 220° face (left/top)
Face 320°	8	part of 320° face (right/top)

Note

If this function returns successfully you need to release the returned LabelImage via ReleaseObject if not needed anymore.

Parameters

[in]	RangeMapImage	Handle of 2½D image.
[in]	PlaneIndex	Plane of RangeMapImage to use in the range of [0 .. ImageDimension[.
[in]	Left	Left border of region of interest in pixels.
[in]	Top	Top border of region of interest in pixels.
[in]	Right	Right border of region of interest in pixels (inclusive).
[in]	Bottom	Bottom border of region of interest in pixels (inclusive).
[out]	LabelImage	Variable to receive the result image handle.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_INVALIDDIMENSION) if PlaneIndex is out of range.
• CVC_ERROR(CVC_E_WRONGOBJECT) if RangeMapImage is neither a IImageVPA nor IPlaneEnum object.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if calibration piece could not be located properly.
• CVC_ERROR(CVC_E_MEMORY) if not enough memory was available to create the label image.

CVMAQS12CreateIntrinsicCalibratorFromPiece()

cvbres_t CVMAQS12CreateIntrinsicCalibratorFromPiece	(	IMG	RangeMapImage,
		cvbdim_t	PlaneIndex,
		CVMAQS12SEGMENTOR2D	Segmentor,
		CVMAQS12CALCONFIG	CalConfig,
		CVC3DCALIBRATOR &	Calibrator,
		CVC3DPointD	Residuals[12]
	)

Creates an intrinsic Calibrator from the given RangeMapImage of an AQS12 calibration piece.

This is the full image variant of CVMAQS12CreateIntrinsicCalibratorFromPieceRect. Detailed information can be found there.

Note

If this function returns successfully you need to release the returned Calibrator via ReleaseObject if not needed anymore.

Attention

Only RangeMapImage objects up to four gigapixels are supported.

Parameters

[in]	RangeMapImage	Handle of 2½D image.
[in]	PlaneIndex	Plane of RangeMapImage to use in the range of [0 .. ImageDimension[.
[in]	Segmentor	Segmentor created by the function CVMAQS12CreateSegmentorForRangeMap.
[in]	CalConfig	Calibration configuration created by the function CVMAQS12CreateInstrinsicCalConfig.
[out]	Calibrator	Variable to receive the newly created calibrator object.
[out]	Residuals	Optional pointer to 12 point array to contain the residuals; nullptr if not needed.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_INVALIDDIMENSION) if PlaneIndex is out of range.
• CVC_ERROR(CVC_E_PARAMETER) if calibration model in CalConfig is not supported.
• CVC_ERROR(CVC_E_WRONGOBJECT) if RangeMapImage is neither a IImageVPA nor IPlaneEnum object or Segmentor or CalConfig is invalid.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if calibration piece could not be located properly.
• CVC_ERROR(CVC_E_MEMORY) if not enough memory was available intermediate processing.

See also

CVMAQS12CreateIntrinsicCalibratorFromPieceRect, CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPiece

CVMAQS12CreateIntrinsicCalibratorFromPieceRect()

cvbres_t CVMAQS12CreateIntrinsicCalibratorFromPieceRect	(	IMG	RangeMapImage,
		cvbdim_t	PlaneIndex,
		cvbdim_t	Left,
		cvbdim_t	Top,
		cvbdim_t	Right,
		cvbdim_t	Bottom,
		CVMAQS12SEGMENTOR2D	Segmentor,
		CVMAQS12CALCONFIG	CalConfig,
		CVC3DCALIBRATOR &	Calibrator,
		CVC3DPointD	Residuals[12]
	)

Creates an intrinsic Calibrator from the given RangeMapImage of an AQS12 calibration piece.

This function expects a range map showing the AQS12 calibration piece in the following orientation:

The 12 Points are interpreted as indicated by the corner points above. As the points 7 to 12 are higher than the base plane, you need to give the TopBasePlaneDistance. The top plane is defined by the points 1 to 6.

The resulting Calibrator contains the intrinsic calibration as specified by CalConfig, i.e. either homography or homography and affine transformation. With the affine transformation errors induced by an inclined laser plane are corrected.

Note

If this function returns successfully you need to release the returned Calibrator via ReleaseObject if not needed anymore.

Attention

Only RangeMapImage objects up to four gigapixels are supported.

Parameters

[in]	RangeMapImage	Handle of 2½D image.
[in]	PlaneIndex	Plane of RangeMapImage to use in the range of [0 .. ImageDimension[.
[in]	Left	Left border of region of interest in pixels.
[in]	Top	Top border of region of interest in pixels.
[in]	Right	Right border of region of interest in pixels (inclusive).
[in]	Bottom	Bottom border of region of interest in pixels (inclusive).
[in]	Segmentor	Segmentor created by the function CVMAQS12CreateSegmentorForRangeMap.
[in]	CalConfig	Calibration configuration created by the function CVMAQS12CreateInstrinsicCalConfig.
[out]	Calibrator	Variable to receive the newly created calibrator object.
[out]	Residuals	Optional pointer to 12 point array to contain the residuals; nullptr if not needed.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_INVALIDDIMENSION) if PlaneIndex is out of range.
• CVC_ERROR(CVC_E_PARAMETER) if the region of interest is outside the bounds of RangeMapImage, or calibration model in CalConfig is not supported.
• CVC_ERROR(CVC_E_WRONGOBJECT) if RangeMapImage is neither a IImageVPA nor IPlaneEnum object or Segmentor or CalConfig is invalid.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if calibration piece could not be located properly.
• CVC_ERROR(CVC_E_MEMORY) if not enough memory was available intermediate processing.

See also

CVMAQS12CreateIntrinsicCalibratorFromPiece, CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPiece

Example

The following C++11 code shows the calibration workflow: Loading a range map, setting up the calibration configuration and the segmentor object and estimating the calibration parameters with the function described above. At the end the results are validated. If they are not accurate enough the user can check intermediate calibration results with the helper functions CVMAQS12CreateFaceSegmentationImageFromRangeMap and CVMAQS12ExtractProjectedPointsFromRangeMap.

#include <iostream>
#include <memory>
#include <vector>
 
#include "iCVCUtilities.h"
#include "CVCError.h"
#include "iCVMetric.h"
 
//  Helper to let the compiler take care of object life-time via custom deleter
using ObjPtr = std::unique_ptr<void, void(*)(OBJ)>;
ObjPtr CreateObjPtr(OBJ handle)
{
  return ObjPtr(handle, [](OBJ pObj) { ReleaseObject(pObj); });
}
 
int main()
{
  // reference points
  static const constexpr CVC3DPointD ReferencePoints[12] =
  {
    {   0,  40,     60 },
    {  10,  53.333, 60 },
    {  10,  96.667, 60 },
    {   0, 110,     60 },
    { -10,  96.667, 60 },
    { -10,  53.333, 60 },
    {   0,   0,     30 },
    {  30,  40,     30 },
    {  30, 110,     30 },
    {   0, 150,     30 },
    { -30, 110,     30 },
    { -30,  40,     30 },
  };
  static const constexpr double ReferenceTopBasePlaneDistance = 60;
 
  // load range map of AQS12
  std::vector<wchar_t> path(260);
  GetCVBDirectoryW(path.data(), path.size());
  auto rgFile = std::wstring(path.data()) + std::wstring(L"Tutorial/Metric/Images/RangeMap_CalibrationPattern.tif");
  IMG rangeMap = nullptr;
  if (!LoadImageFileT(rgFile.c_str(), rangeMap))
    return CVC_ERROR(CVC_E_ERROR);
  auto pRangeMap = CreateObjPtr(rangeMap);
 
  // create calibration configuration object
  CVMAQS12CALCONFIG config = nullptr;
  if (auto error = CVMAQS12CreateInstrinsicCalConfig(ReferencePoints, ReferenceTopBasePlaneDistance, config))
    return error;
  auto pConfig = CreateObjPtr(config);
 
  // create AQS12 segmentor for range maps
  CVMAQS12SEGMENTOR2D segmentor = nullptr;
  if (auto error = CVMAQS12CreateSegmentorForRangeMap(CVMAQS12SegmentationMethod::CVMSM_KmeansClustering,
  segmentor))
    return error;
  auto pSegmentor = CreateObjPtr(segmentor);
 
  // estimate calibration parameters
  CVC3DCALIBRATOR calib = nullptr;
  CVC3DPointD residuals[12] = { 0 };
  if (auto error = CVMAQS12CreateIntrinsicCalibratorFromPiece(rangeMap, 0, segmentor, config, calib, residuals))
    return error;
  auto pCalib = CreateObjPtr(calib);
 
  // check residuals
  bool resultsOk = true;
  double desiredAccuracy = 0.05;
  for (auto i = 0; i < 12; i++)
  {
    if (std::fabs(residuals[i].X) > desiredAccuracy || std::fabs(residuals[i].Y) > desiredAccuracy ||
    std::fabs(residuals[i].Z) > desiredAccuracy)
    {
      resultsOk = false;
      break;
    }
  }
 
  // check intermediate results, if necessary
  if (!resultsOk)
  {
    std::cout << "Results do not have desired accuracy. Check face segmentation and extracted AQS12 points...\n";
 
    // face segmentation
    IMG labelImage = nullptr;
    if (auto error = CVMAQS12CreateFaceSegmentationImageFromRangeMap(rangeMap, 0, segmentor, labelImage))
      return error;
    auto pLabelImage = CreateObjPtr(labelImage);
 
    // point extraction
    CVC3DPointD points[12] = { 0 };
    if (auto error = CVMAQS12ExtractProjectedPointsFromRangeMap(rangeMap, 0, segmentor, points))
      return error;
  }
 
  return CVC_ERROR(CVC_E_OK);
}

CVMCalculateAffineTransformation()

cvbres_t CVMCalculateAffineTransformation	(	const CVC3DPointD *	ReferencePoints,
		const CVC3DPointD *	MeasuredPoints,
		cvbdim_t	PointsLength,
		CVC3DTransformation &	Transformation
	)

Calculates an affine transformation from given reference points (which are assumed to be correct) and measured points. The transformation is calculated by a singular value decomposition.

Parameters

[in]	ReferencePoints	Array of size PointsLength containing reference points of the body.
[in]	MeasuredPoints	Array of size PointsLength containing the corresponding mesuared points of the body.
[in]	PointsLength	Number of points, size of ReferencePoints and Points. At least 4 points are necessary.
[out]	Transformation	Pointer to matrix to be filled with the transformation matrix elements and translation.

Returns

• CVC_ERROR(CVC_E_OK) on success.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if PointsLength is too low.

See also

CVMCalculateRigidBodyTransformation, CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPiece

CVMCalculateCorrectionOfLaserPlaneInclinationWithParams()

cvbres_t CVMCalculateCorrectionOfLaserPlaneInclinationWithParams	(	const CVC3DPointD *	ReferencePoints,
		const CVC3DPointD *	MeasuredPoints,
		cvbdim_t	PointsLength,
		CVMExtrinsicTransformationModel	Model,
		cvbbool_t	CalculateEncoderStep,
		CVC3DTransformation &	Transformation,
		CVC3DAffineTransformationParameters &	TransformationParameters,
		CVC3DPointD *	Residuals
	)

Calculates an affine transformation (correcting the inclination of the laser plane) from given reference points and measured points.

Parameters

[in]	ReferencePoints	Array of size PointsLength containing reference points of the body.
[in]	MeasuredPoints	Array of size PointsLength containing the corresponding mesuared points of the body.
[in]	PointsLength	Number of points, size of ReferencePoints and Points. At least 4 points are necessary.
[in]	Model	Extrinsic tranformation model to be estimated.
[in]	CalculateEncoderStep	Flag to enable or disable the estimation of the encoder step (scaling in Y).
[out]	Transformation	Pointer to matrix to be filled with the transformation matrix elements and translation.
[out]	TransformationParameters	Variable to receive the transformation parameters. If CVMETM_AffineTransformation model is specified, the struct contains solely NaNs.
[out]	Residuals	Optional pointer to point array to contain the residuals; must match the size of PointsLength; nullptr if not needed.

Returns

• CVC_ERROR(CVC_E_OK) on success.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if PointsLength is too low.

See also

CVMCalculateRigidBodyTransformation, CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPiece

CVMCalculateRigidBodyTransformation()

cvbres_t CVMCalculateRigidBodyTransformation	(	const CVC3DPointD *	ReferencePoints,
		const CVC3DPointD *	MeasuredPoints,
		cvbdim_t	PointsLength,
		CVC3DTransformation &	Transformation
	)

Calculates a rigid body transformation (rotation matrix and translation) from given reference points (which are assumed to be correct) and measured points. The transformation is estimated by the Nelder-Mead method.

Parameters

[in]	ReferencePoints	Array of size PointsLength containing reference points of the body.
[in]	MeasuredPoints	Array of size PointsLength containing the corresponding mesuared points of the body.
[in]	PointsLength	Number of points, size pf ReferencePoints and MeasuredPoints. At least 3 points are necessary.
[out]	Transformation	Pointer to matrix to be filled with the rotation matrix elements and translation.

Returns

• CVC_ERROR(CVC_E_OK) on success.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if PointsLength is too low.

See also

CVMCalculateAffineTransformation, CVMAQS12CalculateRigidBodyTransformationFromPiece

CVMCalculateRigidBodyTransformationWithParams()

cvbres_t CVMCalculateRigidBodyTransformationWithParams	(	const CVC3DPointD *	ReferencePoints,
		const CVC3DPointD *	MeasuredPoints,
		cvbdim_t	PointsLength,
		CVC3DTransformation &	Transformation,
		CVC3DAffineTransformationParameters &	TransformationParameters,
		CVC3DPointD *	Residuals
	)

Calculates a rigid body transformation (rotation matrix and translation) from given reference points (which are assumed to be correct) and measured points. The transformation is estimated by the Nelder-Mead method.

Parameters

[in]	ReferencePoints	Array of size PointsLength containing reference points of the body.
[in]	MeasuredPoints	Array of size PointsLength containing the corresponding mesuared points of the body.
[in]	PointsLength	Number of points, size pf ReferencePoints and MeasuredPoints. At least 3 points are necessary.
[out]	Transformation	Pointer to matrix to be filled with the rotation matrix elements and translation.
[out]	TransformationParameters	Variable to receive the transformation parameters.
[out]	Residuals	Optional pointer to point array to contain the residuals; must match the size of PointsLength; nullptr if not needed.

Returns

• CVC_ERROR(CVC_E_OK) on success.
• CVC_ERROR(CVC_E_NOTENOUGHDATA) if PointsLength is too low.

See also

CVMCalculateAffineTransformation, CVMAQS12CalculateRigidBodyTransformationFromPiece

CVMFindSpheres()

cvbres_t CVMFindSpheres	(	CVCOMPOSITE	DenseCloud,
		double	radius,
		double	sensitivity,
		TSphere *	spheres,
		int &	numspheres,
		int	maxnumspheres
	)

Detect spheres of a given radius in dense point clouds.

Attention

This algorithm detects spheres in sensor-centered dense pointclouds, i.e. the pointcloud coordinates are expected like this: X increasing in pointcloud width, Y increasing in pointcloud height and Z is pointing towards the scene.

Parameters

[in]	DenseCloud	Properly oriented pointcloud.
[in]	radius	Size of spheres to detect. This is a rough value only and serves for preprocessing purposes. The detected spheres may vary in size about 50% of this value.
[in]	sensitivity	Controls the triggering of an individual detection process. Ranges from 0.5 for very noisy pointclouds to 2.0 for very precise pointclouds.
[in]	spheres	Pointer to a memory area holding the results. The caller is responsible for providing enough memory to hold up to maxnumspheres sphere-results.
[out]	numspheres	The number of actual detected spheres. The individual results are written to the memory position given by Spheres.
[in]	maxnumspheres	The maximum number of spheres to be detected.

Returns

• CVC_ERROR(CVC_E_OK) on success.
• CVC_ERROR(CVC_E_WRONGOBJECT) if DenseCloud is not a dense point cloud object.

CVMWrite3DCalibrator()

cvbres_t CVMWrite3DCalibrator	(	CVC3DCALIBRATOR	Calibrator,
		const char *	FileName
	)

Writes a 3D calibration file (ASCII string version).

Writes the calibrator information in json format.

Parameters

[in]	Calibrator	Calibrator object to save.
[in]	FileName	Full path where to save the file to.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_PARAMETER) if FileName is nullptr.
• CVC_ERROR(CVC_E_WRONGOBJECT) if Calibrator is not a valid object.
• CVC_ERROR(CVC_E_FILEIO) if FileName is not accessible/existent
• CVC_ERROR(CVC_E_NOTSUPPORTED) if no foundation license is available.

CVMWrite3DCalibratorW()

cvbres_t CVMWrite3DCalibratorW	(	CVC3DCALIBRATOR	Calibrator,
		const wchar_t *	FileName
	)

Writes a 3D calibration file (Unicode string version).

Writes the calibrator information in json format.

Parameters

[in]	Calibrator	Calibrator object to save.
[in]	FileName	Full path where to save the file to.

Returns

• CVC_ERROR(CVC_E_OK) on success
• CVC_ERROR(CVC_E_PARAMETER) if FileName is nullptr.
• CVC_ERROR(CVC_E_WRONGOBJECT) if Calibrator is not a valid object.
• CVC_ERROR(CVC_E_FILEIO) if FileName is not accessible/existent
• CVC_ERROR(CVC_E_NOTSUPPORTED) if no foundation license is available.