目录

spatial_recon_interface.h

Overview

3D spatial reconstruction task design module, which generates 3D scenes by processing multi-view image inputs.

File to include: <spatial/spatial_recon_interface.h>

Library: libspatial_recon_ndk.z.so

System capability: SystemCapability.Graphics.SpatialRecon

Since: 6.1.0(23)

Related module: SpatialRecon

Summary

[h2]Structs

Name typedef Keyword Description
HMS_SpatialRecon_ModelWriteInfo - Defines the struct for writing spatial reconstruction model data.
HMS_SpatialRecon_DataFrame HMS_SpatialRecon_DataFrame Defines the struct for the Huawei Mobile Services (HMS) spatial reconstruction data frame, containing the camera intrinsics, pose information, timestamps, and image data used for spatial reconstruction.
HMS_SpatialRecon_Session HMS_SpatialRecon_Session Defines the struct for the spatial reconstruction session handle, which is used for 3D scene reconstruction.
AREngine_ARSession AREngine_ARSession Defines an opaque handle to an AR session in Huawei AR Engine.
AREngine_ARFrame AREngine_ARFrame Defines the struct for storing a single frame of AR image data captured in AR Engine, containing the camera image, tracking status, anchors, and AR-related information at a specific timestamp.

[h2]Enums

Name typedef Keyword Description
HMS_SpatialReconStatus HMS_SpatialReconStatus Enumerates the operational statuses of spatial reconstruction.
HMS_SpatialReconOutputFormat HMS_SpatialReconOutputFormat Enumerates the output formats of the spatial reconstruction model.
HMS_SpatialReconRunningMode HMS_SpatialReconRunningMode Enumerates the spatial reconstruction running modes.
HMS_SpatialReconStage HMS_SpatialReconStage Enumerates the phases of the 3D reconstruction pipeline. This enum defines all possible states in the spatial reconstruction process, from initialization to completion or termination.
HMS_SpatialReconModelType HMS_SpatialReconModelType Enumerates the spatial reconstruction model types. Currently, only the 3D Gaussian Splatting (3DGS) model is supported.
HMS_SpatialReconImageDataFormat HMS_SpatialReconImageDataFormat Enumerates the image data formats of spatial reconstruction. Currently, only the RGB format is supported.

[h2]Functions

