InstantMeshing

Main entry point: instance lifecycle, scan integration, mesh/union generation, and utility functions.

Lifecycle

phoim_Result phoim_Create(void **handle, const phoim_DeviceParameters *devices, size_t device_count, phoim_Settings settings, phoim_MessageCallback msg_callback, void *optional_data)

Creates a new Instant Meshing instance configured for processing scans from independent devices sequentially using the AddScan function (non-batch mode). The instance must be terminated by a call to phoim_Destroy function.

Parameters:

handle – Output argument that receives a pointer to the created Instant Meshing instance.
devices – An array of parameters for all devices that will be used later in AddScan.
device_count – Number of devices in the devices array.
settings – Configuration for the meshing process (independent of device settings).
msg_callback – Function pointer for receiving log messages and critical events during processing.
optional_data – An optional pointer to user data that will be passed to the callback.

Returns:

Error code indicating success or the reason for failure.

phoim_Result phoim_CreateWithBatches(void **handle, const phoim_DeviceParametersBatch *device_batches, size_t batch_count, phoim_Settings settings, phoim_MessageCallback msg_callback, void *optional_data)

Creates a new Instant Meshing instance configured for batch scan processing using the AddScanBatch function. The instance must be terminated by a call to phoim_Destroy function.

Parameters:

handle – Output argument that receives a pointer to the created Instant Meshing instance.
device_batches – An array of device parameter batches, where each batch contains device parameters for a group of devices that will be processed together via AddScanBatch.
batch_count – Number of batches in the device_batches array.
settings – Configuration for the meshing process (independent of device settings).
msg_callback – Function pointer for receiving log messages and critical events during processing.
optional_data – An optional pointer to user data that will be passed to the callback.

Returns:

Error code indicating success or the reason for failure.

void phoim_Destroy(void **handle)

Destroys an instance of Instant Meshing.

Parameters:: handle – Pointer to a handle to the instance to destroy. The handle will be set to NULL.

phoim_Result phoim_Clear(void *handle)

Clear scene. This call removes all data that has been added, but preserves cropping volume and keeps all added devices.

Parameters:: handle – Pointer to an Instant Meshing instance on which the operation will be performed.
Returns:: Error code indicating success or the reason for failure.

phoim_Result phoim_ResetTracking(void *handle)

Resets tracking, which results in all data being aligned to the camera space of the next added scan.

Note

Already added scans will remain in the same space as they were added and aligned.

Parameters:: handle – Pointer to an Instant Meshing instance on which the operation will be performed.
Returns:: Error code indicating success or the reason for failure.

Scan Integration

phoim_Result phoim_AddScan(void *handle, phoim_InputScan scan, utils_Mat4f *result_transformation)

Integrates an additional scan to the volumetric structure.

1) Processing order:

First, this transformation is applied to the scan
It overrides any implicit camera space transformation from the input scan (CurrentCameraPosition, CurrentCameraXAxis, CurrentCameraYAxis, CurrentCameraZAxis)
Then, if defined, the calibration_matrix from DeviceParams is applied

2) Behavior depends on when it’s used:

First call with a specific device_id:
- Acts like a permanent calibration (similar to calibration_matrix in DeviceParams)
- If calibration_matrix is also defined (non-identity), both transformations are applied
Subsequent calls with the same device_id:
- Acts as a starting point for tracking (if tracking is enabled)
- Or as the final scan transformation (if tracking is disabled)

All matrices (input transformation and result_transformation) are in column-major format.

Note

The transformation matrix of the input scan is optional (set to phoim_INVALID_MATRIX if not used). When provided, it affects scan processing in the following ways:

Parameters:

handle – Pointer to an Instant Meshing instance on which the operation will be performed.
scan – Input scan with device ID and transformation (see the note below). The content of the scan frame is internally copied.
result_transformation – [out] Pointer to transformation matrix to be filled with the result. The matrix represent a transformation from camera space of the input scan to the mesh space. If tracking is enabled but unsuccessful, will be set to phoim_INVALID_MATRIX.

Returns:

Error code indicating success or the reason for failure.

phoim_Result phoim_AddScanBatch(void *handle, phoim_InputScan *scans, size_t scan_count, utils_Mat4f *result_transformation)

Integrates a batch of scans to the volumetric structure simultaneously. All scans in the batch are tracked together, resulting in a single transformation for the entire batch.

Note

All matrices (input transformations and result_transformation) are in column-major format.

Parameters:

handle – Pointer to an Instant Meshing instance on which the operation will be performed.
scans – Array of input scans with their device IDs and transformations. All scans must correspond to the same batch of devices (one of the batches provided during creation). The content of each scan is internally copied.
scan_count – Number of scans in the scans array.
result_transformation – [out] Pointer to transformation matrix to be filled with the result. Transformation matrix from batch space of input scans to the mesh space. This matrix needs to be multiplied by the relative transformation of a specific device to achieve the final transformation of a specific scan. If tracking is enabled but unsuccessful, will be set to phoim_INVALID_MATRIX.

