M3dmapGet

User Guide:

3D coordinate systems and the coordinates of a point cloud Multiple point clouds Steps to creating a cloud of 3D points using laser line profiling

Reference:

M3dmapAddScan M3dmapAllocResult M3dmapGetResult M3dmapInquire MthrAlloc

Not available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP

Available on Matrox Supersight

None.

M3dmapFree

M3dmapGetResult

Synopsis

Retrieve the world coordinates and intensity of each of the points in one or more point clouds.

Syntax

MIL_INT M3dmapGet(

MIL_ID Result3dmapId,	//in
MIL_INT LabelOrIndex,	//in
MIL_INT64 Feature,	//in
MIL_INT64 Options,	//in
MIL_INT64 Type,	//in
MIL_INT ArraySize,	//in
void *Coord1OrPackedArrayPtr,	//out
void *Coord2ArrayPtr,	//out
void *Coord3ArrayPtr,	//out
MIL_INT *NeededSizePtr	//out

)

Description

This function allows you to retrieve the world coordinates and intensity of each of the points in one or more point clouds. You can return this information aggregated in a single array or in three arrays, one for each dimension.

If the specified arrays are greater than or equal to the actual number of elements needed, the arrays are filled with the data and any remaining array indices are left empty. If the specified arrays are less than the actual number of elements needed, the arrays will not be modified at all.

To determine the exact size of the array needed for a given set of parameter values, call this function twice, the first time to determine the required array size and the second time to fill the array. When calling for the first time, specify the same values for Result3dmapId, LabelOrIndex, Feature, Options, and Type as you would for the second call to this function. In addition, set NeededSizePtr to an appropriate address, and set ArraySize and the array parameters to M_NULL. On the second call, specify the required array size to ArraySize, and specify arrays that are at least as large as the needed array size.

By default, this function also returns coordinates of points set to M_INVALID_POINT. To filter out the invalid points, specify the M_NO_INVALID_POINT option.

If coordinates or intensities are not available for the specified point cloud(s), the function will return an error. You can use M3dmapGetResult() with M_HAS_FEATURE to determine whether a feature is available.

Unlike most other functions that modify a MIL object, you can call this function concurrently from multiple threads on the same M_POINT_CLOUD_CONTAINER result buffer (Result3dmapId) without using a M_MUTEX object. This is valid as long as the LabelOrIndex parameter of the concurrent calls is set to a different label or index, and is not set to M_ALL.

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

Result3dmapId

Specifies the identifier of the 3D reconstruction result buffer from which to retrieve the information about the points. The 3D reconstruction result buffer must have been previously allocated using M3dmapAllocResult() with M_POINT_CLOUD_CONTAINER.

LabelOrIndex

Specifies the point cloud(s) in the specified 3D reconstruction result buffer.

For specifying the point cloud(s) or point cloud container
Value	Description
M_DEFAULT	Same as M_ALL.
M_POINT_CLOUD_INDEX( MIL_INT PointCloudIndex )	Specifies the index of a point cloud in the specified 3D reconstruction result buffer. (summarize) Specifies the index of a point cloud in the specified 3D reconstruction result buffer. (more details...)
		Parameters
		PointCloudIndex Specifies the index of an existing point cloud.
M_POINT_CLOUD_LABEL( MIL_INT PointCloudLabel )	Specifies the label of a point cloud in the specified 3D reconstruction result buffer. (summarize) Specifies the label of a point cloud in the specified 3D reconstruction result buffer. (more details...)
		Parameters
		PointCloudLabel Specifies the label of an existing point cloud.
M_ALL	Specifies to retrieve the coordinates and/or intensities of all the points in all point clouds in the specified 3D reconstruction result buffer. Points are retrieved from the point cloud in the order of the point cloud index. For example, all points in the point cloud with index 0 are included in the specified array first, followed by all the points in the point cloud with index 1. (summarize) Specifies to retrieve the coordinates and/or intensities of all the points in all point clouds in the specified 3D reconstruction result buffer. (more details...)

Feature

Specifies the feature to retrieve from the point cloud(s).

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

Options

Specifies options for the function.

You can set this parameter to one or more of the following values. For example, to specify both available options, set this parameter to M_LAST_SCAN + M_NO_INVALID_POINT.