Name typedef Keyword Description
typedef void (*HMS_SpatialReconCallbackFunc)(HMS_SpatialReconStatus) HMS_SpatialReconCallbackFunc Defines the callback function used for handling spatial reconstruction status updates. This callback is called when the system provides updates regarding the spatial reconstruction process.
HMS_SpatialReconStatus HMS_SpatialRecon_IsSupport(HMS_SpatialReconModelType type) - Queries whether the current device supports the specified spatial reconstruction model type. This function checks the capability of the device to execute spatial reconstruction using the given model type.
HMS_SpatialReconStatus HMS_SpatialRecon_CreateSession(HMS_SpatialReconModelType type, const char* workPath, HMS_SpatialRecon_Session **outSpatialReconSession) - Creates a new spatial reconstruction session.
HMS_SpatialReconStatus HMS_SpatialRecon_DestroySession(HMS_SpatialRecon_Session *spatialReconSession) - Destroys a spatial reconstruction session and releases its resources. This function terminates the spatial reconstruction session and frees all memory and system resources associated with it. After this function is called, the provided session pointer becomes invalid and should not be used any more.
HMS_SpatialReconStatus HMS_SpatialRecon_PushFrame(HMS_SpatialRecon_Session *spatialReconSession, HMS_SpatialRecon_DataFrame *inputFrame) - Pushes a spatial reconstruction data frame into a spatial reconstruction session for processing. This function submits the captured spatial data frame to the reconstruction session, which uses this data to update or refine its internal spatial model.
HMS_SpatialReconStatus HMS_SpatialRecon_PushARFrame(HMS_SpatialRecon_Session *spatialReconSession, AREngine_ARSession* arSession, AREngine_ARFrame *arFrame) - Pushes an AREngine frame from an AREngine session into a spatial reconstruction session. This function submits the AREngine frame, containing camera images, poses, and AR tracking data, to the spatial reconstruction session, allowing the reconstruction system to leverage real-time AR tracking information (such as camera poses and feature points) to enhance spatial mapping.
HMS_SpatialReconStatus HMS_SpatialRecon_StartSession(HMS_SpatialRecon_Session *spatialReconSession, HMS_SpatialRecon_ModelWriteInfo* writeInfo, HMS_SpatialReconCallbackFunc onSpatialReconFinished) - Starts a spatial reconstruction session. This function executes asynchronously and reports the completion status through a callback.
HMS_SpatialReconStatus HMS_SpatialRecon_SetRunningMode(HMS_SpatialRecon_Session *spatialReconSession, HMS_SpatialReconRunningMode runningMode) - Sets the running mode for a spatial reconstruction session.
HMS_SpatialReconStatus HMS_SpatialRecon_PauseSession(HMS_SpatialRecon_Session *spatialReconSession) - Pauses an ongoing spatial reconstruction session.
HMS_SpatialReconStatus HMS_SpatialRecon_ResumeSession(HMS_SpatialRecon_Session *spatialReconSession) - Resumes a paused spatial reconstruction session.
HMS_SpatialReconStatus HMS_SpatialRecon_GetProgress(HMS_SpatialRecon_Session *spatialReconSession, float* progress, HMS_SpatialReconStage* stage) - Retrieves the progress of the current task. This function queries the progress ratio of an ongoing task (for example, reconstruction or saving) and returns the result via a pointer variable.
HMS_SpatialReconStatus HMS_SpatialRecon_GetRefinedFrame(HMS_SpatialRecon_Session *spatialReconSession, int iFrame, HMS_SpatialRecon_DataFrame *outFrame) - Retrieves the optimized camera frame from a spatial reconstruction session. This function provides the reconstructed and optimized camera intrinsic and extrinsic parameters for the specified frame index.
HMS_SpatialReconStatus HMS_SpatialRecon_SaveResultToFile(HMS_SpatialRecon_Session *spatialReconSession, HMS_SpatialRecon_ModelWriteInfo *writeInfo, HMS_SpatialReconCallbackFunc onSaved) - Saves the spatial reconstruction results to a file. This function exports the processed spatial reconstruction data to the specified file format. This function executes asynchronously and reports the completion status through a callback.
typedef void (*HMS_SpatialReconNGCallbackFunc)(HMS_SpatialReconStatus, void*) HMS_SpatialReconNGCallbackFunc Callback function that supports custom input parameters.
HMS_SpatialReconStatus HMS_SpatialRecon_RegisterNGCallbackFunc(HMS_SpatialRecon_Session* spatialReconSession, HMS_SpatialReconNGCallbackFunc onTaskFinished, void* data) - Registers the callback function that supports custom input parameters.

Enumeration Description

[h2]HMS_SpatialReconStatus

enum HMS_SpatialReconStatus

Description

Enumerates the operational statuses of spatial reconstruction.

Since: 6.1.0(23)

Value Description
SPATIAL_RECON_STATUS_SUCCESS = 0 The spatial reconstruction is successful.
SPATIAL_RECON_STATUS_EXCEEDS_MAXIMUM = 1023700001 The number of spatial reconstruction frames exceeds the maximum.
SPATIAL_RECON_STATUS_DEVICE_NOT_SUPPORT = 801 The current device does not support spacial reconstruction.
SPATIAL_RECON_STATUS_INVALID_WORK_PATH = 1023700002 The input working path is invalid.
SPATIAL_RECON_STATUS_INVALID_FRAME_DATA = 1023700003 The input frame data is invalid.
SPATIAL_RECON_STATUS_STAGE_NOT_INITIALIZED = 1023700004 The session is not initialized.
SPATIAL_RECON_STATUS_STAGE_BUILDING = 1023700005 The reconstruction session has started.
SPATIAL_RECON_STATUS_STAGE_NOT_FINISHED = 1023700006 The reconstruction session is not complete.
SPATIAL_RECON_STATUS_FAILED = 1023700007 The spacial reconstruction failed.

