M3dmapPut

This function creates a new point cloud or repopulates an existing point cloud. This function is used as an alternative to M3dmapAddScan(), typically with points generated using third-party hardware or software. This function cannot add additional points to an existing point cloud; rather, it deletes the existing points and adds new points to the original point cloud. While it cannot add additional points to a point cloud, the function can affect point features, such as intensity, of an existing point cloud. The function can add point features, delete point features, and write over point features associated with points in the point cloud.

All point clouds created with or repopulated with M3dmapPut() are of type M_UNORGANIZED. If an existing point cloud is specified that is not of type M_UNORGANIZED (such as point clouds of type M_LASER_SCAN), an error occurs.

If you specify an array with one sort of point feature (position or intensity) and you specify an unorganized point cloud that already exists, you overwrite the same point feature of each existing point, but keep the remaining features of each point. For instance, if Feature is set to M_POSITION, and you specify an existing point cloud that has both position and intensity data, you will overwrite the existing position data of each point, but will keep the existing intensity data of each point. When overwriting intensity data, you keep the existing position data intact.

All points in a point cloud populated using M3dmapPut() are assumed to be in the absolute coordinate system, unless a relative coordinate system is specified using CalibratedMilObjectId.

When you are overwriting existing points with new points, you must put the same number of points as existed in the previous point cloud. If necessary, the array you specify with the new points should include any invalid points as place holders. This keeps the total number of places the same. It is also possible that, when creating a new point cloud, you want to store the invalid points in your array (for instance, to maintain the structure of how your points are internally represented). When adding points to a point cloud, whether creating a new point cloud or overwriting existing points, invalid points are generally represented with an X-, Y-, and Z-coordinate set to M_INVALID_POINT. How to specify an invalid point can differ, depending on the data type of your data. Note that it is possible that a feature, such as M_INTENSITY, has a valid value, while the point to which it corresponds is an invalid point with M_INVALID_POINT coordinates. In this case, you typically set the corresponding feature value to 0.

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.