M3dimFindTransformation

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

Find the transformation between 2 sets of points.

Syntax

void M3dimFindTransformation(
    AIL_ID    FindTransformationContext3dimId,  //in
    AIL_ID    SourceContainerOrArrayBufId,      //in
    AIL_ID    TargetContainerOrArrayBufId,      //in
    AIL_ID    Result3dimOrMatrix3dgeoId,        //out
    AIL_INT64 ControlFlag                       //in
)

Description

This function finds the rigid or affine transformation between the source and target sets of points. Aurora Imaging Library finds the transformation matrix A such that A * source (as per M3dimMatrixTransform) best approximates the target. Specifically, the transformation minimizes the squared error between pairs of points. Source[x, y] is compared with Target[x, y]. Accordingly, this function works only when you know a specific pairing between the source and target points (for example, through feature extraction). For a function that finds an alignment but does not require an exact pairing, see M3dregCalculate. Results are stored in the specified result buffer or transformation matrix object. To retrieve the matrix from a result buffer, use M3dimCopyResult with M_TRANSFORMATION_MATRIX.

The source and target can be both containers or both Aurora Imaging Library array buffers (M_ARRAY), or any combination of the two. Note that only pairs with 2 valid points are considered. For an Aurora Imaging Library array buffer, all points are valid; for a container, points are valid if their corresponding confidence score is non-zero.

For this function to succeed, at least 3 non-collinear point pairs are required for a rigid transformation, and at least 4 non-coplanar point pairs are required for an affine transformation. If the operation fails, M3dimGetResult with M_STATUS returns M_NOT_ENOUGH_POINT_PAIRS, M_ALL_POINTS_COPLANAR, or M_NOT_INITIALIZED, and the zero matrix is returned. Note that attempting to use the zero matrix in functions such as M3dimMatrixTransform will cause an error. To verify that the matrix is a valid rigid or affine transformation and not the zero matrix, call M3dgeoInquire with M_RIGID or M_AFFINE (respectively) and ensure that the function returns M_TRUE.

Parameters

FindTransformationContext3dimId (in, AIL_ID)

Specifies the identifier of a find transformation 3D image processing context.

For specifying the find transformation 3D image processing context identifier

Value	Description
M_FIND_TRANSFORMATION_CONTEXT_AFFINE	Specifies to find an affine transformation between the source and target sets of points. You should use this mode when one set of points (either source or target) originates from an uncalibrated source, which might contain a distortion such as a shear.

Note: Note that this mode requires at least 4 non-coplanar point pairs. | | M_FIND_TRANSFORMATION_CONTEXT_RIGID | Specifies to find a rigid transformation between the source and target sets of points. You should use this mode when the two sets of points (source and target) differ by a physical displacement in three dimensions (for example, a rotation and/or translation).

Note: Note that this mode requires at least 3 non-collinear point pairs. |

SourceContainerOrArrayBufId (in, AIL_ID)

Specifies the identifier of the source container containing a 3D-processable point cloud, or specifies the identifier of the source Aurora Imaging Library array buffer.

TargetContainerOrArrayBufId (in, AIL_ID)

Specifies the identifier of the target container containing a 3D-processable point cloud, or specifies the identifier of the target Aurora Imaging Library array buffer.

Result3dimOrMatrix3dgeoId (out, AIL_ID)

Specifies the identifier of the find transformation 3D image processing result buffer or transformation matrix object in which to store the calculated transformation matrix.

ControlFlag (in, AIL_INT64)

Reserved for future expansion and must be set to M_DEFAULT.