[h2]HMS_SpatialReconOutputFormat

enum HMS_SpatialReconOutputFormat

Description

Enumerates the output formats of the spatial reconstruction model.

Since: 6.1.0(23)

Value Description
SPATIAL_RECON_OUTPUT_FORMAT_PLY PLY format.
SPATIAL_RECON_OUTPUT_FORMAT_MP4 MPEG-4 video format.

[h2]HMS_SpatialReconRunningMode

enum HMS_SpatialReconRunningMode

Description

Enumerates the spatial reconstruction running modes.

The SpatialRecon session supports two running modes: foreground and background. When an app is switched to the background or returns to the foreground, you need to call HMS_SpatialRecon_SetRunningMode() to allow the system to optimize power consumption for each running mode.

Since: 6.1.0(23)

Value Description
SPATIAL_RECON_RUNNING_FOREGROUND_MODE Foreground mode (default value). When spatial reconstruction is performed in the foreground, the system allocates more resources to the reconstruction task to ensure a faster reconstruction speed.
SPATIAL_RECON_RUNNING_BACKGROUND_MODE Background mode. When spatial reconstruction is running in the background, the system preferentially processes the operations of foreground apps, resulting in a slower reconstruction speed.

[h2]HMS_SpatialReconStage

enum HMS_SpatialReconStage

Description

Enumerates the phases of the 3D reconstruction pipeline. This enum defines all possible states in the spatial reconstruction process, from initialization to completion or termination.

Since: 6.1.0(23)

Value Description
SPATIAL_RECON_STAGE_INIT Initialization stage: Resources and environment are being prepared.
SPATIAL_RECON_STAGE_BUILDING Reconstruction stage: The data is being processed and a 3D model is being built.
SPATIAL_RECON_STAGE_PAUSED The reconstruction process has been paused.
SPATIAL_RECON_STAGE_FINISHED The reconstruction is successfully completed.
SPATIAL_RECON_STAGE_SAVING Saving stage: The 3D model is being saved as a file.
SPATIAL_RECON_STAGE_UNKNOWN The stage is unknown or uncertain.

[h2]HMS_SpatialReconModelType

enum HMS_SpatialReconModelType

Description

Enumerates the spatial reconstruction model types. Currently, only the 3DGS model is supported.

Since: 6.1.0(23)

Value Description
SPATIAL_RECON_MODEL_TYPE_GS 3DGS model used for scene reconstruction.

[h2]HMS_SpatialReconImageDataFormat

enum HMS_SpatialReconImageDataFormat

Description

Enumerates the image data formats of spatial reconstruction. Currently, only the RGB format is supported.

Since: 6.1.0(23)

Value Description
SPATIAL_RECON_IMAGEDATA_FORMAT_RGB RGB format, a three-channel color representation method based on red, green, and blue.

Function Description

[h2]HMS_SpatialReconCallbackFunc()

typedef void (*HMS_SpatialReconCallbackFunc)(HMS_SpatialReconStatus)

Description

Defines the callback function used for handling spatial reconstruction status updates. This callback is called when the system provides updates regarding the spatial reconstruction process.

Since: 6.1.0(23)

Parameters:

Name Description
HMS_SpatialReconStatus Status of the spatial reconstruction process. HMS_SpatialReconStatus is used to identify the reconstruction result status.

[h2]HMS_SpatialRecon_IsSupport()

HMS_SpatialReconStatus HMS_SpatialRecon_IsSupport(HMS_SpatialReconModelType type)

Description

Queries whether the current device supports the specified spatial reconstruction model type. This function checks the capability of the device to execute spatial reconstruction using the given model type.

Support status may vary depending on device hardware, system version, or current environmental conditions.

Since: 6.1.0(23)

Parameters:

Name Description
HMS_SpatialReconModelType type Spatial reconstruction model type to be checked.

Returns:

Type Description
HMS_SpatialReconStatus Indicates whether the model type is supported.

[h2]HMS_SpatialRecon_CreateSession()

