Filters
Filter values by
  • Status results
| Customize Help
| Save Settings

M3dregGetResult


Function Map
Syntax
Description
Parameters
- Result3dregId
- ResultIndex
Table: For specifying the registration element index of a result
- ResultType
- ResultArrayPtr
Parameter Associations
Table: For retrieving a status from a pairwise 3D registration result buffer, where ResultIndex is set to M_GENERAL
Table: For retrieving results from a 3D pairwise registration result buffer, where ResultIndex is set to an index value or M_ALL
+ combination: For specifying to retrieve the result for each iteration, or only for an intermediate iteration
+ combination: For determining whether results are available
+ combination: For determining the required array size (number of elements) to store the returned values
+ combination: For specifying the data type
Return value
Compilation information
Synopsis
Get the specified type of result from a pairwise 3D registration result buffer.
Syntax
MIL_DOUBLE M3dregGetResult(
MIL_ID Result3dregId, //in
MIL_INT64 ResultIndex, //in
MIL_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 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 M3dregControl() with 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.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see if there is complementary information.
Parameters
This function is not supported on the selected boards.
Parameters
Result3dregId

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

ResultIndex

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

function map For specifying the registration element index of a result
Click to summarizeValue Description
Click to summarize M_ALL

Specifies to retrieve results from all registration result elements in the pairwise 3D registration result buffer.
Click to summarize M_GENERAL

Specifies to retrieve general results from the pairwise 3D registration result buffer.
Click to summarize 0 <= Value <
M_NUMBER_OF_REGISTRATION_ELEMENTS

Specifies the index of the registration result element from which to retrieve results.
ResultType

Specifies the type of result to get.

See the Parameter associations section for possible values that can be specified.

ResultArrayPtr
Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):
  • array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]
  • array of type MIL_FLOAT [optionally, in C++: a reference to a std::vector<MIL_FLOAT> ]
  • array of type MIL_INT [optionally, in C++: a reference to a std::vector<MIL_INT> ]
  • array of type MIL_INT32 [optionally, in C++: a reference to a std::vector<MIL_INT32> ]
  • array of type MIL_INT64 [optionally, in C++: a reference to a std::vector<MIL_INT64> ]
  • MIL_DOUBLE
  • MIL_FLOAT
  • MIL_INT
  • MIL_INT32
  • MIL_INT64

Specifies the address in which to write the results.

See the Parameter associations section for possible values that can be returned.

Parameter associations

The tables below list possible values for the ResultType parameter and possible values returned to the ResultArrayPtr parameter.

To retrieve status results from a pairwise 3D registration result buffer, set ResultIndex to M_GENERAL, and ResultType should be set to the following value:

function map For retrieving a status from a pairwise 3D registration result buffer, where ResultIndex is set to M_GENERAL
Click to summarize
ResultType		 Description
ResultArrayPtr
- Possible values returned
Click to summarize M_STATUS +

Retrieves the global status of the last M3dregCalculate() operation.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_INT MORE
Click to summarize M_COMPLETE

Specifies that the registration result is available.
Click to summarize M_CURRENTLY_CALCULATING

Specifies that the registration operation is ongoing.
Click to summarize M_EMPTY

Specifies that the result buffer is empty.
Click to summarize M_INTERNAL_ERROR

Specifies that an unexpected internal error occurred during the registration operation.
Click to summarize M_NOT_ENOUGH_MEMORY

Specifies that the registration operation was not completed because of a lack of available memory.
Click to summarize M_STOPPED_BY_REQUEST

Specifies that the registration operation was stopped from another thread using M3dregControl() with M_STOP_CALCULATE.
Click to summarize M_TIMEOUT_REACHED

Specifies that the registration operation took longer than the allowed value, specified using M3dregControl() with M_TIMEOUT, and has stopped before completion.

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.

function map For retrieving results from a 3D pairwise registration result buffer, where ResultIndex is set to an index value or M_ALL
Click to summarize
ResultType		 Description
ResultArrayPtr
- Possible values returned
Click to summarize 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.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_INT
Click to summarize M_REGISTRATION_COMPLETED +

Specifies whether the registration has successfully completed.

This is a similar, but simpler, version of M_STATUS_REGISTRATION_ELEMENT.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_INT
Click to summarize M_FALSE

Specifies that the registration has not successfully completed.
Click to summarize M_TRUE

Specifies that the registration has successfully completed.
Click to summarize 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.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE
Click to summarize 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 that the value returned represents a percentage. A value of 0.1 represents 0.1%, and not 10%.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE
Click to summarize 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.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_INT  |  array of type MIL_INT [optionally, in C++: a reference to a std::vector<MIL_INT> ] MORE
Click to summarize M_EMPTY

Specifies that there are no results from the registration operation.
Click to summarize M_MAX_ITERATIONS_REACHED

Specifies 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 that this status implies that, for this registration result element in the result buffer, M_REGISTRATION_COMPLETED returns M_TRUE.

(summarize)
Click to summarize M_NO_VALID_POINTS

Specifies that there were no viable points for use in the registration operation.
Click to summarize M_NOT_ENOUGH_POINT_PAIRS