For specifying the option(s)
Value	Description
M_DEFAULT	Specifies that no option should be applied.
M_LAST_SCAN	Specifies to return information about only those points generated during the last call to M3dmapAddScan(). This option is valid only if LabelOrIndex refers to a single point cloud of type M_LASER_SCAN. (summarize) Specifies to return information about only those points generated during the last call to M3dmapAddScan(). (more details...)
M_NO_INVALID_POINT	Specifies to exclude information about all points in the specified point cloud(s) that are set to M_INVALID_POINT.

Type

Specifies to cast the point cloud data into one or more arrays of the specified data type and depth.

Specify one of the following:

For specifying to cast the point cloud data into arrays of a specified data type and depth
Value	Description
M_FLOAT + 32	Specifies to cast the data into one or more arrays of 32-bit floating-point numbers.
M_FLOAT + 64	Specifies to cast the data into one or more arrays of 64-bit floating-point numbers.
M_UNSIGNED + 8	Specifies to cast the data into an array of 8-bit integers.
M_UNSIGNED + 16	Specifies to cast the data into an array of 16-bit integers.

ArraySize

Specifies the maximum number of elements that the arrays can hold.

For specifying the size of specified arrays
Value	Description
M_NULL	Specifies that there are no specified arrays. This is typically for determining the required size of the array for subsequent calls to M3dmapGet(). (summarize) Specifies that there are no specified arrays. (more details...)
Value > 0	Specifies the size of the specified arrays.

Coord1OrPackedArrayPtr

Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):

array of type MIL_DOUBLE
array of type MIL_FLOAT
array of type MIL_UINT16
array of type MIL_UINT8

Specifies the address of the array in which to store the retrieved data. This array can hold the X-coordinates or intensities of the specified point cloud, or a packed array of all the coordinates or all the coordinates plus the intensities of the specified point cloud.

When determining the required size of this array for subsequent calls to M3dmapGet(), set this value to M_NULL.

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

Coord2ArrayPtr

Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):

array of type MIL_DOUBLE
array of type MIL_FLOAT
array of type MIL_UINT16
array of type MIL_UINT8

Specifies the address of the array in which to store the Y-coordinates.

When not using this parameter or when determining the required size of this array for subsequent calls to M3dmapGet(), set this value to M_NULL.

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

Coord3ArrayPtr

Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):

array of type MIL_DOUBLE
array of type MIL_FLOAT
array of type MIL_UINT16
array of type MIL_UINT8

Specifies the address of the array in which to store the Z-coordinates.

When not using this parameter or when determining the required size of this array for subsequent calls to M3dmapGet(), set this value to M_NULL.

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

NeededSizePtr

Specifies the address of the variable in which to write the number of array elements needed for this function, given the specified point cloud(s) and values for the Options parameter. This is typically for determining the required size of the array(s) for subsequent calls to M3dmapGet().

Since this function also returns the number of elements, you can set this parameter to M_NULL.

Parameter associations

The table below lists possible values for the Feature parameter and possible values returned to the Coord1OrPackedArrayPtr, Coord2ArrayPtr, and Coord3ArrayPtr parameters.

For retrieving the point features

For retrieving the features of the point cloud(s), the Feature parameter can be set to the following:

For retrieving the point features
Feature		Description
	Coord1OrPackedArrayPtr - Possible values returned
	Coord2ArrayPtr - Possible values returned
	Coord3ArrayPtr - Possible values returned
M_INTENSITY		Retrieves the intensity associated with each point in the specified point cloud(s). Note that, while almost all invalid points have an intensity value of zero, it is possible for an invalid point to have a non-zero intensity. (summarize) Retrieves the intensity associated with each point in the specified point cloud(s). (more details...)
	Coord1OrPackedArrayPtr	Data type info Data type: array of type MIL_UINT16 Array size: the number of points in the point cloud Note: This only applies when the Type parameter is set to M_UNSIGNED + 16 Data type: array of type MIL_UINT8 Array size: the number of points in the point cloud Note: This only applies when the Type parameter is set to M_UNSIGNED + 8 Returns the intensities of the points. Note that if you are using M_UNSIGNED + 8 and a value does not fit in a MIL_UINT8, the retrieved value is undefined. (summarize) Data type info Data type: array of type MIL_UINT16 Array size: the number of points in the point cloud Note: This only applies when the Type parameter is set to M_UNSIGNED + 16 Data type: array of type MIL_UINT8 Array size: the number of points in the point cloud Note: This only applies when the Type parameter is set to M_UNSIGNED + 8 Returns the intensities of the points. (more details...)