HMS_SpatialReconStatus HMS_SpatialRecon_CreateSession(HMS_SpatialReconModelType type, const char* workPath, HMS_SpatialRecon_Session **outSpatialReconSession)

Description

Creates a new spatial reconstruction session.

On devices that do not support the model type, the session object cannot be created, and the function will return an error. You can call HMS_SpatialRecon_IsSupport to check whether the current device supports the model type.

Since: 6.1.0(23)

Parameters:

Name Description
HMS_SpatialReconModelType type Type of the reconstruction model to be used. This determines the algorithm and capabilities of the reconstruction session.
const char* workPath File system path for storing reconstruction data and temporary files. The path must exist.
HMS_SpatialRecon_Session **outSpatialReconSession Output parameter, which is used to receive the pointer to the new spatial reconstruction session object. The caller is responsible for managing the lifecycle of the object and must destroy it using an appropriate cleanup function.

Returns:

Type Description
HMS_SpatialReconStatus Operation result.

[h2]HMS_SpatialRecon_DestroySession()

HMS_SpatialReconStatus HMS_SpatialRecon_DestroySession(HMS_SpatialRecon_Session *spatialReconSession)

Description

Destroys a spatial reconstruction session and releases its resources. This function terminates the spatial reconstruction session and frees all memory and system resources associated with it. After this function is called, the provided session pointer becomes invalid and should not be used any more.

Once a session is destroyed, it cannot be restored. All unsaved reconstruction data will be lost. To persist the data, call HMS_SpatialRecon_SaveResultToFile() to save the data before destroying the session.

Since: 6.1.0(23)

Parameters:

Name Description
HMS_SpatialRecon_Session *spatialReconSession Pointer to the spatial reconstruction session to be destroyed. The session must have been created. If the value is NULL, the function has no effect.

Returns:

Type Description
HMS_SpatialReconStatus Operation result.

[h2]HMS_SpatialRecon_PushFrame()

HMS_SpatialReconStatus HMS_SpatialRecon_PushFrame(HMS_SpatialRecon_Session *spatialReconSession, HMS_SpatialRecon_DataFrame *inputFrame)

Description

Pushes a spatial reconstruction data frame into a spatial reconstruction session for processing. This function submits the captured spatial data frame to the reconstruction session, which uses this data to update or refine its internal spatial model.

If HMS_SpatialRecon_StartSession is called to start the modeling process, the frame data cannot be successfully input.

Since: 6.1.0(23)

Parameters:

Name Description
HMS_SpatialRecon_Session *spatialReconSession Pointer to the handle to the spatial reconstruction session.
HMS_SpatialRecon_DataFrame *inputFrame Pointer to the spatial reconstruction data frame that contains the sensor data.

Returns:

Type Description
HMS_SpatialReconStatus Status code, which indicates the operation result.

[h2]HMS_SpatialRecon_PushARFrame()

HMS_SpatialReconStatus HMS_SpatialRecon_PushARFrame(HMS_SpatialRecon_Session *spatialReconSession, AREngine_ARSession* arSession, AREngine_ARFrame *arFrame)

Description

Pushes an AREngine frame from an AREngine session into a spatial reconstruction session. This function submits the AREngine frame, containing camera images, poses, and AR tracking data, to the spatial reconstruction session, allowing the reconstruction system to leverage real-time AR tracking information (such as camera poses and feature points) to enhance spatial mapping.

If HMS_SpatialRecon_StartSession is called to start the modeling process, the frame data cannot be successfully input.

Since: 6.1.0(23)

Parameters:

Name Description
HMS_SpatialRecon_Session *spatialReconSession Pointer to the handle to the spatial reconstruction session.
AREngine_ARSession* arSession Pointer to the AR Engine session that generates the AR Engine frame.
AREngine_ARFrame *arFrame Pointer to the AR Engine frame that contains the AR tracking data and camera image.

Returns:

Type Description
HMS_SpatialReconStatus Status code, which indicates the operation result.

[h2]HMS_SpatialRecon_StartSession()