Specifies that there are not enough point pairs to use in the registration operation.
Click to summarize M_REGISTRATION_GLOBAL

Specifies that the registration element uses the global coordinate system as its reference.

Note that this status implies that, for this registration result element in the result buffer, M_REGISTRATION_COMPLETED returns M_TRUE.

(summarize)
Click to summarize M_RMS_ERROR_RELATIVE_THRESHOLD_REACHED

Specifies 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 that this status implies that, for this registration result element in the result buffer, M_REGISTRATION_COMPLETED returns M_TRUE.

(summarize)
Click to summarize M_RMS_ERROR_THRESHOLD_REACHED

Specifies 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 that this status implies that, for this registration result element in the result buffer, M_REGISTRATION_COMPLETED returns M_TRUE.

(summarize)
Combination values for M_RMS_ERROR; M_RMS_ERROR_RELATIVE.

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.

function map For specifying to retrieve the result for each iteration, or only for an intermediate iteration
Click to summarizeResultType Description
ResultArrayPtr
- Possible values returned
Click to summarize M_ALL_ITERATIONS +

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

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ] MORE
Click to summarize 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.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_INT
Combination value for the values listed in For retrieving a status from a pairwise 3D registration result buffer, where ResultIndex is set to M_GENERAL; the values listed in For retrieving results from a 3D pairwise registration result buffer, where ResultIndex is set to an index value or M_ALL.

You can add the following value to the above-mentioned values to determine whether a result is available.

function map For determining whether results are available
Click to summarizeResultType Description
ResultArrayPtr
- Possible values returned
Click to summarize M_AVAILABLE

Retrieves whether a result is available to be returned.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_INT
Click to summarize M_NULL

Specifies that the result is not available to be returned.
Click to summarize Value != 0

Specifies that the result is available to be returned.
Combination value for M_ALL_ITERATIONS; M_STATUS_REGISTRATION_ELEMENT.

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

function map For determining the required array size (number of elements) to store the returned values
Click to summarizeResultType combination value Description
ResultArrayPtr
- Possible values returned
Click to summarize M_NB_ELEMENTS

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

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_INT
Combination values for the values listed in For retrieving a status from a pairwise 3D registration result buffer, where ResultIndex is set to M_GENERAL; the values listed in For retrieving results from a 3D pairwise registration result buffer, where ResultIndex is set to an index value or M_ALL.

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

Note: In C++, when using a standard vector (std::vector) instead of an array, the values listed in this combination table must not be used. If you need to use a specific data type, instantiate the vector with the necessary data type.

function map For specifying the data type
Click to summarizeResultType Description
ResultArrayPtr
- Possible values returned
Click to summarize M_TYPE_MIL_DOUBLE

Casts the requested results to a MIL_DOUBLE.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_DOUBLE [optionally, in C++: a reference to a std::vector<MIL_DOUBLE> ]  |  address of a MIL_DOUBLE MORE
Click to summarize M_TYPE_MIL_FLOAT

Casts the requested results to a MIL_FLOAT.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_FLOAT [optionally, in C++: a reference to a std::vector<MIL_FLOAT> ]  |  address of a MIL_FLOAT MORE
Click to summarize M_TYPE_MIL_INT

Casts the requested results to a MIL_INT.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_INT [optionally, in C++: a reference to a std::vector<MIL_INT> ]  |  address of a MIL_INT MORE
Click to summarize M_TYPE_MIL_INT32

Casts the requested results to a MIL_INT32.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_INT32 [optionally, in C++: a reference to a std::vector<MIL_INT32> ]  |  address of a MIL_INT32 MORE
Click to summarize M_TYPE_MIL_INT64

Casts the requested results to a MIL_INT64.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: array of type MIL_INT64 [optionally, in C++: a reference to a std::vector<MIL_INT64> ]  |  address of a MIL_INT64 MORE
Return value
The returned value is the requested information, cast to a MIL_DOUBLE. If the requested information does not fit into a MIL_DOUBLE, this function will return M_NULL or truncate the information.
Compilation information
Header Include mil.h.
Library Use mil.lib; mil3dreg.lib.
DLL Requires mil.dll; mil3dreg.dll.
ALL GENERAL NUMBER OF REGISTRATION ELEMENTS STATUS COMPLETE CURRENTLY CALCULATING EMPTY INTERNAL ERROR NOT ENOUGH MEMORY STOPPED BY REQUEST TIMEOUT REACHED NB ITERATIONS REGISTRATION COMPLETED FALSE TRUE RMS ERROR RMS ERROR RELATIVE STATUS REGISTRATION ELEMENT EMPTY MAX ITERATIONS REACHED NO VALID POINTS NOT ENOUGH POINT PAIRS REGISTRATION GLOBAL RMS ERROR RELATIVE THRESHOLD REACHED RMS ERROR THRESHOLD REACHED ALL ITERATIONS INTERMEDIATE ITERATION AVAILABLE NULL NB ELEMENTS TYPE MIL DOUBLE TYPE MIL FLOAT TYPE MIL INT TYPE MIL INT32 TYPE MIL INT64 ALL ALL