3D coordinate systems and the coordinates of a point cloud
Once a 3D reconstruction setup has been calibrated using M3dmapCalibrate() (or M3dmapCalibrateMultiple() in the case of multiple camera-laser pairs discussed later), a new coordinate system is created in the 3D reconstruction context: the laser line coordinate system. This coordinate system is a real-world coordinate system partially defined by the intersection of the laser plane with the conveyor (the laser line).
Once you allocate a result buffer using M3dmapAllocResult() with M_POINT_CLOUD_CONTAINER, another new coordinate system is created in the 3D reconstruction result buffer: the relative coordinate system of the 3D result buffer. Once you add 3D data to the result buffer using M3dmapAddScan(), this relative coordinate system overlaps the laser line coordinate system.
The relative coordinate system in the result buffer can be moved, while the laser line coordinate system in the context is always fixed. All results, whether the points in a point cloud or a depth map, are returned with respect to the relative coordinate system.
Understanding the laser line coordinate system
The laser line coordinate system is the coordinate system used to represent 3D points generated by the 3D Reconstruction module. It is defined in the 3D reconstruction context upon calling M3dmapCalibrate() or M3dmapCalibrateMultiple().
The laser line coordinate system has the following characteristics:
-
Its X-axis and origin are on the intersection of the laser plane and the conveyor (laser line).
-
Its Y-axis is parallel to the object's motion.
-
Its Z-axis is perpendicular to the plane of the conveyor and points in the direction of the absolute coordinate system's Z-axis. The XY-plane of the absolute coordinate system must be parallel to the conveyor as well.
Note that if the Z-axis points down, the Z-coordinate decreases in the direction in which height of the objects increase. This leads to negative Z-coordinates for scanned objects.
-
The origin and the direction of the X-axis and Y-axis are as close to the absolute coordinate system as possible, given the above constraints.
In the image below, the absolute coordinate system, which was previously defined using the chessboard grid shown, is not aligned with the conveyor or the laser line. The laser line coordinate system, however, must be aligned with the direction of the conveyor and laser line. So in the laser line coordinate system, the direction of the Y-axis is close to the direction of the absolute coordinate system's Y-axis, but is still parallel with the movement of the conveyor. This direction is essential to understanding why the Y-coordinates of points of an object will increase or decrease as the object moves on the conveyor.
By default, an object's coordinates are initially based on the position of the object in the laser line coordinate system at the moment of the first call to M3dmapAddScan(). Despite the object actually moving along the conveyor to pass under the laser line, the result buffer stores the object's coordinates as they were before the first scan. In the image below, the object is shown in its original position, just before the first scan. Note that the first few scans in the image below will not contain any data about the object; the first few scans are of the conveyor.
All 3D coordinates are returned and all depth and intensity maps are generated in the relative coordinate system of the 3D reconstruction result buffer, which is identical to the laser line coordinate system, by default.
Understanding the relative coordinate system in a 3D result buffer
The relative coordinate system in a M_POINT_CLOUD_CONTAINER result buffer is the coordinate system used when retrieving coordinates of the points in the point cloud. It is defined in a M_POINT_CLOUD_CONTAINER result buffer as soon as 3D data is added to a point cloud, using M3dmapAddScan() or M3dmapPut().
While the coordinates of the points are created with respect to the laser line coordinate system, the coordinates are retrieved with respect to the relative coordinate system. When you create a point cloud using M3dmapAddScan(), the relative coordinate system overlaps with the laser line coordinate system.
Retrieving the coordinates of the points in a point cloud
To retrieve the coordinates of the points in a point cloud, use M3dmapGet(). You can retrieve the coordinates in three separate arrays, each with a size equal to the number of points in the point cloud(s) (Feature set to M_POSITION) or one packed array with a size equal to three times the number of points (Feature set to M_XYZ). You can retrieve the intensities associated with the points in a single array of the same size as the number of points (Feature set to M_INTENSITY) or in a single packed array that includes all the coordinates and the intensities together (Feature set to M_XYZI).
Note that to know the exact size needed for your array, you can call M3dmapGet() with all the array pointers set to M_NULL and ArraySize set to 0. The function will return the size needed for the array(s).
These coordinates can be used as an input to a third party tool to generate a mesh of the object.
Transforming the relative coordinate system
The coordinates of the points are expressed with respect to the relative coordinate system of the M_POINT_CLOUD_CONTAINER result buffer. The relative coordinate system initially overlaps with the laser line coordinate system, but while the laser line coordinate system is fixed, the relative coordinate system can be transformed. If you transform the relative coordinate system (for example, using McalSetCoordinateSystem() or McalFixture()), the returned coordinates obtained using M3dmapGet() and any other result will reflect this transformed coordinate system.
To more easily measure or compare successive objects that can be scanned at random orientations, you can transform the relative coordinate system for each new object such that similar points, edges, and fiducial markers have the same coordinates. In the following images, two boxes are scanned with edges that are not parallel with the axes of the laser line coordinate system, and have different orientations. The vertex closest to the fiducial marker in the top image would, using M3dmapGet(), return the coordinates (7, 5, -3.5) and the same vertex in the bottom image would return the coordinates (3, 4.5, -3.5). This is in the relative coordinate system as it is by default, overlapping the laser line coordinate system. If you moved the relative coordinate system to the corner opposite the fiducial marker, as it appears in the image below, then in both cases the highlighted vertex would return the same coordinates, (6, 0, -3.5). Note that in all cases in these images, the Z-axis is pointing down, which leads to a negative Z-coordinate.
Note that when you are generating a depth map, using M3dmapExtract(), transforming the relative coordinate system can dramatically change the resulting depth map. 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 later in this chapter.
Results displacement mode
The results displacement mode determines whether an object's stored coordinates are returned fixed as they were before being scanned, or as they currently are after moving along the conveyor. For example in the image below, when M3dmapControl() with M_RESULTS_DISPLACEMENT_MODE is set to M_FIXED, the coordinates of the specified point on the box before being scanned at t0 are (3, 3, -2). Regardless of the ongoing movement of the object at t1 , all results are returned as though the object was fixed at its original position. The specified point still has the same coordinates, (3, 3, -2).
When M_RESULTS_DISPLACEMENT_MODE is set to M_CURRENT, the specified point that started at t0 changes to (3, -8, -2) at t1 . The change in the Y-coordinate from 3 to -8 is because the conveyor moved 11 units in the direction of the negative Y-axis since the scanning began. You can determine the distance that the object traveled along the conveyor since the scanning began (the change in the Y-coordinate) using M3dmapGetResult() set to M_TOTAL_DISPLACEMENT_Y.
The displacement mode also has an effect on defining the extraction box when generating a depth map. For more information on specifying the extraction box, see the Specifying the extraction box when including Y-axis displacement subsection of the Generating fully corrected depth and intensity maps section later in this chapter.