M3dmapGet

MIL_ID Result3dmapId,	//in
MIL_INT LabelOrIndex,	//in
MIL_INT64 Feature,	//in
MIL_INT64 PointsToInclude,	//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 bigger 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 smaller than the actual number of elements needed, the arrays will not be modified at all, unless using M_PARTIAL_WRITE. When using M_PARTIAL_WRITE, the arrays are filled with point information until they are full; the remaining point information is ignored.

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, PointsToInclude, 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 information about all points, including those set to M_INVALID_POINT. To filter out the invalid points, specify M_EXCLUDE_INVALID_POINTS.

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.

PointsToInclude

Specifies which points to include in the array(s).

For specifying the subset of points
Value	Description
M_DEFAULT	Same as M_INCLUDE_ALL_POINTS.
M_EXCLUDE_INVALID_POINTS +	Specifies to exclude all points in the specified point cloud(s) that are set to M_INVALID_POINT. This includes all valid points inside and outside of the extraction box. (summarize) Specifies to exclude all points in the specified point cloud(s) that are set to M_INVALID_POINT. (more details...)
M_INCLUDE_ALL_POINTS +	Specifies to include all points in the point cloud(s).
M_INCLUDE_POINTS_INSIDE_BOX_ONLY +	Specifies to include all valid points inside the extraction box. Note that invalid points have no coordinates, and so are neither inside nor outside the extraction box. (summarize) Specifies to include all valid points inside the extraction box. (more details...)
M_INVALIDATE_POINTS_OUTSIDE_BOX +	Specifies to include all points in the point cloud(s), and to set points outside the extraction box to M_INVALID_POINT.

Combination values for any of the possible values of the PointsToInclude parameter.

You can add one or more of the following values to the above-mentioned values to specify additional point inclusion options.

For specifying additional options
Combination value	Description
M_LAST_SCAN	Specifies to include 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 include only those points generated during the last call to M3dmapAddScan(). (more details...)
M_PARTIAL_WRITE	Specifies to write to the output array(s), even if the array(s) are not big enough to hold all the elements.

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. This is for arrays of type MIL_FLOAT. (summarize) Specifies to cast the data into one or more arrays of 32-bit floating-point numbers. (more details...)
M_FLOAT + 64	Specifies to cast the data into one or more arrays of 64-bit floating-point numbers. This is for arrays of type MIL_DOUBLE. (summarize) Specifies to cast the data into one or more arrays of 64-bit floating-point numbers. (more details...)
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

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

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 PointsToInclude 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

Set unused parameters to M_NULL.

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 of type MIL_UINT8 (more details...) Data type: array of type MIL_UINT16 Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. Note: This only applies when the Type parameter is set to M_UNSIGNED + 16 Data type: array of type MIL_UINT8 Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. 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 of type MIL_UINT8 (more details...) Data type: array of type MIL_UINT16 Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. Note: This only applies when the Type parameter is set to M_UNSIGNED + 16 Data type: array of type MIL_UINT8 Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. 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 of type MIL_FLOAT (more details...) Data type: array of type MIL_DOUBLE Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. 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 of type MIL_FLOAT (more details...) Data type: array of type MIL_DOUBLE Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. 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 of type MIL_FLOAT (more details...) Data type: array of type MIL_DOUBLE Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. 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 of type MIL_FLOAT (more details...) Data type: array of type MIL_DOUBLE Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. 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 of type MIL_FLOAT (more details...) Data type: array of type MIL_DOUBLE Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. 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 of type MIL_FLOAT (more details...) Data type: array of type MIL_DOUBLE Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. 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 of type MIL_FLOAT (more details...) Data type: array of type MIL_DOUBLE Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. 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 of type MIL_FLOAT (more details...) Data type: array of type MIL_DOUBLE Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. 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 of type MIL_FLOAT (more details...) Data type: array of type MIL_DOUBLE Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. 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 of type MIL_FLOAT (more details...) Data type: array of type MIL_DOUBLE Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. Note: This only applies when the Type parameter is set to M_FLOAT + 64 Data type: array of type MIL_FLOAT Required array size:Call M3dmapGet() with Coord1OrPackedArrayPtr set to M_NULL, Coord2ArrayPtr set to M_NULL, and Coord3ArrayPtr set to M_NULL. The array size is stored in the NeededSizePtr parameter. 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. The PointsToInclude parameter can modify the total number of points returned, and so can modify the return value of this function.

Compilation information

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