HMS_SpatialReconStatus HMS_SpatialRecon_StartSession(HMS_SpatialRecon_Session *spatialReconSession, HMS_SpatialRecon_ModelWriteInfo* writeInfo, HMS_SpatialReconCallbackFunc onSpatialReconFinished)

Description

Starts a spatial reconstruction session. This function executes asynchronously and reports the completion status through a callback.

Since: 6.1.0(23)

Parameters:

Name Description
HMS_SpatialRecon_Session *spatialReconSession Pointer to the handle to the spatial reconstruction session. If spatialReconSession is null, the function returns an error code.
HMS_SpatialRecon_ModelWriteInfo* writeInfo Pointer to the model configuration information for writing. It contains the parameters of the reconstruction output. If the writeInfo pointer is null, no write operation is performed after the reconstruction is completed. In this case, you can call the HMS_SpatialRecon_SaveResultToFile API separately.
HMS_SpatialReconCallbackFunc onSpatialReconFinished Pointer to the callback function to be called after the reconstruction process is completed. The callback function can be set to NULL. In this case, no callback is triggered.

Returns:

Type Description
HMS_SpatialReconStatus Status code, which indicates success or a specific error.

[h2]HMS_SpatialRecon_SetRunningMode()

HMS_SpatialReconStatus HMS_SpatialRecon_SetRunningMode(HMS_SpatialRecon_Session *spatialReconSession, HMS_SpatialReconRunningMode runningMode)

Description

Sets the running mode for a spatial reconstruction session.

This function must be called after HMS_SpatialRecon_StartSession() and before the reconstruction is completed. If this function is called during an inactive session, no effect will be produced.

Since: 6.1.0(23)

Parameters:

Name Description
HMS_SpatialRecon_Session *spatialReconSession Pointer to the handle to the spatial reconstruction session.
HMS_SpatialReconRunningMode runningMode Expected running mode of spatial reconstruction.

Returns:

Type Description
HMS_SpatialReconStatus Status code, which indicates success or a specific error.

[h2]HMS_SpatialRecon_PauseSession()

HMS_SpatialReconStatus HMS_SpatialRecon_PauseSession(HMS_SpatialRecon_Session *spatialReconSession)

Description

Pauses an ongoing spatial reconstruction session.

Since: 6.1.0(23)

Parameters:

Name Description
HMS_SpatialRecon_Session *spatialReconSession Pointer to the handle to the spatial reconstruction session.

Returns:

Type Description
HMS_SpatialReconStatus Status code, which indicates the operation result. If no active session exists, an error is returned.

[h2]HMS_SpatialRecon_ResumeSession()

HMS_SpatialReconStatus HMS_SpatialRecon_ResumeSession(HMS_SpatialRecon_Session *spatialReconSession)

Description

Resumes a paused spatial reconstruction session.

Since: 6.1.0(23)

Parameters:

Name Description
HMS_SpatialRecon_Session *spatialReconSession Pointer to the handle to the spatial reconstruction session.

Returns:

Type Description
HMS_SpatialReconStatus Operation result. If the session is not paused, an error is returned.

[h2]HMS_SpatialRecon_GetProgress()

HMS_SpatialReconStatus HMS_SpatialRecon_GetProgress(HMS_SpatialRecon_Session *spatialReconSession, float* progress, HMS_SpatialReconStage* stage)

Description

Retrieves the progress of the current task. This function queries the progress ratio of an ongoing task (for example, reconstruction or saving) and returns the result via a pointer variable.

Once the HMS_SpatialRecon_SaveResultToFile function is called, the session will manually save the 3D model to a file. The returned progress will reflect only the progress of saving the file, not the entire process.

Since: 6.1.0(23)

Parameters:

Name Description
HMS_SpatialRecon_Session *spatialReconSession Pointer to a spatial reconstruction session instance.
float* progress Pointer to a floating-point variable for storing the progress ratio. The value ranges from 0.0f (0%) to 1.0f (100%). If the pointer is NULL, the function returns an error code.
HMS_SpatialReconStage* stage Pointer to a stage variable for storing the stage value. If the pointer is NULL, the stage value will not be written.

