| MIL 10 Reference
| Customize Help
| Save Settings

M3dmapCalibrateMultiple


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
M3dmapCalibrate
M3dmapClear
Synopsis
Calibrate a 3D reconstruction setup that uses multiple camera-laser pairs.
Syntax
void M3dmapCalibrateMultiple(
const MIL_ID *Context3dmapIdArrayPtr, //in
const MIL_ID *Result3dmapIdArrayPtr, //in
const MIL_ID *ContextCalIdArrayPtr, //in
MIL_INT ArraySize, //in
MIL_INT64 ControlFlag //in
)
Description

This function calibrates your 3D reconstruction setup when using multiple camera-laser pairs.

By identifying the camera-laser pairs using M_CAMERA_LABEL() and M_LASER_LABEL() when allocating the 3D reconstruction context, you can determine which cameras and lasers should share a common calibration. When two contexts share the same laser label, they will be constrained to sharing the same laser plane equation. Similarly, when two contexts share the same camera label, they will be constrained to using the same camera calibration. By calling M3dmapCalibrateMultiple(), instead of using multiple calls to M3dmapCalibrate(), the calibrations of the 3D reconstruction will be optimized to satisfy the constraints imposed by all the various calibrations.

When constructing the arrays specified by Context3dmapIdArrayPtr, Result3dmapIdArrayPtr, and ContextCalIdArrayPtr, you must establish a one to one relationship between each item; that is, the 3D reconstruction context is calibrated using the camera calibration and extracted laser line data found in the same array position. The three arrays passed to the function must have the same size specified by ArraySize.

When using M3dmapCalibrateMultiple(), the following setup constraints must be met:

  • You must use a 3D based calibration mode for each camera calibration context, either M_TSAI_BASED or M_3D_ROBOTICS.

  • If the laser planes are not perpendicular to the object's motion (that is, if they are not perfectly vertical), the result buffers must contain laser line data extracted from multiple reference planes (using multiple calls to M3dmapAddScan() for each result buffer). The laser planes are assumed to be perfectly vertical if a single reference plane is provided for a given laser label.

  • The laser lines projected on the XY-plane (Z=0) must be perpendicular to the object's motion.

  • The camera must have a sufficient angle with respect to their respective laser planes to have accurate results; that is, the cameras must be able to acquire meaningful displacements of the laser lines for different depths. For more information, see the Camera angle requirement subsection of the Configuring the laser line profiling setup section of Chapter 18: 3D reconstruction using laser line profiling.

  • The camera calibration identifiers at two distinct indices in the ContextCalIdArrayPtr array must be the same if and only if the camera labels of the two 3D reconstruction contexts at the same indices in the Context3dmapIdArrayPtr array are also the same.

For the steps required to calibrate your 3D reconstruction setup in either mode, see the Calibrating your 3D reconstruction setup to create a point cloud section of Chapter 18: 3D reconstruction using laser line profiling.

After calling M3dmapCalibrateMultiple(), you can use M3dmapInquire() set to M_CALIBRATION_STATUS on each 3D reconstruction context to know the results of the calibration operation.

  • If M3dmapCalibrateMultiple() is successful, all statuses are set to M_CALIBRATED.

  • If M3dmapCalibrateMultiple() fails because of a particular 3D reconstruction context, its calibration status is set according to the cause of failure. A MIL error is also reported. The calibration status of the other contexts are set to M_NOT_INITIALIZED. Apart from the calibration status, the 3D reconstruction contexts are unchanged, and can thus be used in a subsequent call to M3dmapCalibrateMultiple().

  • If M3dmapCalibrateMultiple() fails during the global optimization phase, the calibration status of all the 3D reconstruction contexts is set to the cause of failure. A different MIL error is also reported. Apart from the calibration status, the 3D reconstruction contexts are unchanged, and can thus be used in a subsequent call to M3dmapCalibrateMultiple().

  • If M3dmapCalibrateMultiple() fails because of an invalid parameter passed to the function, the 3D reconstruction contexts remains unchanged (including the calibration status). A MIL error is reported accordingly.

This function can only be called on 3D reconstruction contexts allocated with M_CALIBRATED_CAMERA_LINEAR_MOTION reconstruction mode.

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
Context3dmapIdArrayPtr

Specifies the address of an array containing the identifiers of the 3D reconstruction context used to extract the laser line from grabbed images. The contexts must have been previously allocated on the required system using M3dmapAlloc().

This array must have a size equal to ArraySize.

Result3dmapIdArrayPtr

Specifies the address of an array containing the identifiers of the 3D reconstruction result buffers that contains the laser line data required for calibration. The 3D reconstruction result buffers must have been previously allocated using M3dmapAllocResult() and contain data for at least one laser line.

This array must have a size equal to ArraySize.

ContextCalIdArrayPtr

Specifies the address of an array containing the identifiers of the camera calibration contexts of the cameras used to grab the laser lines. The contexts must have been previously allocated on the required system using McalAlloc() with M_TSAI_BASED or M_3D_ROBOTICS and must be calibrated.

This array must have a size equal to ArraySize.

ArraySize

Specifies the number of camera-laser pairs. This parameter must be greater or equal to 1.

ControlFlag

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

function map For specifying error reporting in the case of duplicate labels
CollapseValue Description
Collapse M_DEFAULT

Specifies the default behavior. If two or more 3D reconstruction contexts in Context3dmapIdArrayPtr have been allocated with the same values for CameraLabel and LaserLabel, an error is reported.

(summarize)
Collapse M_ALLOW_DUPLICATES

Specifies to not report an error if two or more 3D reconstruction contexts in Context3dmapIdArrayPtr have been allocated with the same values for CameraLabel and LaserLabel.
Compilation information
Header Include mil.h.
Library Use mil.lib; mil3dmap.lib.
DLL Requires mil.dll; mil3dmap.dll.
3D ROBOTICS TSAI BASED DEFAULT ALLOW DUPLICATES