ml_meshing2.h

Classes

	Name
struct	MLMeshingSettings
struct	MLMeshingExtents
struct	MLMeshingBlockInfo
struct	MLMeshingMeshInfo
struct	MLMeshingBlockRequest
struct	MLMeshingMeshRequest
struct	MLMeshingBlockMesh
struct	MLMeshingMesh

Types

	Name
typedef struct MLMeshingSettings	MLMeshingSettings
typedef struct MLMeshingExtents	MLMeshingExtents
typedef struct MLMeshingBlockInfo	MLMeshingBlockInfo
typedef struct MLMeshingMeshInfo	MLMeshingMeshInfo
typedef struct MLMeshingBlockRequest	MLMeshingBlockRequest
typedef struct MLMeshingMeshRequest	MLMeshingMeshRequest
typedef struct MLMeshingBlockMesh	MLMeshingBlockMesh
typedef struct MLMeshingMesh	MLMeshingMesh

Enums

	Name
enum	MLMeshingFlags { MLMeshingFlags_PointCloud = 1 << 0, MLMeshingFlags_ComputeNormals = 1 << 1, MLMeshingFlags_ComputeConfidence = 1 << 2, MLMeshingFlags_Planarize = 1 << 3, MLMeshingFlags_RemoveMeshSkirt = 1 << 4, MLMeshingFlags_IndexOrderCW = 1 << 5, MLMeshingFlags_Ensure32Bits = 0x7FFFFFFF }
enum	MLMeshingLOD { MLMeshingLOD_Minimum, MLMeshingLOD_Medium, MLMeshingLOD_Maximum, MLMeshingLOD_Ensure32Bits = 0x7FFFFFFF }
enum	MLMeshingResult { MLMeshingResult_Success, MLMeshingResult_Failed, MLMeshingResult_Pending, MLMeshingResult_PartialUpdate, MLMeshingResult_Ensure32Bits = 0x7FFFFFFF }
enum	MLMeshingMeshState { MLMeshingMeshState_New, MLMeshingMeshState_Updated, MLMeshingMeshState_Deleted, MLMeshingMeshState_Unchanged, MLMeshingMeshState_Ensure32Bits = 0x7FFFFFFF }

Functions

	Name
MLResult	MLMeshingCreateClient(MLHandle out_client_handle, const MLMeshingSettings settings) Create the meshing client.
MLResult	MLMeshingDestroyClient(MLHandle client_handle) Free the client resources.
MLResult	MLMeshingInitSettings(MLMeshingSettings * out_settings) Initialize the meshing settings with system defaults.
MLResult	MLMeshingUpdateSettings(MLHandle client_handle, const MLMeshingSettings * settings) Update the meshing settings at runtime.
MLResult	MLMeshingRequestMeshInfo(MLHandle client_handle, const MLMeshingExtents extents, MLHandle out_request_handle) Request the Mesh Info which includes CFUIDs and bounding extents of the blocks.
MLResult	MLMeshingGetMeshInfoResult(MLHandle client_handle, MLHandle request_handle, MLMeshingMeshInfo * out_info) Get the Result of a previous MeshInfo request.
MLResult	MLMeshingRequestMesh(MLHandle client_handle, const MLMeshingMeshRequest request, MLHandle out_request_handle) Request the Mesh for all CFUIDs populated in request.
MLResult	MLMeshingGetMeshResult(MLHandle client_handle, MLHandle request_handle, MLMeshingMesh * out_mesh) Get the Result of a previous Mesh request.
MLResult	MLMeshingFreeResource(MLHandle client_handle, MLHandle * request_handle) Free resources created by the meshing APIS. Needs to be called whenever MLMeshingGetMeshInfoResult, MLMeshingGetMeshResult return a success.

Enums Documentation

MLMeshingFlags

Enumerator	Value	Description
MLMeshingFlags_PointCloud	1 << 0	If set, will return a point cloud instead of a triangle mesh.
MLMeshingFlags_ComputeNormals	1 << 1	If set, the system will compute the normals for the triangle vertices.
MLMeshingFlags_ComputeConfidence	1 << 2	If set, the system will compute the confidence values.
MLMeshingFlags_Planarize	1 << 3	If set, the system will planarize the returned mesh (planar regions will be smoothed out).
MLMeshingFlags_RemoveMeshSkirt	1 << 4	If set, the mesh skirt (overlapping area between two mesh blocks) will be removed.
MLMeshingFlags_IndexOrderCW	1 << 5	If set, winding order of indices will be be changed from counter clockwise to clockwise. This could be useful for face culling process in different engines.
MLMeshingFlags_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Request flags for the meshing system.