M_POSITION		Retrieves the world coordinates of the points in the specified point cloud(s), saving the X-, Y-, and Z-coordinates in separate arrays. The coordinates are expressed in the relative coordinate system of the specified 3D reconstruction result buffer. Note that if you are using M_FLOAT + 32, invalid point coordinates will be set to M_INVALID_POINT_FLOAT, otherwise, invalid point coordinates will be set to M_INVALID_POINT. (summarize) Retrieves the world coordinates of the points in the specified point cloud(s), saving the X-, Y-, and Z-coordinates in separate arrays. (more details...)
	Coord1OrPackedArrayPtr	Data type info Data type: array of type MIL_DOUBLE Array size: the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Array size: the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 32 Returns the X-coordinates of the points. Data type info Data type: array of type MIL_DOUBLE Array size: the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Array size: the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 32 Returns the X-coordinates of the points.
	Coord2ArrayPtr	Data type info Data type: array of type MIL_DOUBLE Array size: the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Array size: the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 32 Returns the Y-coordinates of the points. Data type info Data type: array of type MIL_DOUBLE Array size: the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Array size: the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 32 Returns the Y-coordinates of the points.
	Coord3ArrayPtr	Data type info Data type: array of type MIL_DOUBLE Array size: the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Array size: the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 32 Returns the Z-coordinates of the points. Data type info Data type: array of type MIL_DOUBLE Array size: the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Array size: the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 32 Returns the Z-coordinates of the points.
M_XYZ		Retrieves the world coordinates of the points in the specified point cloud(s), saving the X-, Y-, and Z-coordinates in a single array. The coordinates are interleaved in the following format: [X0, Y0, Z0, X1, Y1, Z1]. The coordinates are expressed in the relative coordinate system of the specified 3D reconstruction result buffer. Note that if you are using M_FLOAT + 32, invalid point coordinates will be set to M_INVALID_POINT_FLOAT, otherwise, invalid point coordinates will be set to M_INVALID_POINT. (summarize) Retrieves the world coordinates of the points in the specified point cloud(s), saving the X-, Y-, and Z-coordinates in a single array. (more details...)
	Coord1OrPackedArrayPtr	Data type info Data type: array of type MIL_DOUBLE Array size: three times the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Array size: three times the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 32 Returns all the coordinates, in a packed format. Data type info Data type: array of type MIL_DOUBLE Array size: three times the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Array size: three times the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 32 Returns all the coordinates, in a packed format.
M_XYZI		Retrieves the world coordinates and intensity of the points in the specified point cloud(s), saving the X-, Y-, and Z-coordinates and intensity in a single array. The data is interleaved in the following format: [X0, Y0, Z0, I0, X1, Y1, Z1, I1]. The coordinates are expressed in the relative coordinate system of the specified 3D reconstruction result buffer. If intensity data is not available, the function will report an error. Note that if you are using M_FLOAT + 32, invalid point coordinates will be set to M_INVALID_POINT_FLOAT; otherwise, invalid point coordinates will be set to M_INVALID_POINT. (summarize) Retrieves the world coordinates and intensity of the points in the specified point cloud(s), saving the X-, Y-, and Z-coordinates and intensity in a single array. (more details...)
	Coord1OrPackedArrayPtr	Data type info Data type: array of type MIL_DOUBLE Array size: four times the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Array size: four times the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 32 Returns all the coordinates, plus the intensities, in a packed format. Data type info Data type: array of type MIL_DOUBLE Array size: four times the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Array size: four times the number of points in the point cloud Note: This only applies when the Type parameter is set to M_FLOAT + 32 Returns all the coordinates, plus the intensities, in a packed format.

Return value

The returned value is the size that the arrays needed to store all the data. When you specify M_NO_INVALID_POINT, the returned value does not include the invalid points.

Compilation information

Header	Include mil.h.
Library	Use mil.lib; mil3dmap.lib.
DLL	Requires mil.dll; mil3dmap.dll.