Foundation (CVMetric.dll) 14.1
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  CVMIntrinsicCorrectionModel { CVMICM_XZHomography = 1 }
 Contains the possible intrinsic calibration correction models. Since Common Vision Blox 13.3. 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 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 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 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 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

◆ CVMIntrinsicCorrectionModel

Contains the possible intrinsic calibration correction models. Since Common Vision Blox 13.3. 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.

Since
Common Vision Blox 13.4
Parameters
[in]DenseCloudHandle of dense point cloud.
[in]SegmentorSegmentor created by the function CVMAQS12CreateSegmentorForDensePointCloud.
[in]CalConfigCalibration configuration created by the function CVMAQS12CreateInstrinsicCalConfig.
[out]TransformationLaserPlaneInclinationVariable to receive the affine transformation, which corrects erros induced by an inclined laser plane.
[out]ResidualsOptional pointer to 12 point array to contain the difference between the reference Points and the TransformationLaserPlaneInclination result; nullptr if not needed.
Returns
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.
Since
Common Vision Blox 13.4

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]DenseCloudHandle of dense point cloud.
[in]LeftFirst column for region of interest in dense cloud.
[in]TopFirst row for region of interest in dense cloud.
[in]RightLast column for region of interest in dense cloud (inclusive).
[in]BottomLast row for region of interest in dense cloud (inclusive).
[in]SegmentorSegmentor created by the function CVMAQS12CreateSegmentorForDensePointCloud.
[in]CalConfigCalibration configuration created by the function CVMAQS12CreateInstrinsicCalConfig.
[out]TransformationLaserPlaneInclinationVariable to receive the affine transformation, which corrects erros induced by an inclined laser plane.
[out]ResidualsOptional pointer to 12 point array to contain the difference between the reference Points and the TransformationLaserPlaneInclination result; nullptr if not needed.
Returns
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))
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;
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;
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;
}
cvbres_t CVMAQS12CalConfigSetCalculateHomography(CVMAQS12CALCONFIG CalibrationConfiguration, cvbbool_t CalculateHomography)
Sets or resets the flag to calculate homography of a calibration configurator.
Definition: ExportsCalibrationConfiguration.cpp:106
cvbres_t CVMAQS12CreateInstrinsicCalConfig(const CVC3DPointD Points[12], double TopBasePlaneDistance, CVMAQS12CALCONFIG &InstrinsicCalibrationConfiguration)
Creates a default intrinsic calibration configurator. Calculation of homography and correction of las...
Definition: ExportsCalibrationConfiguration.cpp:53
cvbres_t CVMAQS12CalculateCorrectionOfLaserPlaneInclinationFromPiece(CVCOMPOSITE DenseCloud, CVMAQS12SEGMENTOR3D Segmentor, CVMAQS12CALCONFIG CalConfig, CVC3DTransformation &TransformationLaserPlaneInclination, CVC3DPointD Residuals[12])
Calculates the affine transformation TransformationLaserPlaneInclination from the given DenseCloud of...
Definition: Exports.cpp:545
#define CVC_ERROR(a)
Definition: CVCError.h:18
CVC_E_OK
CVC_E_ERROR
cvbres_t CVC3DCalibratorSetCorrectionOfLaserPlaneInclination(CVC3DCALIBRATOR Calibrator, const CVC3DTransformation &IntrinsicAffineMatrix)
void * CVC3DCALIBRATOR
cvbres_t CVC3DCreateCalibratedPointCloudFromRangeMap(OBJ RangeMapImage, CVC3DCALIBRATOR Calibrator, cvbval_t Flags, CVCOMPOSITE &PointCloud)
cvbres_t CVC3DLoadCalibratorW(const wchar_t *FileName, CVC3DCALIBRATOR &Calibrator)
void * CVCOMPOSITE
CVC3DPCF_DTDouble
CVC3DPCF_NoExtrinsic
CVC3DPCF_XYZConfidence
cvbres_t CVMAQS12CreateSegmentorForDensePointCloud(CVMAQS12SegmentationMethod SegmentationMethod, CVMAQS12SEGMENTOR3D &Segmentor)
Creates a default AQS12 segmentor for dense point clouds.
Definition: ExportsSegmentationConfiguration.cpp:454
@ CVMSM_KmeansClustering
The faces of the AQS12 piece are clustered by the kmeans alogrithm.
Definition: iCVMetric.h:30