---

MLMeshingLOD

Enumerator	Value	Description
MLMeshingLOD_Minimum		Minimum Level of Detail (LOD) for the mesh.
MLMeshingLOD_Medium		Medium Level of Detail (LOD) for the mesh.
MLMeshingLOD_Maximum		Maximum Level of Detail (LOD) for the mesh.
MLMeshingLOD_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Level of detail of the block mesh.

---

MLMeshingResult

Enumerator	Value	Description
MLMeshingResult_Success		Mesh request has succeeded.
MLMeshingResult_Failed		Mesh request has failed.
MLMeshingResult_Pending		Mesh request is pending.
MLMeshingResult_PartialUpdate		There are partial updates on the mesh request.
MLMeshingResult_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Result of a mesh request.

---

MLMeshingMeshState

Enumerator	Value	Description
MLMeshingMeshState_New		Mesh has been created.
MLMeshingMeshState_Updated		Mesh has been updated.
MLMeshingMeshState_Deleted		Mesh has been deleted.
MLMeshingMeshState_Unchanged		Mesh is unchanged.
MLMeshingMeshState_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

State of a block mesh.

---

Types Documentation

MLMeshingSettings

typedef struct MLMeshingSettings MLMeshingSettings;

Mesh Settings for the underlying system.

More Info

---

MLMeshingExtents

typedef struct MLMeshingExtents MLMeshingExtents;

Axis aligned bounding box for querying updated mesh info.

More Info

---

MLMeshingBlockInfo

typedef struct MLMeshingBlockInfo MLMeshingBlockInfo;

Representation of a mesh block.

More Info

---

MLMeshingMeshInfo

typedef struct MLMeshingMeshInfo MLMeshingMeshInfo;

Response structure for the mesh block info.

More Info

---

MLMeshingBlockRequest

typedef struct MLMeshingBlockRequest MLMeshingBlockRequest;

Request structure to get the actual mesh for a block.

More Info

---

MLMeshingMeshRequest

typedef struct MLMeshingMeshRequest MLMeshingMeshRequest;

Request structure to get the actual mesh for a set of blocks.

More Info

---

MLMeshingBlockMesh

typedef struct MLMeshingBlockMesh MLMeshingBlockMesh;

Final structure for a block mesh.

More Info

---

MLMeshingMesh

typedef struct MLMeshingMesh MLMeshingMesh;

Result of a Mesh request. See MLMeshingGetMeshResult() for details.

More Info

---

Functions Documentation

MLMeshingCreateClient

MLResult MLMeshingCreateClient(
    MLHandle * out_client_handle,
    const MLMeshingSettings * settings
)

Create the meshing client.

Parameters

MLHandle *	out_client_handle	The handle to the created client.
const MLMeshingSettings *	settings	The initial settings to be used for meshing.

Returns

MLResult	MLResult_InvalidParam	Meshing Client was not created due to an invalid parameter.
MLResult	MLResult_Ok	Meshing Client was created successfully.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_PermissionDenied	Missing required permission(s).
MLResult	MLResult_UnspecifiedFailure	Meshing Client was not created due to an unknown error.

Required Permissions:

• com.magicleap.permission.SPATIAL_MAPPING (protection level: dangerous)

Note that this will be the only function in the meshing API that will return MLResult_PermissionDenied. Trying to call the other functions with an invalid MLHandle will result in MLResult_InvalidParam.

---

MLMeshingDestroyClient

MLResult MLMeshingDestroyClient(
    MLHandle client_handle
)

Free the client resources.

Parameters

MLHandle	client_handle	The client to destroy.

Returns

MLResult	MLResult_InvalidParam	Meshing Client was not destroyed due to an invalid parameter.
MLResult	MLResult_Ok	Meshing Client was destroyed successfully.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.

Required Permissions:

• None

---

MLMeshingInitSettings

MLResult MLMeshingInitSettings(
    MLMeshingSettings * out_settings
)

Initialize the meshing settings with system defaults.

Parameters

MLMeshingSettings *	out_settings	The initial settings to be used for meshing.

Returns

MLResult	MLResult_InvalidParam	Mesh Settings were not initialized due to an invalid parameter.
MLResult	MLResult_Ok	Mesh Settings were initialized successfully.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.

Required Permissions:

• None

---

MLMeshingUpdateSettings

