M3dimLattice

Board	Supported
Host System	Yes
V4L2	Yes
Clarity UHD	Yes
Concord PoE	No
GenTL	Yes
GevIQ	Yes
GigE Vision	Yes
Indio	No
Iris GTX	Yes
Radient eV-CL	Yes
Rapixo CL	Yes
Rapixo CoF	Yes
Rapixo CXP	Yes
USB3 Vision	Yes

Calculate a lattice structure for a container's point cloud.

Syntax

void M3dimLattice(
    AIL_ID    LatticeContext3dimId,          //in
    AIL_ID    ContainerBufId,                //in
    AIL_ID    Box3dgeoId,                    //in
    AIL_ID    LatticeResultOrContext3dimId,  //out
    AIL_INT64 ControlFlag                    //in
)

Description

This function calculates a lattice that divides points into cells. You can use the calculated lattice to subsample or project the point cloud, where one point is selected per cell, or all points in a cell are projected into the same depth map pixel, respectively.

Use M3dimControl to set constraints on the lattice before calling this function. For example, you can specify the relative cell dimensions (that is, the sizes of X, Y, and Z relative to each other) using M_RELATIVE_CELL_SIZE_....

Results are stored in the specified lattice 3D image processing result buffer or subsample 3D image processing context. You can retrieve results from the lattice 3D image processing result buffer, using M3dimGetResult.

To use the lattice to subsample the point cloud, specify a subsample 3D image processing context as the destination for results. Alternatively, you can store results in a lattice 3D image processing result buffer, and then copy them into a subsample 3D image processing context, using M3dimCopyResult with M_SUBSAMPLE_CONTEXT. When you call M3dimSample with a subsample 3D image processing context containing lattice results, a grid operation is performed where one point is selected per cell in the lattice. Empty cells or cells containing only invalid points are ignored when the resulting point cloud is unorganized, whereas they result in points with 0 confidence when the resulting point cloud is organized.

You can use this function instead of M3dimCalculateMapSize to calculate a recommended depth map buffer size for projection. M3dimCalculateMapSize recommends a size such that most points map to their own pixel. You should use M3dimLattice if you want multiple points to map to the same pixel. Use M3dimControl with M_LATTICE_MODE to specify the mode with which to calculate the lattice. If using M_FRACTION_OF_POINTS, you can specify the required ratio of valid pixels in the depth map to valid points in the point cloud, using M_FRACTION_OF_POINTS and M_FRACTION_OF_POINTS_TOLERANCE. If using M_SPARSITY_CHANGE, you can specify the tolerance to use for identifying sparsity changes in grid sizes, using M_SPARSITY_DIMENSION_TOLERANCE. In this case, when calling M3dimLattice, you must store results in a lattice 3D image processing result buffer, so that you can then retrieve the results to set up an appropriate depth map image buffer or container for M3dimProject; for more information, see Generating fully corrected depth and intensity maps. When you call M3dimProject, all the points in a cell are projected into the same pixel of the depth map image buffer or depth map container. Empty cells or cells containing only invalid points will result in invalid pixels.

Parameters

LatticeContext3dimId (in, AIL_ID)

Specifies the identifier of the lattice 3D image processing context. The context must have been previously allocated using M3dimAlloc with M_LATTICE_CONTEXT.

ContainerBufId (in, AIL_ID)

Specifies the identifier of the source container containing a 3D-processable point cloud. The container must have been previously allocated using MbufAllocContainer with M_PROC, and must be 3D-processable (that is, if you call MbufInquireContainer with M_3D_PROCESSABLE, the function returns M_PROCESSABLE).

Box3dgeoId (in, AIL_ID)

Specifies the identifier of the axis-aligned 3D box geometry object that defines the space for which to calculate the lattice. Only points inside the box are used to calculate the lattice. The 3D box geometry object must have been previously allocated using M3dgeoAlloc with M_GEOMETRY, and defined as a box.

LatticeResultOrContext3dimId (out, AIL_ID)

Specifies the identifier of the lattice 3D image processing result buffer or subsample 3D image processing context in which to write the results.

For specifying the lattice 3D image processing result buffer or subsample 3D image processing context identifier

Value	Description
Lattice 3D image processing result buffer identifier	Specifies the identifier of a lattice 3D image processing result buffer, previously allocated using M3dimAllocResult with M_LATTICE_RESULT.
Subsample 3D image processing context identifier	Specifies the identifier of a subsample 3D image processing context, previously allocated using M3dimAlloc with M_SUBSAMPLE_CONTEXT. This sets the M_SUBSAMPLE_MODE control type of the subsample 3D image processing context to M_SUBSAMPLE_GRID and its M_GRID_SIZE_... control types to the cell sizes of the lattice results (M3dimGetResult with M_CELL_SIZE_...). If 1 of the cell dimensions is infinite, M_ORGANIZATION_TYPE is set to M_ORGANIZED.

Note that this is equivalent to specifying a lattice 3D image processing result buffer and using M3dimCopyResult with M_SUBSAMPLE_CONTEXT. |

ControlFlag (in, AIL_INT64)

Reserved for future expansion and must be set to M_DEFAULT.