Skip to main content

M3dregGetResult

BoardSupported
Host SystemYes
V4L2Yes
Clarity UHDYes
Concord PoENo
GenTLYes
GevIQYes
GigE VisionYes
IndioNo
Iris GTXYes
Radient eV-CLYes
Rapixo CLYes
Rapixo CoFYes
Rapixo CXPYes
USB3 VisionYes

Get the specified type of result from a pairwise 3D registration result buffer.

Syntax​

AIL_DOUBLE M3dregGetResult(
    AIL_ID    Result3dregId,  //in
    AIL_INT64 ResultIndex,    //in
    AIL_INT64 ResultType,     //in
    void *    ResultArrayPtr  //out
)

Description​

This function retrieves results of the specified type from a pairwise 3D registration result buffer. The pairwise 3D registration result buffer contains registration result elements, each of which stores the registration results of M3dregCalculate for each individual point cloud.

To retrieve the transformation matrices, images, or subsampled point clouds generated by M3dregCalculate, use M3dregCopyResult.

By default, M3dregGetResult returns the final results of the registration operation. To retrieve the results of an intermediate iteration in the registration operation, use M3dregControlwith M_ITERATION_INDEX to specify for which iteration to retrieve results; then, when calling M3dregGetResult, combine the required result type (ResultType) with M_INTERMEDIATE_ITERATION. To retrieve the results of all iterations in the registration operation, combine the required result type (ResultType) with M_ALL_ITERATIONS.

Parameters​

Result3dregId (in, AIL_ID)​

Specifies the identifier of the pairwise 3D registration result buffer, previously allocated using M3dregAllocResult with M_PAIRWISE_REGISTRATION_RESULT.

ResultIndex (in, AIL_INT64)​

Specifies the registration result element for which to retrieve results. This parameter must be set to one of the following values:

For specifying the registration element index of a result

ValueDescription
M_ALLSpecifies to retrieve results from all registration result elements in the pairwise 3D registration result buffer.
M_GENERALSpecifies to retrieve general results from the pairwise 3D registration result buffer.
0 <= Value < M_NUMBER_OF_REGISTRATION_ELEMENTSSpecifies the index of the registration result element from which to retrieve results.

ResultType (in, AIL_INT64)​

Specifies the type of result to get.

ResultArrayPtr *(out, void)​

Specifies the address in which to write the results.

Parameter Associations​

For retrieving general results from a pairwise 3D registration result buffer, where​

To retrieve general results from a pairwise 3D registration result buffer, set ResultIndex to M_GENERAL, and ResultType should be set to one of the following values:

M_NUMBER_OF_REGISTRATION_ELEMENTS​

Retrieves the number of registration result elements in the pairwise 3D registration result buffer.

M_SAVE_PAIRS_INFO​

Retrieves whether point pair information has been saved into the pairwise 3D registration result buffer. Point pair information is necessary to copy results into an image buffer or container (for example, to create a distance image using M3dregCopyResult with M_DISTANCE_IMAGE). Point pair information is only saved if M3dregControl with M_SAVE_PAIRS_INFO is set to M_TRUE.

ValueDescription
M_FALSESpecifies that point pair information has not been saved.
M_TRUESpecifies that point pair information has been saved.

M_SET_LOCATION_REFERENCE​

Retrieves the index of the reference registration element, as set using M3dregSetLocation when setting the rough location of a point cloud's working coordinate system.

ValueDescription
M_REGISTRATION_GLOBALSpecifies the global coordinate system.
0 <= Value < M3dregGetResult(M_NUMBER_OF_REGISTRATION_ELEMENTS)Specifies the index of the reference registration element.

M_STATUS​

Retrieves the global status of the last M3dregCalculate operation.

ValueDescription
M_COMPLETESpecifies that the registration result is available.
M_CURRENTLY_CALCULATINGSpecifies that the registration operation is ongoing.
M_EMPTYSpecifies that the result buffer is empty.
M_INTERNAL_ERRORSpecifies that an unexpected internal error occurred during the registration operation.
M_NOT_ENOUGH_MEMORYSpecifies that the registration operation was not completed because of a lack of available memory.
M_STOPPED_BY_REQUESTSpecifies that the registration operation was stopped from another thread using M3dregControl with M_STOP_CALCULATE.
M_TIMEOUT_REACHEDSpecifies that the registration operation took longer than the allowed value, specified using M3dregControl with M_TIMEOUT, and has stopped before completion.