MLResult MLMeshingUpdateSettings(
    MLHandle client_handle,
    const MLMeshingSettings * settings
)

Update the meshing settings at runtime.

Parameters

MLHandle	client_handle	The handle to the created client.
const MLMeshingSettings *	settings	The updated settings to be used for meshing.

Returns

MLResult	MLResult_InvalidParam	Mesh Settings were not updated due to an invalid parameter.
MLResult	MLResult_Ok	Mesh Settings were updated successfully.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.

Required Permissions:

• None

---

MLMeshingRequestMeshInfo

MLResult MLMeshingRequestMeshInfo(
    MLHandle client_handle,
    const MLMeshingExtents * extents,
    MLHandle * out_request_handle
)

Request the Mesh Info which includes CFUIDs and bounding extents of the blocks.

Parameters

MLHandle	client_handle	The handle to the created client.
const MLMeshingExtents *	extents	The region of interest for meshing.
MLHandle *	out_request_handle	The handle for the current request. Needs to be passed to query the result of the request.

Returns

MLResult	MLResult_InvalidParam	Mesh info was not requested due to an invalid parameter.
MLResult	MLResult_Ok	Mesh Info was requested successfully.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.

Required Permissions:

• None

---

MLMeshingGetMeshInfoResult

MLResult MLMeshingGetMeshInfoResult(
    MLHandle client_handle,
    MLHandle request_handle,
    MLMeshingMeshInfo * out_info
)

Get the Result of a previous MeshInfo request.

Parameters

MLHandle	client_handle	The handle to the created client.
MLHandle	request_handle	The handle populated in a prev MLMeshingGetMeshInfo.
MLMeshingMeshInfo *	out_info	The final result which will be populated only if the result is successful.

Returns

MLResult	MLResult_InvalidParam	Mesh Settings were not updated due to an invalid parameter.
MLResult	MLResult_Ok	Mesh Info was populated successfully.
MLResult	MLResult_Peding	Mesh Info is pending update.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.

Required Permissions:

• None

---

MLMeshingRequestMesh

MLResult MLMeshingRequestMesh(
    MLHandle client_handle,
    const MLMeshingMeshRequest * request,
    MLHandle * out_request_handle
)

Request the Mesh for all CFUIDs populated in request.

Parameters

MLHandle	client_handle	The handle to the created client.
const MLMeshingMeshRequest *	request	The request for meshes of interest.
MLHandle *	out_request_handle	The handle for the current request. Needs to be passed to query the result of the request.

Returns

MLResult	MLResult_InvalidParam	Meshes were not requested due to an invalid parameter.
MLResult	MLResult_Ok	Meshes were requested successfully.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.

Required Permissions:

• None

---

MLMeshingGetMeshResult

MLResult MLMeshingGetMeshResult(
    MLHandle client_handle,
    MLHandle request_handle,
    MLMeshingMesh * out_mesh
)

Get the Result of a previous Mesh request.

Parameters

MLHandle	client_handle	The handle to the created client.
MLHandle	request_handle	The handle populated in a prev MLMeshingGetMesh.
MLMeshingMesh *	out_mesh	The final result which will be populated only if the result is successful.

Returns

MLResult	MLResult_InvalidParam	Meshes were not updated due to an invalid parameter.
MLResult	MLResult_Ok	Meshes was populated successfully.
MLResult	MLResult_Peding	Meshes pending update.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.

Required Permissions:

• None

---

MLMeshingFreeResource

MLResult MLMeshingFreeResource(
    MLHandle client_handle,
    MLHandle * request_handle
)

Free resources created by the meshing APIS. Needs to be called whenever MLMeshingGetMeshInfoResult, MLMeshingGetMeshResult return a success.

Parameters

MLHandle	client_handle	The handle to the created client.
MLHandle *	request_handle	The handle populated in a prev request.

Returns

MLResult	MLResult_InvalidParam	Resources were not freed due to an invalid parameter.
MLResult	MLResult_Ok	Resources were freed successfully.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.

Required Permissions:

• None

---

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2017 Magic Leap, Inc. All Rights Reserved.
// Use of this file is governed by the Software License Agreement,
// located here: https://www.magicleap.com/software-license-agreement-ml2
// Terms and conditions applicable to third-party materials accompanying
// this distribution may also be found in the top-level NOTICE file
// appearing herein.
// %COPYRIGHT_END%
// ---------------------------------------------------------------------
// %BANNER_END%

#pragma once

