M3dmapAlignScan

Board	Supported
Host System	Yes
V4L2	Yes
Clarity UHD	Yes
Concord PoE	No
GenTL	Yes
GevIQ	Yes
GigE Vision	Yes
Indio	No
Iris GTX	Yes
Radient eV-CL	Yes
Rapixo CL	Yes
Rapixo CoF	Yes
Rapixo CXP	Yes
USB3 Vision	Yes

Calculates the transformations and information necessary to calibrate a 3D profile sensor.

Syntax

void M3dmapAlignScan(
    AIL_ID    AlignContext3dmapId,  //in
    AIL_ID    ContainerBufId,       //in
    AIL_ID    AlignResult3dmapId,   //out
    AIL_INT64 ControlFlag           //in
)

Description

This function calculates the transformations necessary to calibrate your 3D profile sensor using an alignment object that was specified using M3dmapControl with M_OBJECT_SHAPE.

This function uses a point cloud of an alignment object, with expected markings and constraints, to establish the transformations and information necessary to calibrate the 3D sensor that transmitted the point cloud. The calibration, when applied to the data transmitted by the 3D sensor, corrects the data so that the alignment object is represented correctly.

To retrieve the calculated sensor data, use M3dmapGetResult and M3dmapCopyResult. The sensor data includes values such as M_SENSOR_PITCH, M_SENSOR_PITCH_BEFORE_YAW, M_SENSOR_YAW, M_SENSOR_YAW_BEFORE_PITCH, M_3D_SHEAR_X, M_3D_SHEAR_Z, and M_3D_SCALE_Y.

You must use M3dmapControl with M_OBJECT_SHAPE set to M_PYRAMID, M_DISK, or M_FLAT_SURFACE prior to calling this function. When using an alignment pyramid or disk, certain constraints must be met. You must also specify the dimensions of your alignment object before calling M3dmapAlignScan.

• For an alignment disk (M_DISK):
  • You must specify the dimensions ofM_HEIGHT and M_DIAMETER using M3dmapControl before calling M3dmapAlignScan.
  • For information on the alignment disk constraints, see Alignment disk constraints and requirements.
• For an alignment pyramid (M_PYRAMID):
  • You must specify the dimensions ofM_HEIGHT, M_PYRAMID_BASE_LENGTH, and M_PYRAMID_TOP_FACE_LENGTH using M3dmapControl before calling M3dmapAlignScan.
  • For information on the alignment pyramid constraints, see Alignment pyramid constraints and requirements.

The following are the different ways to calibrate a 3D profile sensor with the calculated sensor data.

• You can use M3dimMatrixTransform to apply the calculated transformation matrix (M3dmapCopyResult with M_TRANSFORMATION_MATRIX) to point clouds acquired by the 3D profile sensor.
• You can use MbufConvert3d when converting the 3D sensor data to a format that is 3D-processable. To do so, prior to calling MbufConvert3d, set MbufControl with M_3D_SHEAR_X, M_3D_SCALE_Y, M_3D_SHEAR_Z to the values retrieved using M3dmapGetResult with M_3D_SHEAR_X, M_3D_SCALE_Y, M_3D_SHEAR_Z, respectively.
• You can pass the calculated results (such as pitch, yaw, and shear values) to a compatible 3D profile sensor (such as Zebra AltiZ) using MdigControlFeature. In this case, the 3D profile sensor will directly output calibrated scan lines.

Parameters

AlignContext3dmapId (in, AIL_ID)

Specifies the identifier of the 3D alignment context to use for the alignment operation. The context must have been previously allocated using M3dmapAlloc with M_ALIGN_CONTEXT.

ContainerBufId (in, AIL_ID)

Specifies the identifier of the 3D-processable point cloud container that stores the point cloud of the alignment object.

AlignResult3dmapId (out, AIL_ID)

Specifies the identifier of the 3D alignment result buffer in which to store results. The result buffer must have been previously allocated using M3dmapAllocResult with M_ALIGN_RESULT.

ControlFlag (in, AIL_INT64)

Reserved for future expansion and must be set to M_DEFAULT.