For retrieving results from a 3D pairwise registration result buffer, where​

To retrieve results from the registration result elements of a pairwise 3D registration result buffer, set ResultType to one of the following values, and set the ResultIndex parameter to the index of a registration result element, or to M_ALL (to retrieve the results of all registration result elements). Setting ResultIndex to M_ALL will return an array where each element contains the results of each registration result element.

M_MAX_PAIRS_RANK​

Retrieves the maximum possible pair rank for the registration element at the specified iteration index (set using M3dregControl with M_ITERATION_INDEX). When there are reference points paired to multiple points in the registration result element's point cloud, M_MAX_PAIRS_RANK returns the maximum number of points to which they are paired. You can then specify M3dregControl with M_PAIRS_RANK to establish from which pair's results to copy when using M3dregCopyResult to create a distance, overlap, or pair index image.

M_NB_ITERATIONS​

Retrieves the number of iterations performed during the pairwise 3D registration operation. This always includes the preregistration step, which is the first iteration of the registration operation.

M_REGISTRATION_COMPLETED​

Specifies whether the registration has successfully completed. This is a similar, but simpler, version of M_STATUS_REGISTRATION_ELEMENT.

ValueDescription
M_FALSESpecifies that the registration has not successfully completed.
M_TRUESpecifies that the registration has successfully completed.

M_RESULT_IMAGE_SIZE_X​

Retrieves the size in X of the reference point cloud's range component. You can use this value to allocate an image buffer of the correct size when retrieving a result image created using M3dregCopyResult with M_OVERLAP_MASK, M_DISTANCE_IMAGE, or M_PAIR_INDEX_IMAGE. > Note: Note that the size is available after an M3dregCalculate operation. If you have enabled subsampling, M_RESULT_IMAGE_SIZE_X will return the size in X of the subsampled container's range component.

M_RESULT_IMAGE_SIZE_Y​

Retrieves the size in Y of the reference point cloud's range component. You can use this value to allocate an image buffer of the correct size when retrieving a result image created using M3dregCopyResult with M_OVERLAP_MASK, M_DISTANCE_IMAGE, or M_PAIR_INDEX_IMAGE. > Note: Note that the size is available after an M3dregCalculate operation. If you have enabled subsampling, M_RESULT_IMAGE_SIZE_Y will return the size in Y of the subsampled container's range component.

M_RMS_ERROR​

Specifies the root-mean-square (RMS) error. Retrieves the RMS error calculated using the distance measured between paired points in two point clouds. How this distance is measured is set using M3dregControl with M_ERROR_MINIMIZATION_METRIC. A value of 0.0 implies that all points in the first point cloud perfectly overlap with the points in the second point cloud.

M_RMS_ERROR_RELATIVE​

Specifies the relative RMS error. The relative RMS error is the percentage change in the RMS error of the last two iterations of the pairwise 3D registration operation. Specifically, where _Ei _ is the RMS error of iteration i, the relative RMS error is calculated as: [(_Ei-1 _ - _Ei _)/_Ei-1 _]*100%. For instance, if the RMS error of the first iteration is 2.0 and the RMS error of the second iteration is 0.8, the relative RMS error of the second iteration is equal to [(2.0-0.8)/2.0]*100, which is 60%. If the relative RMS error is positive, this means the RMS error is decreasing, and the point clouds are becoming increasingly aligned. > Note: Note that the value returned represents a percentage. A value of 0.1 represents 0.1%, and not 10%.

M_STATUS_REGISTRATION_ELEMENT​

Retrieves a status result from one, or all, pairwise registration result elements. If a result has multiple statuses, the status that is returned depends on the following order of precedence: M_RMS_ERROR_THRESHOLD_REACHED, M_RMS_ERROR_RELATIVE_THRESHOLD_REACHED, M_MAX_ITERATIONS_REACHED.

