M3dmapAddScan

See also

User Guide:

3D coordinate systems and the coordinates of a point cloud Calibrating your 3D reconstruction setup to create a point cloud Configuring the laser line profiling setup Multiple camera-laser pairs Partially corrected depth maps Steps to creating a cloud of 3D points using laser line profiling Using 3D cameras that output uncorrected depth maps

Reference:

M3dmapAlloc M3dmapAllocResult M3dmapCalibrate M3dmapCalibrateMultiple M3dmapClear M3dmapControl MbufAlloc2d MbufInquire MimControl MthrAlloc

Availability

Not available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Not supported on:

Not supported on Matrox Indio (Update 53 or Update 68) (w)

Not supported on Matrox Concord PoE with ToE (Update 82) (z)

Fully supported on:

Fully supported on Host system (a)

Fully supported on Matrox GigE Vision driver (MIL 10, Update 25, Update 54, or Update 85)* (c)

Fully supported on Matrox Morphis (g)

Fully supported on Matrox Morphis QxT (h)

Fully supported on Matrox Orion HD (i)

Fully supported on Matrox Radient eCL (j)

Fully supported on Matrox Radient eV-CXP (MIL 10 or Update 29)* (k)

Fully supported on Matrox Solios eA/XA (l)

Fully supported on Matrox Solios ecl/xcl/ev-cl (m)

Fully supported on Matrox USB3 Vision driver (Update 19) (o)

Fully supported on Matrox RadientPro-CL (Update 7) (p)

Fully supported on Matrox Radient eV-CL (Update 27 or 74) (r)

Fully supported on Matrox Iris GTR (Update 28 or Update 68) (t)

Fully supported on Matrox Clarity UHD (Update 36 or 76) (u)

Fully supported on Matrox GenTL driver (Update 34) (v)

Fully supported on Matrox Rapixo CXP (Update 75 or Update 84) (y)

Fully supported on Matrox Rapixo CL Pro (Update 96) (aa)

* Refer to the MIL system-specific information
in the MIL Reference for the minimum update required.

For any information regarding a MIL system added during a MIL Update, see the MIL system’s release note

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

cameralasercalibration.cpp
examplemanagerfor3d.cpp
m3dmap.cpp
m3dmap.cs
m3dmap.vb
multicameralasercalibration.cpp

Function Map

- LaserOrDepthMapImageBufId

- IntensityImageBufId

- ExtraInfoArrayId

- PointCloudLabel

Table:

For specifying the label of a point cloud

- ControlFlag

Table:

To specify the function's control flag

Compilation information

Synopsis

Extract laser line data from an image and store this data in a 3D reconstruction result buffer.

Syntax

void M3dmapAddScan(

MIL_ID Context3dmapId,	//in
MIL_ID Result3dmapId,	//in
MIL_ID LaserOrDepthMapImageBufId,	//in
MIL_ID IntensityImageBufId,	//in
MIL_ID ExtraInfoArrayId,	//in
MIL_INT PointCloudLabel,	//in
MIL_INT64 ControlFlag	//in

)

Description

This function stores laser line data extracted from grabbed images into the specified result buffer.

If the specified result buffer is of type M_LASER_CALIBRATION_DATA, you can use this data to calibrate a laser reconstruction setup using M3dmapCalibrate() or M3dmapCalibrateMultiple(). If your camera has integrated hardware capable of extracting the laser line data, call M3dmapAddScan() with M_LINE_ALREADY_EXTRACTED to skip the extraction process and store laser line data in the result buffer.

If the number of extracted laser lines is greater than the maximum number of lines that can be stored in the result buffer, specified using M3dmapControl() with M_MAX_FRAMES, the result buffer's oldest values are overwritten with the new ones.

When specifying a 3D reconstruction result buffer allocated using M_POINT_CLOUD_RESULT, calls to M3dmapAddScan() either create a new point cloud in the result buffer and add laser line data to it, or just add laser line data to the specified point cloud in the result buffer. To create a new point cloud, specify a point cloud label that does not currently exist in the specified 3D reconstruction result buffer.

Between each set of scans for different objects or for cumulative extraction mode, you can clear the content of the result buffer using M3dmapClear().

Note that the size and depth of the source image buffer containing the laser lines must not change when making multiple calls to M3dmapAddScan() with the same destination result buffer.

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

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

Context3dmapId

Specifies the identifier of the 3D reconstruction context. The 3D reconstruction context must have been previously allocated on the required system using M3dmapAlloc() with M_LASER.

Result3dmapId

Specifies the identifier of the 3D reconstruction result buffer in which to store the laser line data. The 3D reconstruction result buffer must have been previously allocated using M3dmapAllocResult() with M_LASER_CALIBRATION_DATA, M_POINT_CLOUD_RESULT, or M_DEPTH_CORRECTED_DATA.

You can call this function concurrently in multiple threads for the same M_POINT_CLOUD_RESULT result buffer, so long as the PointCloudLabel is distinct between concurrent calls and all other parameters do not share data between concurrent calls.