◆ 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]RangeMapImageHandle of 2½D image.
[in]PlaneIndexPlane of RangeMapImage to use in the range of [0 .. ImageDimension[.
[in]CalibratorOptional calibrator to apply to the RangeMapImage (no extrinsic transformation is done).
[in]PointsThe 12 reference points in world coordinates.
[in]TopBasePlaneDistanceOptional 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]ExtrinsicTransformationVariable to receive the extrinsic transformation.
[out]ResidualsOptional pointer to 12 point array to contain the difference between the reference Points and the ExtrinsicTransformation result; nullptr if not needed.
Returns

◆ 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]RangeMapImageHandle of 2½D image.
[in]PlaneIndexPlane of RangeMapImage to use in the range of [0 .. ImageDimension[.
[in]LeftLeft border of region of interest in pixels.
[in]TopTop border of region of interest in pixels.
[in]RightRight border of region of interest in pixels (inclusive).
[in]BottomBottom border of region of interest in pixels (inclusive).
[in]CalibratorOptional calibrator to apply to the RangeMapImage (no extrinsic transformation is done).
[in]PointsThe 12 reference points in world coordinates.
[in]TopBasePlaneDistanceOptional 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]ExtrinsicTransformationVariable to receive the extrinsic transformation.
[out]ResidualsOptional pointer to 12 point array to contain the difference between the reference Points and the ExtrinsicTransformation result; nullptr if not needed.
Returns

◆ 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.

Since
Common Vision Blox 13.4
Parameters
[in]DenseCloudHandle of dense point cloud.
[in]SegmentorSegmentor created by the function CVMAQS12CreateSegmentorForDensePointCloud.
[in]PointsThe 12 reference points in world coordinates.
[in]TopBasePlaneDistanceOptional 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]ExtrinsicTransformationVariable to transformation.
[out]ResidualsOptional pointer to 12 point array to contain the difference between the reference Points and the ExtrinsicTransformation result; nullptr if not needed.
Returns
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.
Since
Common Vision Blox 13.4

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]DenseCloudHandle of dense point cloud.
[in]LeftFirst column for region of interest in dense cloud.
[in]TopFirst row for region of interest in dense cloud.
[in]RightLast column for region of interest in dense cloud (inclusive).
[in]BottomLast row for region of interest in dense cloud (inclusive).
[in]SegmentorSegmentor created by the function CVMAQS12CreateSegmentorForDensePointCloud.
[in]PointsThe 12 reference points in world coordinates.
[in]TopBasePlaneDistanceOptional 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]ExtrinsicTransformationVariable to transformation.
[out]ResidualsOptional pointer to 12 point array to contain the difference between the reference Points and the ExtrinsicTransformation result; nullptr if not needed.
Returns
See also
CVMAQS12CalculateRigidBodyTransformationFromPiece, 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]RangeMapImageHandle of 2½D image.
[in]PlaneIndexPlane of RangeMapImage to use in the range of [0 .. ImageDimension[.
[in]PointsThe 12 reference points in world coordinates.
[in]TopBasePlaneDistanceOptional 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]ModelCalibration model to apply (so far only CVMICM_XZHomography is supported).
[out]CalibratorVariable to receive the newly created calibrator object.
[out]ResidualsOptional pointer to 12 point array to contain the difference between the reference Points and the Calibrator result; nullptr if not needed.
Returns
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]RangeMapImageHandle of 2½D image.
[in]PlaneIndexPlane of RangeMapImage to use in the range of [0 .. ImageDimension[.
[in]LeftLeft border of region of interest in pixels.
[in]TopTop border of region of interest in pixels.
[in]RightRight border of region of interest in pixels (inclusive).
[in]BottomBottom border of region of interest in pixels (inclusive).
[in]PointsThe 12 reference points in world coordinates.
[in]TopBasePlaneDistanceOptional 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]ModelCalibration model to apply (so far only CVMICM_XZHomography is supported).
[out]CalibratorVariable to receive the newly created calibrator object.
[out]ResidualsOptional pointer to 12 point array to contain the difference between the reference Points and the Calibrator result; nullptr if not needed.
Returns
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]RangeMapImageHandle of 2½D image.
[in]PlaneIndexPlane of RangeMapImage to use in the range of [0 .. ImageDimension[.
[out]LabelImageVariable to receive the result image handle.
Returns

◆ 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]RangeMapImageHandle of 2½D image.
[in]PlaneIndexPlane of RangeMapImage to use in the range of [0 .. ImageDimension[.
[in]LeftLeft border of region of interest in pixels.
[in]TopTop border of region of interest in pixels.
[in]RightRight border of region of interest in pixels (inclusive).
[in]BottomBottom border of region of interest in pixels (inclusive).
[out]LabelImageVariable to receive the result image handle.
Returns

◆ 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.

Since
Common Vision Blox 13.4
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]RangeMapImageHandle of 2½D image.
[in]PlaneIndexPlane of RangeMapImage to use in the range of [0 .. ImageDimension[.
[in]SegmentorSegmentor created by the function CVMAQS12CreateSegmentorForRangeMap.
[in]CalConfigCalibration configuration created by the function CVMAQS12CreateInstrinsicCalConfig.
[out]CalibratorVariable to receive the newly created calibrator object.
[out]ResidualsOptional pointer to 12 point array to contain the difference between the reference Points and the Calibrator result; nullptr if not needed.
Returns
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.

Since
Common Vision Blox 13.4

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]RangeMapImageHandle of 2½D image.
[in]PlaneIndexPlane of RangeMapImage to use in the range of [0 .. ImageDimension[.
[in]LeftLeft border of region of interest in pixels.
[in]TopTop border of region of interest in pixels.
[in]RightRight border of region of interest in pixels (inclusive).
[in]BottomBottom border of region of interest in pixels (inclusive).
[in]SegmentorSegmentor created by the function CVMAQS12CreateSegmentorForRangeMap.
[in]CalConfigCalibration configuration created by the function CVMAQS12CreateInstrinsicCalConfig.
[out]CalibratorVariable to receive the newly created calibrator object.
[out]ResidualsOptional pointer to 12 point array to contain the difference between the reference Points and the Calibrator result; nullptr if not needed.
Returns
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))
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;
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;
}
}
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.
Definition: Exports.cpp:155
cvbres_t CVMAQS12ExtractProjectedPointsFromRangeMap(IMG RangeMapImage, cvbdim_t PlaneIndex, CVMAQS12SEGMENTOR2D Segmentor, CVC3DPointD ExtractedPoints[12])
Extracts intersection points of faces of AQS12 calibration piece from a range map....
Definition: ExportsSegmentationPointExtraction.cpp:409
cvbres_t CVMAQS12CreateFaceSegmentationImageFromRangeMap(IMG RangeMapImage, cvbdim_t PlaneIndex, CVMAQS12SEGMENTOR2D Segmentor, IMG &LabelImage)
Segments the given RangeMapImage into the different faces of the AQS12 calibration piece.
Definition: ExportsSegmentationPointExtraction.cpp:63
cvbres_t CVMAQS12CreateSegmentorForRangeMap(CVMAQS12SegmentationMethod SegmentationMethod, CVMAQS12SEGMENTOR2D &Segmentor)
Creates a default AQS12 segmentor for range maps with default range map ignore value equal zero.
Definition: ExportsSegmentationConfiguration.cpp:137

◆ 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.

Since
Common Vision Blox 13.4
Parameters
[in]ReferencePointsArray of size PointsLength containing reference points of the body.
[in]MeasuredPointsArray of size PointsLength containing the corresponding mesuared points of the body.
[in]PointsLengthNumber of points, size of ReferencePoints and Points. At least 4 points are necessary.
[out]TransformationPointer to matrix to be filled with the transformation matrix elements and translation.
Returns
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.

Since
Common Vision Blox 13.4
Parameters
[in]ReferencePointsArray of size PointsLength containing reference points of the body.
[in]MeasuredPointsArray of size PointsLength containing the corresponding mesuared points of the body.
[in]PointsLengthNumber of points, size pf ReferencePoints and MeasuredPoints. At least 3 points are necessary.
[out]TransformationPointer to matrix to be filled with the rotation matrix elements and translation.
Returns
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.

Since
Common Vision Blox 13.4
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]DenseCloudProperly oriented pointcloud.
[in]radiusSize 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]sensitivityControls the triggering of an individual detection process. Ranges from 0.5 for very noisy pointclouds to 2.0 for very precise pointclouds.
[in]spheresPointer to a memory area holding the results. The caller is responsible for providing enough memory to hold up to maxnumspheres sphere-results.
[out]numspheresThe number of actual detected spheres. The individual results are written to the memory position given by Spheres.
[in]maxnumspheresThe maximum number of spheres to be detected.
Returns

◆ 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]CalibratorCalibrator object to save.
[in]FileNameFull path where to save the file to.
Returns

◆ 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]CalibratorCalibrator object to save.
[in]FileNameFull path where to save the file to.
Returns