M3dmapExtract

This function takes the accumulated scanned laser line data stored inside a result buffer and generates a depth map image, as well as an intensity map image, if required. The gray level of the depth map image indicates depth; whereas, the gray level in the intensity map image indicates luminosity.

For result buffers of type M_POINT_CLOUD_CONTAINER, you must set an extraction box, using M3dmapSetBox(), prior to calling M3dmapExtract(); otherwise an error is returned. M3dmapExtract() only uses those points inside the extraction box when generating the depth map.

M3dmapExtract() projects the point cloud on the XY-plane of the relative coordinate system of the M_POINT_CLOUD_CONTAINER result buffer. You can change the perspective of the depth map by transforming the relative coordinate system. For more information, see the Changing a depth map by transforming the relative coordinate system subsection of the Generating fully corrected depth and intensity maps section of Chapter 18: 3D reconstruction using laser line profiling.

Missing data points, due to different phenomena such as occlusion, form gaps in the generated depth map. Pixels corresponding to gaps are set to the maximum value of the specified buffer. You can have M3dmapExtract() fill these gap pixels with likely values. To do so, you must specify the order (mode) in which M3dmapExtract() should fill the gaps using M3dmapControl() with M_FILL_MODE. Then, use M_FILL_SHARP_ELEVATION_DEPTH to indicate whether the difference between the gap's boundaries is sharp or gradual. Sharp elevation gaps are filled by propagating one of the gap's boundaries. Gradual elevation gaps are filled by linear interpolation.

You can also choose to only fill the data gaps of a previously generated depth map image. To do so, first set the required fill mode (M3dmapControl() with M_FILL_MODE). Then, call M3dmapExtract() with M_FILL_MISSING_DATA_ONLY and pass a 3D reconstruction result buffer and the identifier of a depth map image buffer that contains data gaps. The 3D reconstruction result buffer need not be the one used to initially generate the depth map. This is because the result buffer is only needed for the information vital to the gap-filling functionality, such as the fill mode (M3dmapControl() with M_FILL_MODE).

If you know that the total laser line data exceeds available memory, you can gradually add some data to the depth map and intensity map. To do so, you must first enable cumulative extraction mode, using M3dmapControl() with M_EXTRACTION_CUMULATIVE. In this mode, you must clear the depth map image buffer (using MbufClear()) before the first call to M3dmapExtract(). To gradually add data to the depth map, you must iterate through filling up the result buffer with several calls to M3dmapAddScan(), extracting the data from the result buffer into a depth map using M3dmapExtract(), followed by clearing the result buffer, using M3dmapClear(). Once the result buffer is cleared of the previous iteration's laser line data, you can start to fill it again with new laser line data.

Note that in cumulative extraction mode, gap filling is disabled, and you must call M3dmapExtract() with M_FILL_MISSING_DATA_ONLY only after the necessary depth map data is accumulated.

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 index, and is not set to M_ALL.