Filters
Filter values by
3D Geometry Object Restriction
  • 3D Cylinder Geometry Object Filter
  • 3D Plane Geometry Object Filter
  • 3D Line Geometry Object Filter
  • 3D Sphere Geometry Object Filter
| Customize Help
| Save Settings

M3dmetGetResult



Function Map
Synopsis
Get the specified type of result(s) from a 3D metrology result buffer.
Syntax
MIL_DOUBLE M3dmetGetResult(
MIL_ID Result3dmetId, //in
MIL_INT64 ResultType, //in
void *ResultArrayPtr //out
)
Description

This function retrieves the result(s) of the specified type from a 3D metrology result buffer. Results are available for fit 3D metrology result buffers after calling M3dmetFit(), and results are available for statistics 3D metrology result buffers after calling M3dmetStat().

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 which MIL system’s documentation you should use in its place and any possible differences.
Parameters
This function is not supported on the selected boards.
This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.
Parameters
Result3dmetId

Specifies the identifier of a fit 3D metrology result buffer or statistics 3D metrology result buffer, from which to retrieve results.

ResultType

Specifies the type of result to retrieve.

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):
  • MIL_DOUBLE
  • MIL_FLOAT
  • MIL_INT
  • MIL_INT32
  • MIL_INT64

Specifies the address in which to write the results. Since the M3dmetGetResult() function also returns the results, you can set this parameter to M_NULL.

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

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

To retrieve a result from an fit 3D metrology result buffer, the ResultType parameter can be set to one of the following values:

function map For retrieving results from a fit 3D metrology result buffer
Click to summarize
ResultType
Description
ResultArrayPtr
- Possible values returned
Click to summarize M_AXIS_X +

Retrieves the X-component of the fitted 3D geometry's unit vector.

If the fitted 3D geometry is a cylinder, the X-component of the cylinder's central axis unit vector is retrieved. This vector does not reflect the cylinder's length.

If the fitted 3D geometry is a line, the X-component of the line's direction unit vector is retrieved. This vector does not reflect the line's length.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE
Click to summarize -1.0 >= Value >= 1.0

Specifies the X-component of the unit vector, expressed in the working coordinate system.

Click to summarize M_AXIS_Y +

Retrieves the Y-component of the fitted 3D geometry's unit vector.

If the fitted 3D geometry is a cylinder, the Y-component of the cylinder's central axis unit vector is retrieved. This vector does not reflect the cylinder's length.

If the fitted 3D geometry is a line, the Y-component of the line's direction unit vector is retrieved. This vector does not reflect the line's length.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE
Click to summarize -1.0 >= Value >= 1.0

Specifies the Y-component of the unit vector, expressed in the working coordinate system.

Click to summarize M_AXIS_Z +

Retrieves the Z-component of the fitted 3D geometry's unit vector.

If the fitted 3D geometry is a cylinder, the Z-component of the cylinder's central axis unit vector is retrieved. This vector does not reflect the cylinder's length.

If the fitted 3D geometry is a line, then the Z-component of the line's direction unit vector is retrieved. This vector does not reflect the line's length.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE
Click to summarize -1.0 >= Value >= 1.0

Specifies the Z-component of the unit vector, expressed in the working coordinate system.

Click to summarize M_CENTER_X +

Retrieves the X-coordinate of the center point of the fitted 3D geometry, expressed in the working coordinate system.

If the fitted 3D geometry is a cylinder, the X-coordinate of the center point on the cylinder's central axis is retrieved.

If the fitted 3D geometry is a line, the X-coordinate of the center point on the line is retrieved.

If the fitted 3D geometry is a plane, the X-coordinate of the plane's center is retrieved. This center point is equivalent to the centroid of all inlier points.

If the fitted 3D geometry is a sphere, the X-coordinate of the sphere's center point is retrieved.