#include "ml_api.h"
#include "ml_types.h"

ML_EXTERN_C_BEGIN

typedef enum MLMeshingFlags {
  MLMeshingFlags_PointCloud = 1 << 0,
  MLMeshingFlags_ComputeNormals = 1 << 1,
  MLMeshingFlags_ComputeConfidence = 1 << 2,
  MLMeshingFlags_Planarize = 1 << 3,
  MLMeshingFlags_RemoveMeshSkirt = 1 << 4,
  MLMeshingFlags_IndexOrderCW = 1 << 5,
  MLMeshingFlags_Ensure32Bits = 0x7FFFFFFF
} MLMeshingFlags;

typedef enum MLMeshingLOD {
  MLMeshingLOD_Minimum,
  MLMeshingLOD_Medium,
  MLMeshingLOD_Maximum,
  MLMeshingLOD_Ensure32Bits = 0x7FFFFFFF
} MLMeshingLOD;

typedef enum MLMeshingResult {
  MLMeshingResult_Success,
  MLMeshingResult_Failed,
  MLMeshingResult_Pending,
  MLMeshingResult_PartialUpdate,
  MLMeshingResult_Ensure32Bits = 0x7FFFFFFF
} MLMeshingResult;

typedef enum MLMeshingMeshState {
  MLMeshingMeshState_New,
  MLMeshingMeshState_Updated,
  MLMeshingMeshState_Deleted,
  MLMeshingMeshState_Unchanged,
  MLMeshingMeshState_Ensure32Bits = 0x7FFFFFFF
} MLMeshingMeshState;

typedef struct MLMeshingSettings {
  uint32_t flags;
  float fill_hole_length;
  float disconnected_component_area;
} MLMeshingSettings;

typedef struct MLMeshingExtents {
  MLVec3f center;
  MLQuaternionf rotation;
  MLVec3f extents;
} MLMeshingExtents;

typedef struct MLMeshingBlockInfo {
  MLCoordinateFrameUID id;
  MLMeshingExtents extents;
  MLTime timestamp;
  MLMeshingMeshState state;
} MLMeshingBlockInfo;

typedef struct MLMeshingMeshInfo {
  MLTime timestamp;
  uint32_t data_count;
  MLMeshingBlockInfo *data;
} MLMeshingMeshInfo;

typedef struct MLMeshingBlockRequest {
  MLCoordinateFrameUID id;
  MLMeshingLOD level;
} MLMeshingBlockRequest;

typedef struct MLMeshingMeshRequest {
  int request_count;
  MLMeshingBlockRequest *data;
} MLMeshingMeshRequest;

typedef struct MLMeshingBlockMesh {
  MLMeshingResult result;
  MLCoordinateFrameUID id;
  MLMeshingLOD level;
  uint32_t flags;
  uint16_t index_count;
  uint32_t vertex_count;
  MLVec3f *vertex;
  uint16_t *index;
  MLVec3f *normal;
  float *confidence;
} MLMeshingBlockMesh;

typedef struct MLMeshingMesh {
  MLMeshingResult result;
  MLTime timestamp;
  uint32_t data_count;
  MLMeshingBlockMesh *data;
} MLMeshingMesh;

ML_API MLResult ML_CALL MLMeshingCreateClient(MLHandle *out_client_handle, const MLMeshingSettings *settings);

ML_API MLResult ML_CALL MLMeshingDestroyClient(MLHandle client_handle);

ML_API MLResult ML_CALL MLMeshingInitSettings(MLMeshingSettings *out_settings);

ML_API MLResult ML_CALL MLMeshingUpdateSettings(MLHandle client_handle, const MLMeshingSettings *settings);

ML_API MLResult ML_CALL MLMeshingRequestMeshInfo(MLHandle client_handle, const MLMeshingExtents *extents, MLHandle *out_request_handle);

ML_API MLResult ML_CALL MLMeshingGetMeshInfoResult(MLHandle client_handle, MLHandle request_handle, MLMeshingMeshInfo *out_info);

ML_API MLResult ML_CALL MLMeshingRequestMesh(MLHandle client_handle, const MLMeshingMeshRequest *request, MLHandle *out_request_handle);

ML_API MLResult ML_CALL MLMeshingGetMeshResult(MLHandle client_handle, MLHandle request_handle, MLMeshingMesh *out_mesh);

ML_API MLResult ML_CALL MLMeshingFreeResource(MLHandle client_handle, MLHandle *request_handle);

ML_EXTERN_C_END