Returns:

Type Description
HMS_SpatialReconStatus Status code, which indicates success or a specific error.

[h2]HMS_SpatialRecon_GetRefinedFrame()

HMS_SpatialReconStatus HMS_SpatialRecon_GetRefinedFrame(HMS_SpatialRecon_Session *spatialReconSession, int iFrame, HMS_SpatialRecon_DataFrame *outFrame)

Description

Retrieves the optimized camera frame from a spatial reconstruction session. This function provides the reconstructed and optimized camera intrinsic and extrinsic parameters for the specified frame index.

This function does not return image pixel data, and the imageData parameter will be set to null.

Since: 6.1.0(23)

Parameters:

Name Description
HMS_SpatialRecon_Session *spatialReconSession Pointer to the handle to the spatial reconstruction session.
int iFrame Index of the frame to obtain. The value starts from 0.
HMS_SpatialRecon_DataFrame *outFrame Output parameter, which is used to store the optimized frame data.

Returns:

Type Description
HMS_SpatialReconStatus Status code, which indicates operation success or failure.

[h2]HMS_SpatialRecon_SaveResultToFile()

HMS_SpatialReconStatus HMS_SpatialRecon_SaveResultToFile(HMS_SpatialRecon_Session *spatialReconSession, HMS_SpatialRecon_ModelWriteInfo *writeInfo, HMS_SpatialReconCallbackFunc onSaved)

Description

Saves the spatial reconstruction results to a file. This function exports the processed spatial reconstruction data to the specified file format. This function executes asynchronously and reports the completion status through a callback.

If this function is called before the model building succeeds, it returns the SPATIAL_RECON_STATUS_STAGE_NOT_FINISHED status code.

Since: 6.1.0(23)

Parameters:

Name Description
HMS_SpatialRecon_Session *spatialReconSession Pointer to the handle to the spatial reconstruction object. The value cannot be NULL and must refer to a valid and active session.
HMS_SpatialRecon_ModelWriteInfo *writeInfo Pointer to the struct containing the file export parameters, such as the file path, format, and optional configuration flags. The value cannot be NULL.
HMS_SpatialReconCallbackFunc onSaved Pointer to the callback function to be called after the save operation is completed. If no callback is required, set this parameter to NULL.

Returns:

Type Description
HMS_SpatialReconStatus Initial verification status or an instant error (for example, invalid parameter). The actual result of file export is returned through the callback.

[h2]HMS_SpatialReconNGCallbackFunc()

typedef void (*HMS_SpatialReconNGCallbackFunc)(HMS_SpatialReconStatus, void*);

Description

Callback function that supports custom input parameters.

Since: 26.0.0

Parameters:

Name Description
HMS_SpatialReconStatus Status of the spatial reconstruction process. HMS_SpatialReconStatus is used to identify the reconstruction result status.
void* Custom input parameter to be passed to the callback function. You must ensure the security and correctness of data processing.

[h2]HMS_SpatialRecon_RegisterNGCallbackFunc()

HMS_SpatialReconStatus HMS_SpatialRecon_RegisterNGCallbackFunc(HMS_SpatialRecon_Session* spatialReconSession, HMS_SpatialReconNGCallbackFunc onTaskFinished, void* data);

Description

Registers the callback function that supports custom input parameters.

Similar to other industry-standard void* callbacks, you must ensure the safe and correct handling of the data pointer. Spatial Recon Kit performs no safety checks on the parsing or utilization of the input parameter data.

Since: 26.0.0

Parameters:

Name Description
HMS_SpatialRecon_Session *spatialReconSession Pointer to the handle to the spatial reconstruction object. The value cannot be NULL and must refer to a valid and active session.
HMS_SpatialReconNGCallbackFunc *onTaskFinished Address of the callback function with custom input parameters.
void* data Data to be passed to the callback function. You must ensure the security and correctness of data reading and processing.

Returns:

Type Description
HMS_SpatialReconStatus Initial verification status or an instant error (for example, invalid parameter).