(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_CENTER_Y +

Retrieves the Y-coordinate of the center point of the fitted 3D geometry expressed in the working coordinate system.

If the fitted 3D geometry is a cylinder, the Y-coordinate of the center point on the cylinder's central axis is retrieved.

If the fitted 3D geometry is a line, the Y-coordinate of the center point on the line is retrieved.

If the fitted 3D geometry is a plane, the Y-coordinate of the plane's center is retrieved. This center point is equivalent to the centroid of all inlier points.

If the fitted 3D geometry is a sphere, the Y-coordinate of the sphere's center point is retrieved.

(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_CENTER_Z +

Retrieves the Z-coordinate of the center point of the fitted 3D geometry, expressed in the working coordinate system.

If the fitted 3D geometry is a cylinder, the Z-coordinate of the center point on the cylinder's central axis is retrieved.

If the fitted 3D geometry is a line, the Z-coordinate of the center point on the line is retrieved.

If the fitted 3D geometry is a plane, the Z-coordinate of the plane's center is retrieved. This center point is equivalent to the centroid of all inlier points.

If the fitted 3D geometry is a sphere, the Z-coordinate of the sphere's center point is retrieved.

(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_CLOSEST_TO_ORIGIN_X +

Retrieves the X-coordinate of the point on the fitted 3D plane geometry, closest to the origin of the working coordinate system.

(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_CLOSEST_TO_ORIGIN_Y +

Retrieves the Y-coordinate of the point on the fitted 3D plane geometry, closest to the origin of the working coordinate system.

(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_CLOSEST_TO_ORIGIN_Z +

Retrieves the Z-coordinate of the point on the fitted 3D plane geometry, closest to the origin of the working coordinate system.

(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_COEFFICIENT_A +

Retrieves the coefficient A of the fitted 3D plane geometry's equation, Ax + By + Cz + D = 0.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE
Click to summarize -1.0 >= Value >= 1.0

Specifies the coefficient A.

Click to summarize M_COEFFICIENT_B +

Retrieves the coefficient B of the fitted 3D plane geometry's equation, Ax + By + Cz + D = 0.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE
Click to summarize -1.0 >= Value >= 1.0

Specifies the coefficient B.

Click to summarize M_COEFFICIENT_C +

Retrieves the coefficient C of the fitted 3D plane geometry's equation, Ax + By + Cz + D = 0.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE
Click to summarize -1.0 >= Value >= 1.0

Specifies the coefficient C.

Click to summarize M_COEFFICIENT_D +

Retrieves the coefficient D of the fitted 3D plane geometry's equation, Ax + By + Cz + D = 0.

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

Specifies the coefficient D.

Click to summarize M_END_POINT_X +

Retrieves the X-coordinate of the end point of the fitted 3D geometry, expressed in the working coordinate system.

If the fitted 3D geometry is a cylinder, the X-coordinate of the cylinder's end point (positioned at the center of the cylinder's second circular base) is retrieved.

If the fitted 3D geometry is a line, the X-coordinate of the line's end point is retrieved.

(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_END_POINT_Y +

Retrieves the Y-coordinate of the end point of the fitted 3D geometry, expressed in the working coordinate system.

If the fitted 3D geometry is a cylinder, the Y-coordinate of the cylinder's end point (positioned at the center of the cylinder's second circular base) is retrieved.

If the fitted 3D geometry is a line, the Y-coordinate of the line's end point is retrieved.

(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_END_POINT_Z +

Retrieves the Z-coordinate of the end point of the fitted 3D geometry, expressed in the working coordinate system.

If the fitted 3D geometry is a cylinder, the Z-coordinate of the cylinder's end point (positioned at the center of the cylinder's second circular base) is retrieved.

If the fitted 3D geometry is a line, the Z-coordinate of the line's end point is retrieved.

(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_FIT_RMS_ERROR +

Retrieves the root-mean-squared (RMS) error of the distance between the point cloud or depth map, and the fitted 3D geometry. Only inliers are considered when calculating the RMS error.

For planes, the error corresponds to the distance between the points and the fitted plane.

For spheres and cylinders, the error corresponds to the distance between the points and the surface of the sphere or cylinder. For cylinders, this specifically refers to the distance to the curved surface and not the circular bases.

This result is only available for retrieval after a successful fit.

(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_GEOMETRY_TYPE +

Retrieves the type of the fitted 3D geometry.

This result is only available for retrieval after a successful fit.

(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_CYLINDER

Specifies a cylinder.

Click to summarize M_LINE

Specifies a line.

Click to summarize M_PLANE

Specifies a plane.

Click to summarize M_SPHERE

Specifies a sphere.

Click to summarize M_LENGTH +

Retrieves the length of the fitted 3D cylinder geometry, or fitted 3D line geometry, in world units.

(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_NORMAL_X +

Retrieves the X-component of the fitted 3D plane geometry's normal unit vector.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE
Click to summarize -1.0 >= Value >= 1.0

Specifies the X-component of the normal unit vector, expressed in the working coordinate system.

Click to summarize M_NORMAL_Y +

Retrieves the Y-component of the fitted 3D plane geometry's normal unit vector.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE
Click to summarize -1.0 >= Value >= 1.0

Specifies the Y-component of the normal unit vector, expressed in the working coordinate system.

Click to summarize M_NORMAL_Z +

Retrieves the Z-component of the fitted 3D plane geometry's normal unit vector.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE
Click to summarize -1.0 >= Value >= 1.0

Specifies the Z-component of the normal unit vector, expressed in the working coordinate system.

Click to summarize M_NUMBER_OF_POINTS_INLIERS +

Retrieves the number of points that were considered inliers during the fit operation.

This result is only available for retrieval after a fit.

(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_NUMBER_OF_POINTS_MISSING_DATA +

Retrieves the number of points with zero confidence (if you specified a container), or the number of points with an invalid value (if you specified a depth map). Note that in the case of depth maps, this only refers to the points inside the ROI.

This result is only available for retrieval after a fit.

(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_NUMBER_OF_POINTS_OUTLIERS +

Retrieves the number of points that were considered outliers during the fit operation.

This result is only available for retrieval after a fit.

(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_NUMBER_OF_POINTS_TOTAL +

Retrieves the total number of points. This number is equal to M_NUMBER_OF_POINTS_VALID + M_NUMBER_OF_POINTS_MISSING_DATA.

This result is only available for retrieval after a fit.

(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_NUMBER_OF_POINTS_VALID +

Retrieves the number of valid points, which is equal to the number of points with non-zero confidence. This number is equal to M_NUMBER_OF_POINTS_INLIERS + M_NUMBER_OF_POINTS_OUTLIERS.

This result is only available for retrieval after a fit.

(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_RADIUS +

Retrieves the radius of the fitted 3D cylinder geometry or 3D sphere geometry in world units.

(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_START_POINT_X +

Retrieves the X-coordinate of the fitted 3D geometry's start point, expressed in the working coordinate system.

If the fitted 3D geometry is a cylinder, the start point is positioned at the center of the cylinder's first circular base.

If the fitted 3D geometry is a line, the start point is positioned at the start of the line.

(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_START_POINT_Y +

Retrieves the Y-coordinate of the fitted 3D geometry's start point, expressed in the working coordinate system.

If the fitted 3D geometry is a cylinder, the start point is positioned at the center of the cylinder's first circular base.

If the fitted 3D geometry is a line, the start point is positioned at the start of the line.

(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_START_POINT_Z +

Retrieves the Z-coordinate of the fitted 3D geometry's start point, expressed in the working coordinate system.

If the fitted 3D geometry is a cylinder, the start point is positioned at the center of the cylinder's first circular base.

If the fitted 3D geometry is a line, the start point is positioned at the start of the line.

(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 +

Retrieves the status of the fit operation.

This result is always available for retrieval.

(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_ALL_POINTS_COPLANAR

Specifies that the fit failed because the fit operation tried to fit a sphere, or cylinder, to points that are coplanar.

Click to summarize M_BAD_ESTIMATE

Specifies that the fit failed because the initial fit estimate did not include any valid inliers.

Click to summarize M_NOT_ENOUGH_VALID_DATA

Specifies that the fit failed because there were not enough valid points to fit the specified 3D geometry.

Click to summarize M_NOT_INITIALIZED

Specifies that the fit 3D metrology result buffer was not used in a call to M3dmetFit(), and contains no results.

Click to summarize M_SUCCESS

Specifies that the fit operation completed successfully.

To retrieve a result from an statistics 3D metrology result buffer, the ResultType parameter can be set to one of the following values:

function map For retrieving results from a statistics 3D metrology result buffer
Click to summarizeResultType Description
ResultArrayPtr
- Possible values returned
Click to summarize M_STAT_MAX +

Retrieves the maximum distance between the point cloud or depth map, and the reference 3D geometry.

(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_STAT_MAX_ABS +

Retrieves the maximum absolute distance between the point cloud or depth map, and the reference 3D geometry.

(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_STAT_MEAN +

Retrieves the mean distance between the point cloud or depth map, and the reference 3D geometry.

(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_STAT_MIN +

Retrieves the minimum distance between the point cloud or depth map, and the reference 3D geometry.

(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_STAT_MIN_ABS +

Retrieves the minimum absolute distance between the point cloud or depth map, and the reference 3D geometry.

(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_STAT_NUMBER +

Retrieves the number of points that satisfied the condition specified when M3dmetStat() was called (using the Condition parameter).

(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_STAT_RMS +

Retrieves the root-mean-square (RMS) error between the point cloud or depth map, and the reference 3D geometry object. MIL calculates the RMS error using the following formula:

(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_STAT_STANDARD_DEVIATION +

Retrieves the standard deviation of all the distances calculated between the point cloud or depth map, and the reference 3D geometry. MIL calculates the standard deviation using the following formula:

(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_STAT_SUM +

Retrieves the sum of all the distances calculated between the point cloud or depth map, and the reference 3D geometry.

(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_STAT_SUM_ABS +

Retrieves the sum of all the absolute distances calculated between the point cloud or depth map, and the reference 3D geometry.

(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_STAT_SUM_OF_SQUARES +

Retrieves the sum of squared distances between the point cloud or depth map, and the reference 3D geometry.

(summarize)
Expand data type infoCollapse data type info ResultArrayPtr extra info
Data type info: Data type: address of a MIL_DOUBLE

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_DOUBLE
Click to summarize M_NULL

Specifies that the result is not available to be retrieved.

Click to summarize Value != 0

Specifies that the result is available to be retrieved.

You can add one of the following values to the above-mentioned values to cast the requested results to the required 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: address of a MIL_DOUBLE
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: address of a MIL_FLOAT
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: address of a MIL_INT
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: address of a MIL_INT32
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: address of a MIL_INT64
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; mil3dmet.lib.
DLL Requires mil.dll; mil3dmet.dll.
AXIS X AXIS Y AXIS Z CENTER X CENTER Y CENTER Z CLOSEST TO ORIGIN X CLOSEST TO ORIGIN Y CLOSEST TO ORIGIN Z COEFFICIENT A COEFFICIENT B COEFFICIENT C COEFFICIENT D END POINT X END POINT Y END POINT Z FIT RMS ERROR GEOMETRY TYPE CYLINDER LINE PLANE SPHERE LENGTH NORMAL X NORMAL Y NORMAL Z NUMBER OF POINTS INLIERS NUMBER OF POINTS MISSING DATA NUMBER OF POINTS OUTLIERS NUMBER OF POINTS TOTAL NUMBER OF POINTS VALID RADIUS START POINT X START POINT Y START POINT Z STATUS ALL POINTS COPLANAR BAD ESTIMATE NOT ENOUGH VALID DATA NOT INITIALIZED SUCCESS STAT MAX STAT MAX ABS STAT MEAN STAT MIN STAT MIN ABS STAT NUMBER STAT RMS STAT STANDARD DEVIATION STAT SUM STAT SUM ABS STAT SUM OF SQUARES AVAILABLE NULL TYPE MIL DOUBLE TYPE MIL FLOAT TYPE MIL INT TYPE MIL INT32 TYPE MIL INT64