Returns:

Error code indicating success or the reason for failure.

Virtual Scanning

phoim_Result phoim_GetVirtualScanPerspective(void *handle, const phoim_CameraParamsPerspective camera_params, const bool camera_space, phoim_Scan *result_scan)

Creates a virtual 3D scan of the internal volumetric structure from an arbitrary viewpoint using perspective projection without requiring full mesh computation.

Note

This operation uses additional GPU memory beyond the max_gpu_memory_usage setting.

Parameters:

handle – Pointer to an Instant Meshing instance on which the operation will be performed.
camera_params – Parameters of the perspective virtual camera including resolution, position, orientation basis, camera intrinsics, and other settings.
camera_space – If true, the resulting scan will be in the camera space defined by camera_params; if false, it will be in the mesh space.
result_scan – [out] Pointer to scan structure to be filled with the virtual scan data that contains 3D data of the volumetric structure containing all previously added scans. The scan must be freed using phoim_FreeScan when no longer needed.

Returns:

Error code indicating success or the reason for failure.

phoim_Result phoim_GetVirtualScanOrthogonal(void *handle, phoim_CameraParamsOrthogonal camera_params, bool camera_space, phoim_Scan *result_scan)

Creates a virtual 3D scan of the internal volumetric structure from an arbitrary viewpoint using orthogonal projection without requiring full mesh computation.

Note

This operation uses additional GPU memory beyond the max_gpu_memory_usage setting.

Parameters:

handle – Pointer to an Instant Meshing instance on which the operation will be performed.
camera_params – Parameters of the orthogonal virtual camera including resolution, position, orientation basis, orthogonal box width and height, and other settings.
camera_space – If true, the resulting scan will be in the camera space defined by camera_params; if false, it will be in the mesh space.
result_scan – [out] Pointer to scan structure to be filled with the virtual scan data that contains 3D data of the volumetric structure containing all previously added scans. The scan must be freed using phoim_FreeScan when no longer needed.

Returns:

Error code indicating success or the reason for failure.

Output Extraction

phoim_Result phoim_GetMesh(void *handle, const phoim_CroppingVolume cropping_volume, phoim_ProgressCallback progress_callback, void *optional_data, phoim_Mesh *result_mesh)

Computes union of all added scans within the specified cropping volume as a single triangle mesh.

Note

The mesh can be exported using phoim_ExportMesh function in GeometryUtils.h header.

Parameters:

handle – Pointer to an Instant Meshing instance on which the operation will be performed.
cropping_volume – Defines the 3D volume boundary for mesh generation. Only surfaces inside this volume will be included in the resulting mesh.
progress_callback – Function pointer for receiving progress updates during mesh generation. Progress values range from 0.0 (started) to 1.0 (completed). Can be NULL if progress reporting is not needed.
optional_data – An optional pointer to user data that will be passed to the progress callback.
result_mesh – [out] Pointer to mesh structure to be filled with the generated mesh data. The mesh needs to be freed via phoim_FreeMesh after use.

Returns:

Error code indicating success or the reason for failure.

phoim_Result phoim_GetUnionPerspective(void *handle, const phoim_CameraParamsPerspective *camera_views, const size_t view_count, phoim_PointCloud *result_point_cloud)

Generates virtual scans based on input perspective camera views and returns them as a single point cloud. The point cloud can be exported using phoim_ExportPointCloud.

Note

Mind the number of camera_views as this method is quite CPU memory heavy. The union point cloud can be exported using phoim_ExportPointCloud function from GeometryUtils.h header.

Parameters:

handle – Pointer to an Instant Meshing instance on which the operation will be performed.
camera_views – Array of perspective camera views based on which virtual scans are generated.
view_count – Number of camera views in the camera_views array.
result_point_cloud – [out] Pointer to a non-organized point cloud structure to be filled with the generated data. It needs to be freed via phoim_FreePointCloud after use.

Returns:

Error code indicating success or the reason for failure.

phoim_Result phoim_GetUnionOrthogonal(void *handle, const phoim_CameraParamsOrthogonal *camera_views, const size_t view_count, phoim_PointCloud *result_point_cloud)

Generates virtual scans based on input orthogonal camera views and returns them as a single point cloud. The point cloud can be exported using phoim_ExportPointCloud.

Note

Mind the number of camera_views as this method is quite CPU memory heavy. The union point cloud can be exported using phoim_ExportPointCloud function from GeometryUtils.h header.

Parameters:

handle – Pointer to an Instant Meshing instance on which the operation will be performed.
camera_views – Array of orthogonal camera views based on which virtual scans are generated.
view_count – Number of camera views in the camera_views array.
result_point_cloud – [out] Pointer to a non-organized point cloud structure to be filled with the generated data. It needs to be freed via phoim_FreePointCloud after use.

Returns:

Error code indicating success or the reason for failure.

Cropping Volume

phoim_Result phoim_SetCroppingVolume(void *handle, const phoim_CroppingVolume cropping_volume)

Defines a 3D boundary volume for filtering newly added scan data. Only surfaces inside this volume will be added to the volumetric structure.

Note

The filtering occurs after scan alignment to the existing data
This setting only affects future scans; existing data remains unchanged
To remove this filter, use phoim_ResetCroppingVolume()

Parameters:

handle – Pointer to an Instant Meshing instance on which the operation will be performed.
cropping_volume – The 3D volume boundary.

Returns:

Error code indicating success or the reason for failure.

phoim_Result phoim_ResetCroppingVolume(void *handle)

Removes the 3D boundary volume filter previously set by phoim_SetCroppingVolume.

Note

Disables any active cropping volume filter, allowing all newly added scan data to be processed regardless of spatial position. This only affects future scans, existing filtered data cannot be recovered.

Parameters:: handle – Pointer to an Instant Meshing instance on which the operation will be performed.
Returns:: Error code indicating success or the reason for failure.

Types & Constants

enum phoim_Result

Error codes returned by C API functions. Use GetErrorDescription() to get human-readable error messages.

Values:

enumerator PHOIM_SUCCESS

enumerator PHOIM_ERROR_INVALID_LICENSE

enumerator PHOIM_ERROR_GPU_NOT_FOUND

enumerator PHOIM_ERROR_RESOURCE_LIMIT

enumerator PHOIM_ERROR_GPU_MEMORY

enumerator PHOIM_ERROR_CONFIG_VALUE

enumerator PHOIM_ERROR_DEVICE_PARAMS

enumerator PHOIM_ERROR_INVALID_ARGUMENT

enumerator PHOIM_ERROR_VULKAN_INIT

enumerator PHOIM_ERROR_VULKAN_RENDER

enumerator PHOIM_ERROR_CUDA

enumerator PHOIM_ERROR_DATA_SIZE_MISMATCH

enumerator PHOIM_ERROR_RENDER

enumerator PHOIM_ERROR_INTERNAL

enumerator PHOIM_ERROR_UNKNOWN

enum phoim_MessageType

Type of message returned via the message callback.

Values:

enumerator debug

enumerator info

enumerator warning

enumerator error

enumerator critical

enumerator _unspecified

struct phoim_InputScan: Scan from an actual device with its transformation.

typedef void (*phoim_MessageCallback)(phoim_MessageType type, const char *message, void *optional_data)

Message callback function type.

Param type:: The type of message being delivered.
Param message:: Pointer to a read-only, null-terminated string containing the message. The caller retains ownership of this memory. Do not attempt to free it.
Param optional_data:: An optional pointer to user data that will be passed to the callback.

typedef void (*phoim_ProgressCallback)(float progress, void *optional_data)

Progress callback function type for reporting progress of long-running operations.

Param progress:: Progress value in range [0.0, 1.0] where 0.0 means just started and 1.0 means completed.
Param optional_data:: An optional pointer to user data that will be passed to the callback.

const utils_Mat4f phoim_IDENTITY_MATRIX: 4x4 identity transformation matrix (column-major). Provided as a convenience reference — represents no transformation.

const utils_Mat4f phoim_INVALID_MATRIX: 4x4 matrix indicating an invalid or unavailable transformation (column-major). Returned by phoim_AddScan when tracking is enabled but fails. Compare the return value against this constant to detect tracking loss.

Utilities

const char *phoim_GetErrorDescription(phoim_Result result_code)

Get human-readable description for error code.

Parameters:: result_code – Result code to describe.
Returns:: Description for the error.

const char *phoim_GetVersion()

Get the library version string.

Returns:: Null-terminated version string (e.g. “2.3.0”). The returned pointer is valid for the lifetime of the library.

char *phoim_SerializeDeviceParameters(phoim_DeviceParameters params)

Serialize Device Parameters to JSON string.

Parameters:: params – Device Parameters struct.
Returns:: C string representation of Device Parameters in JSON format. The returned string needs to be freed using phoim_FreeCString after use.

void phoim_DeserializeDeviceParameters(const char *json_params, phoim_DeviceParameters *device_params)

Deserialize Device Parameters from JSON and update existing struct.

Parameters:

json_params – C string representation of Device Parameters in JSON format.
device_params – [out] Pointer to device parameters structure to be filled with deserialized values.

void phoim_FreeCString(char *str)

Frees a C string allocated by the API functions like phoim_SerializeDeviceParameters.

Parameters:: str – The C string to free. If NULL, no operation is performed.