| MIL 10 Reference
| Customize Help
| Save Settings

M3dmapAddScan


See also
Availability
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
function map Function map
Examples
Previous
M3dmapAlign
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 the specified buffer is of type M_DEPTH_CORRECTED_DATA or M_POINT_CLOUD_CONTAINER, you can use this data to generate a partially corrected or fully corrected depth map, respectively, with M3dmapExtract(). 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_CONTAINER, 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_CONTAINER 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 if there is complementary information.
Parameters
This function is not supported on the selected boards.
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_CONTAINER, or M_DEPTH_CORRECTED_DATA.

You can call this function concurrently in multiple threads for the same M_POINT_CLOUD_CONTAINER 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 perform laser line extraction section of Chapter 18: 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_CONTAINER. For all other types of 3D reconstruction result buffers, set this parameter to M_DEFAULT.

function map For specifying the label of a point cloud
CollapseValue Description
Collapse

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)
Parameters

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:

function map To specify the function's control flag
CollapseValue Description
Collapse M_DEFAULT

Same as M_EXTRACT_LINE.
Collapse 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.
Collapse 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)
Compilation information
Header Include mil.h.
Library Use mil.lib; mil3dmap.lib.
DLL Requires mil.dll; mil3dmap.dll.
UNSIGNED PROC NONE PROC NONE DEFAULT EXTRACT LINE LINE ALREADY EXTRACTED