LaserOrDepthMapImageBufId

Specifies the identifier of the image buffer containing the grabbed image of the laser line.

If ControlFlag is set to M_LINE_ALREADY_EXTRACTED, the image buffer must contain an uncorrected depth map that follows the following format:

If the M_SCAN_LANE_DIRECTION control type is set to M_HORIZONTAL, the uncorrected depth map must contain M rows and N columns, where:
- M is the number of frames containing the laser line. One frame generates one row of data, where frame m corresponds to row m in the uncorrected depth map (0 <= m <= M - 1).
- N is the width, in pixels, of the laser line image. One pixel corresponds to one column of data, where the pixel distance of the laser line in column n of the laser line image corresponds to the pixel in column n in the uncorrected depth map (0 <= n <= N - 1).
- Each entry (m, n) in the uncorrected depth map must contain a value d, which is the vertical distance of the laser line in column n of the laser line image m.
If the M_SCAN_LANE_DIRECTION control type is set to M_VERTICAL, the uncorrected depth map must contain M rows and N columns, where:
- M is the number of frames containing the laser line. One frame generates one row of data, where frame m corresponds to row m in the uncorrected depth map (0 <= m <= M - 1).
- N is the height, in pixels, of the laser line image. One pixel corresponds to one row of data, where the pixel distance of the laser line in row n of the laser line image corresponds to the pixel in column n in the uncorrected depth map (0 <= n <= N - 1).
- Each entry (m, n) in the uncorrected depth map must contain a value d, which is the horizontal distance of the laser line at row n in the laser line image m.

For more information on the required image buffer format in M_LINE_ALREADY_EXTRACTED mode, consult the Using 3D cameras that output uncorrected depth maps section of Chapter 40: 3D reconstruction using laser line profiling.

If you supply M3dmapAddScan() with a child buffer so that it processes only a subset of the grabbed laser line image, and you will be generating a fully corrected depth map, you must specify the X- and Y-offsets of that child buffer, relative to the top-left pixel of the image buffer used during camera calibration. To do so, use M3dmapControl() with M_EXTRACTION_CHILD_OFFSET_X and M_EXTRACTION_CHILD_OFFSET_Y. If you know, for example, that the laser line will appear only at certain heights in the grabbed laser line image, using a child buffer can be useful to narrow down the search region and reduce processing time.

This buffer must have been previously allocated with MbufAlloc2d(). The image must be a 1-band, 8-bit or 16-bit, unsigned buffer and its size must not exceed 65535 pixels by 65535 pixels.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

IntensityImageBufId

Specifies the identifier of the image buffer containing the intensity map, if using a 3D camera. If you are not using a 3D camera, set this parameter to M_NULL. If you use a 3D camera that does not provide intensity map data (or if you want to exclude it), you should also set this parameter to M_NULL.

If the M_SCAN_LANE_DIRECTION control type of the 3D reconstruction context is set to M_VERTICAL, the gray level of the uncorrected intensity map for coordinate (X, Y) corresponds to the Y-position of the laser line at column X.

If the M_SCAN_LANE_DIRECTION control type of the 3D reconstruction context is set to M_HORIZONTAL, the gray level of the uncorrected intensity map at coordinate (X, Y) corresponds to the X-position of the laser line at row Y.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

ExtraInfoArrayId

Reserved for future expansion. This parameter must be set to M_NULL.

PointCloudLabel

Specifies the label of the point cloud in the result buffer in which to add the laser line data, if the result buffer has been allocated using M3dmapAllocResult() with M_POINT_CLOUD_RESULT. For all other types of 3D reconstruction result buffers, set this parameter to M_DEFAULT.

For specifying the label of a point cloud

Value

Description

M_POINT_CLOUD_LABEL(

MIL_INT PointCloudLabel

)

Specifies the label of the point cloud.

If the result buffer does not contain a point cloud with the specified label, a new point cloud is created in the result buffer.

(summarize)

Specifies the label of the point cloud.

(more details...)

Parameters

PointCloudLabel INQ

Specifies the label.

1 <= Value <= 134217727

Specifies the label as a positive integer value. This value must be between 1 and 134217727.

ControlFlag

Specifies the function's control flag. This parameter must be set to one of the following values:

To specify the function's control flag
Value	Description
M_DEFAULT	Same as M_EXTRACT_LINE.
M_EXTRACT_LINE	Extracts the laser line data from the input image, corrects the data if the 3D reconstruction context is calibrated, and stores it in the result buffer.
M_LINE_ALREADY_EXTRACTED	Specifies that the uncorrected depth map and intensity map are given as input. Specify this control flag only if the 3D Reconstruction module should not perform the laser line extraction, as is the case for 3D cameras that perform laser line extraction. (summarize) Specifies that the uncorrected depth map and intensity map are given as input. (more details...)

Compilation information

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