Share via

INuiFusionReconstruction::ProcessFrame Method

  • Article

Kinect for Windows 1.7, 1.8

A high-level function to process a depth frame through the KinectFusion pipeline.

Specifically, this performs on-device processing equivalent to the following functions for each frame:

  1. AlignDepthFloatToReconstruction
  2. IntegrateFrame

Users may also optionally call the low-level functions individually, instead of calling this function, for more control. However, this function call will be faster due to the integrated nature of the calls. After this call completes successfully, if a visible output image of the reconstruction is required, the user can call CalculatePointCloud and then ShadePointCloud.

The maximum image resolution supported in this function is 640x480.

Note: If there is a tracking error in the AlignDepthFloatToReconstruction stage, no depth data integration will be performed, and the internal camera pose will remain unchanged.

Syntax

public:
HRESULT ProcessFrame(
         const NUI_FUSION_IMAGE_FRAME *pDepthFloatFrame,
         USHORT maxAlignIterationCount,
         USHORT maxIntegrationWeight,
         const Matrix4 *pWorldToCameraTransform
)

Parameters

  • pDepthFloatFrame
    Type: NUI_FUSION_IMAGE_FRAME
    A pointer to a floating point depth frame from the Kinect camera.
  • maxAlignIterationCount
    Type: USHORT
    The maximum number of iterations of the AlignDepthFloatToReconstruction to run. The minimum value is 1. Using only a small number of iterations will have a faster runtime; however, the algorithm may not converge to the correct transformation.
  • maxIntegrationWeight
    Type: USHORT
    A parameter to control the temporal smoothing of depth integration. Minimum value is 1. Lower values have more noisy representations, but objects that move integrate and disintegrate faster, so are suitable for more dynamic environments. Higher values integrate objects more slowly, but provide finer detail with less noise.
  • pWorldToCameraTransform
    Type: Matrix4
    Optionally, a pointer to a pre-allocated Matrix 4, with the best guess of the latest camera pose (e.g. the camera pose result from the last process call). If NULL is passed, the most recent internally stored pose from a call to AlignDepthFloatToReconstruction, ProcessFrame or IntegrateFrame is used to initialize the tracking.

Return Value

Type: HRESULT
Returns S_OK if successful; otherwise, returns one of the following failure codes:

Error code Description
E_INVALIDARG The pDepthFloatFrame parameter is NULL, or the pDepthFloatFrame parameter is an incorrect image size or type, or the maxAlignIterationCount parameter or the maxIntegrationWeight parameter is less than 1.
E_NOINTERFACE The pDepthFloatFrame parameter's pFrameTexture member is NULL.
E_NUI_FUSION_TRACKING_ERROR The AlignDepthFloatToReconstruction algorithm failed or did not converge.
E_NUI_FEATURE_NOT_INITIALIZED The Kinect camera runtime could not be accessed.
E_NUI_DEVICE_NOT_CONNECTED No Kinect camera could be found.
E_FAIL The call failed for an unknown reason.

Requirements

Header: Declared in KinectFusionExplorer.h.

Library: Use KinectFusion170_32.lib or KinectFusion170_64.lib, depending on the bitness of the target system being compiled..