ValueDescription
M_EMPTYSpecifies that there are no results from the registration operation.
M_MAX_ITERATIONS_REACHEDSpecifies that a stop condition has been met, and that the maximum number of iterations has been met. You can inquire what the maximum number of iterations is by calling M3dregInquire with M_MAX_ITERATIONS. > Note: Note that this status implies that, for this registration result element in the result buffer, M_REGISTRATION_COMPLETED returns M_TRUE.
M_NO_VALID_POINTSSpecifies that there were no viable points for use in the registration operation.
M_NOT_ENOUGH_POINT_PAIRSSpecifies that there are not enough point pairs to use in the registration operation.
M_REGISTRATION_GLOBALSpecifies that the registration element uses the global coordinate system as its reference. > Note: Note that this status implies that, for this registration result element in the result buffer, M_REGISTRATION_COMPLETED returns M_TRUE.
M_RMS_ERROR_RELATIVE_THRESHOLD_REACHEDSpecifies that a stop condition has been met, and that the relative RMS error threshold has been met. You can inquire what the threshold is by calling M3dregInquire with M_RMS_ERROR_RELATIVE_THRESHOLD. You can get the RMS error and relative RMS error using M3dregGetResult with M_RMS_ERROR and M_RMS_ERROR_RELATIVE, respectively. > Note: Note that this status implies that, for this registration result element in the result buffer, M_REGISTRATION_COMPLETED returns M_TRUE.
M_RMS_ERROR_THRESHOLD_REACHEDSpecifies that a stop condition has been met, and that the RMS error threshold has been met. You can inquire what the threshold is by calling M3dregInquire with M_RMS_ERROR_THRESHOLD. You can get the RMS error and relative RMS error using M3dregGetResult with M_RMS_ERROR and M_RMS_ERROR_RELATIVE, respectively. > Note: Note that this status implies that, for this registration result element in the result buffer, M_REGISTRATION_COMPLETED returns M_TRUE.

Combination Constants — For specifying to retrieve the result for each iteration, or only for an intermediate iteration​

Optional.

Usage: You can add one of the following values to the above-mentioned values to determine the result for all iterations, or only for an intermediate iteration.

M_ALL_ITERATIONS​

Specifies to retrieve the result for each iteration during the pairwise 3D registration operation.

M_INTERMEDIATE_ITERATION​

Specifies to retrieve the result for an intermediate iteration of the pairwise 3D registration operation. You can specify which intermediate iteration to retrieve results from using M3dregControl with M_ITERATION_INDEX.

Combination Constants — For determining whether results are available​

Optional.

Usage: You can add one of the following values to the above-mentioned values to determine whether a result is available.

M_AVAILABLE​

Retrieves whether the requested result type is available for retrieval.

ValueDescription
M_FALSESpecifies that the requested result type is not available.
M_TRUESpecifies that the requested result type is available.

Combination Constants — For determining the required array size (number of elements) to store the returned values​

Optional, cannot be used alone.

Usage: You can add one of the following values to the above-mentioned values to determine the required array size (number of elements) to store the returned values.

M_NB_ELEMENTS​

Retrieves the required array size (number of elements) to store the returned values.

Combination Constants — For specifying the data type​

Optional.

Usage: You can add one of the following values to the above-mentioned values to cast the requested results to the required data type.

M_TYPE_AIL_DOUBLE​

Casts the requested results to an AIL_DOUBLE.

M_TYPE_AIL_FLOAT​

Casts the requested results to an AIL_FLOAT.

M_TYPE_AIL_INT​

Casts the requested results to an AIL_INT.

M_TYPE_AIL_INT32​

Casts the requested results to an AIL_INT32.

M_TYPE_AIL_INT64​

Casts the requested results to an AIL_INT64.

Return Value​

Type: AIL_DOUBLE

The returned value is the requested information, cast to an AIL_DOUBLE. If the requested information does not fit into an AIL_DOUBLE, this function will return M_NULLor truncate the information.

Copyright © 2026 Zebra Technologies.