MIL_ID ContextOrResult3dregId, | //in |
MIL_INT64 Index, | //in |
MIL_INT64 ControlType, | //in |
MIL_DOUBLE ControlValue | //in |
This function controls the settings of a pairwise 3D registration context, one of its registration elements, or a pairwise 3D registration result buffer. These settings specify how to start and stop the registration operation (preregistration and stop conditions), and how M3dregCalculate() performs the pairwise comparison of points.
To inquire about these control type settings, call M3dregInquire().
Specifies the identifier of the pairwise 3D registration context or a pairwise 3D registration result buffer to control. The pairwise 3D registration context must be allocated using M3dregAlloc(), and the pairwise 3D registration result buffer must be allocated using M3dregAllocResult().
Specifies what to control. Set this parameter to one of the following values:
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description | ||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the default behavior. If ContextOrResult3dregId specifies a pairwise 3D registration context, then M_DEFAULT is the same as M_CONTEXT. If ContextOrResult3dregId specifies a pairwise 3D registration result buffer, then M_DEFAULT is the same as M_GENERAL. (summarize)Specifies the default behavior. (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies to apply the control settings to all registration elements of a pairwise 3D registration context or all registration result elements of a pairwise 3D registration result buffer. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies to apply the control settings to a pairwise 3D registration context. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies to apply the control settings to a pairwise 3D registration result buffer. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() M3dregInquire(M_NUMBER_OF_REGISTRATION_ELEMENTS) |
Specifies the index of the registration element or registration result element to apply the control settings. |
Specifies the setting to change.
See the Parameter associations section for possible values that can be specified.
Specifies the setting's new value.
See the Parameter associations section for possible values that can be specified.
The tables below list possible values for the ControlType and ControlValue parameters.
The following ControlType and corresponding ControlValue parameter settings are used to control the pairwise 3D registration context specified with the ContextOrResult3dregId parameter. Index must be set to M_CONTEXT.
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description | ||||||||||||||||||||||||||||||||||||||
ControlValue | |||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets the technique for performing the pairwise comparison during each iteration of the registration operation, and establishes how to compute the RMS error. In each iteration, points in the reference point cloud are paired with the closest points in the other point cloud. The points are always paired in the same manner (independent of the setting of M_ERROR_MINIMIZATION_METRIC). Once paired, the RMS error is calculated using the specified distance measurement or error metric. The best technique for a given registration depends on how many large and flat surfaces the object represented by the point cloud has. Using the correct setting can help avoid registration sliding (when multiple different registration are possible because of large planar surfaces) or diverging (when the registration operation results in the point clouds moving apart). INQ (summarize)Sets the technique for performing the pairwise comparison during each iteration of the registration operation, and establishes how to compute the RMS error. INQ (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Same as M_POINT_TO_PLANE. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies to calculate the RMS error using the shortest distance between the point (in the reference point cloud), and the plane tangent to the other paired point. The tangent plane is calculated using the normal of the latter point. ![]() This setting improves the speed of registering organized point clouds, where the normal at a given point is not similar to the normal at nearby points. This implies that the object represented by the point cloud has a large range of surface directions, and no relatively large flat surfaces. Large surfaces can result in the registration sliding or diverging. (summarize)Specifies to calculate the RMS error using the shortest distance between the point (in the reference point cloud), and the plane tangent to the other paired point. (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies to calculate the RMS error using the distance between the paired points. ![]() This setting is better suited to registering point clouds that represent objects with large planar surfaces, and will avoid registration sliding or diverging. (summarize)Specifies to calculate the RMS error using the distance between the paired points. (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets a stop condition for the iterative registration operation. If the maximum number of iterations is reached, the registration operation stops. To inquire whether this stop condition was met, call M3dregGetResult() with M_STATUS. Note that preregistration constitutes the first iteration. INQ (summarize)Sets a stop condition for the iterative registration operation. INQ (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the default value; the default value is 20. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the maximum number of iterations in the registration process. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets the number of registration elements in the pairwise 3D registration context. The number of registration elements should be equal to, or greater than, the number of point clouds to register. If you reduce the number of registration elements, the settings of the ones that remain are kept unchanged. If you increase the number of registration elements, the new ones are initialized with the default settings. INQ (summarize)Sets the number of registration elements in the pairwise 3D registration context. INQ (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the default value; the default value is 2. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the number of registration elements in a pairwise 3D registration context. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets how to perform the preregistration step. INQ (summarize)Sets how to perform the preregistration step. INQ (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Same as M_USER_DEFINED. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies to apply the preregistration transformation matrix, specified using M3dregSetLocation(); it then automatically registers the centroids (center of mass) of the two point clouds. By default, the registration of the centroids is a translation only and does not include any rotation. To only register the centroids, you can specify the identity matrix as the transformation matrix of the preregistration; to do so, call M3dregSetLocation() with M_IDENTITY_MATRIX. Alternatively, you can delegate the translation to the centroid registration, and define the rotation using a user-defined transformation matrix specified using M3dregSetLocation(). (summarize)Specifies to apply the preregistration transformation matrix, specified using M3dregSetLocation(); it then automatically registers the centroids (center of mass) of the two point clouds. (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies to apply the preregistration transformation matrix in the first iteration of the registration operation. Specify the transformation matrix using M3dregSetLocation(). (summarize)Specifies to apply the preregistration transformation matrix in the first iteration of the registration operation. (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets the stop condition for the registration operation that tests the percentage change of the root-mean-square (RMS) error of successive iterations. The RMS error is calculated from the distance between all paired points. You can control how the distance is calculated using M_ERROR_MINIMIZATION_METRIC. 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. If the change in the calculated RMS error between successive iterations is less than or equal to the specified value, the registration operation stops. If this stop condition is met, the registration is typically considered correct. Note that the specified value represents a percentage, so the default value of 0.1 represents 0.1%, not 10%. INQ (summarize)Sets the stop condition for the registration operation that tests the percentage change of the root-mean-square (RMS) error of successive iterations. INQ (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the default value; the default value is 0.1. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the relative RMS error threshold. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets the stop condition for the registration operation that tests the root-mean-square (RMS) error of successive iterations. The RMS error is calculated from the distance between all paired points. You can control how the distance is calculated using M_ERROR_MINIMIZATION_METRIC. This value should be set to an acceptable average RMS error for a pair of points. If the calculated RMS error goes under or equals the specified value, the registration operation stops. If this stop condition is met, the registration is typically considered correct. INQ (summarize)Sets the stop condition for the registration operation that tests the root-mean-square (RMS) error of successive iterations. INQ (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the default value; the default value is 0.0. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the RMS error threshold. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets whether to enable subsampling before applying the registration. Settings for subsampling techniques are defined in a subsampling context. Every registration context contains a subsampling context. To change the settings of the subsampling context, call M3dregInquire() with M_SUBSAMPLE_CONTEXT_ID to first get the MIL identifier of the subsampling context. The subsampling context can then be controlled using M3dimControl() (see the settings available for Subsample context ID). INQ (summarize)Sets whether to enable subsampling before applying the registration. INQ (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Same as M_DISABLE. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies to disable subsampling before applying the registration. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies to enable subsampling before applying the registration. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets the maximum amount of time for M3dregCalculate() to complete the registration operation before generating a time-out error. (summarize)Sets the maximum amount of time for M3dregCalculate() to complete the registration operation before generating a time-out error. (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Same as M_DISABLE. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies that there is no timeout value. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the timeout value, in msec. |
The following ControlType and corresponding ControlValue parameter settings are used to control the registration result elements of the pairwise 3D registration context specified with the ContextOrResult3dregId parameter. Index must be set to an index value or M_ALL:
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description | ||||||||||||||||||||||||||||||||||||||
ControlValue | |||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets the percentage of point pairings to use in a single iteration of the registration operation. At the start of an iteration, the points of the reference point cloud are individually paired with the closest points in the other point cloud. M_OVERLAP specifies the percentage of those paired points that are used in the registration operation, prioritizing the paired points with the lowest RMS error. For example, if you specify 80%, then during each iteration, 80% of paired points (with the lowest calculated RMS error as defined by M_ERROR_MINIMIZATION_METRIC) are used to calculate the average RMS error of the iteration, and a new transformation. This excludes the 20% worst point pairings, which often contain outliers in the reference point cloud. These outliers are typically caused by image noise, occlusion, object deformity, or misalignment. Typically, if there are fewer points in the reference point cloud than in the point cloud that will be registered to it, the overlap should roughly equal the ratio of the points in the reference point cloud to the points in the other point cloud. If the density of points is the same in both point clouds, this ratio could be set to the exact ratio between the two. For example, if there are 100 points in the reference point cloud, 200 points in the point cloud that will be registered to it, and they have a similar density, then the overlap can be set to 50%. This can occur because of occlusion of the object while generating the scene point cloud. If there are more points in the reference point cloud, this value should be set to a little under 100%. In this case, it is recommended that you use as many of the points in the reference point cloud as possible while still accounting for outliers. INQ (summarize)Sets the percentage of point pairings to use in a single iteration of the registration operation. INQ (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the default value; the default value is 80.0. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the percentage of possible paired points included in each iteration of the registration operation. |
The following ControlType and corresponding ControlValue parameter settings are used to control the registration elements of the pairwise 3D result buffer specified with the ContextOrResult3dregId parameter. Index must be set to an index value or M_ALL.
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description | ||||||||||||||||||||||||||||||||||||||
ControlValue | |||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Sets the index of the iteration from which to copy the transformation matrix, or get results. This setting is used by the M_INTERMEDIATE_ITERATION combination value in functions like M3dregCopyResult() and M3dregGetResult() to retrieve results from intermediate iterations, and is useful when you want to debug the registration operation or understand it in greater detail. INQ (summarize)Sets the index of the iteration from which to copy the transformation matrix, or get results. INQ (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Same as M_LAST_ITERATION. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the index of the final iteration of the registration process. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the index of the iteration from which to copy the transformation matrix or get results. |
The following ControlType and corresponding ControlValue parameter settings are used to control the pairwise 3D registration result buffer specified with the ContextOrResult3dregId parameter. Index must be set to M_GENERAL.
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description | ||||||||||||||||||||||||||||||||||||||
ControlValue | |||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Removes all results from the pairwise 3D registration result buffer. This does not delete the pairwise 3D registration result buffer, as is the case with M3dregFree(). (summarize)Removes all results from the pairwise 3D registration result buffer. (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the default behavior. |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Stops the current execution of M3dregCalculate() from another thread of higher priority. Any results from previous registrations become invalid and are discarded, and any completed results from the current registration operation will be available. (summarize)Stops the current execution of M3dregCalculate() from another thread of higher priority. (more details...) |
||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Specifies the default behavior. |
Header | Include mil.h. |
Library | Use mil.lib; mil3dreg.lib. |
DLL | Requires mil.dll; mil3dreg.dll. |