Skip to main content
Version: 21 Aug 2024

ml_gesture_classification.h

Classes

Name
structMLGestureClassificationStaticData
Static information about the gesture classification.
structMLGestureClassificationPostureFingerData
Gesture classification posture related finger data.
structMLGestureClassificationFingerState
Gesture classification state of a single finger.
structMLGestureClassificationState
Gesture classification state of a single hand.
structMLGestureClassificationData
Data which is received when querying tracker from MLGestureClassificationGetData().

Types

Name
typedef struct MLGestureClassificationStaticDataMLGestureClassificationStaticData
Static information about the gesture classification.
typedef struct MLGestureClassificationPostureFingerDataMLGestureClassificationPostureFingerData
Gesture classification posture related finger data.
typedef struct MLGestureClassificationFingerStateMLGestureClassificationFingerState
Gesture classification state of a single finger.
typedef struct MLGestureClassificationStateMLGestureClassificationState
Gesture classification state of a single hand.
typedef struct MLGestureClassificationDataMLGestureClassificationData
Data which is received when querying tracker from MLGestureClassificationGetData().

Enums

Name
enumMLGestureClassificationHandType
{
MLGestureClassificationHandType_Left = 0,
MLGestureClassificationHandType_Right = 1,
MLGestureClassificationHandType_Count = 2,
MLGestureClassificationHandType_Ensure32Bits = 0x7FFFFFFF
}
enumMLGestureClassificationPostureType
{
MLGestureClassificationPostureType_None = 0,
MLGestureClassificationPostureType_Pinch = 1,
MLGestureClassificationPostureType_Point = 2,
MLGestureClassificationPostureType_Grasp = 3,
MLGestureClassificationPostureType_Open = 4,
MLGestureClassificationPostureType_Ensure32Bits = 0x7FFFFFFF
}
System gesture classification posture type.
enumMLGestureClassificationKeyPoseType
{
MLGestureClassificationKeyPoseType_None = 0,
MLGestureClassificationKeyPoseType_OK = 1,
MLGestureClassificationKeyPoseType_C = 2,
MLGestureClassificationKeyPoseType_Pinch = 3,
MLGestureClassificationKeyPoseType_Finger = 4,
MLGestureClassificationKeyPoseType_L = 5,
MLGestureClassificationKeyPoseType_Thumb = 6,
MLGestureClassificationKeyPoseType_Fist = 7,
MLGestureClassificationKeyPoseType_Open = 8,
MLGestureClassificationKeyPoseType_Ensure32Bits = 0x7FFFFFFF
}
System gesture classification key pose type.

Functions

Name
voidMLGestureClassificationStaticDataInit(MLGestureClassificationStaticData * inout_data)
Initializes default values for MLGestureClassificationStaticData.
voidMLGestureClassificationDataInit(MLGestureClassificationData * inout_data)
Initializes default values for MLGestureClassificationData.
MLResultMLGestureClassificationCreate(MLHandle * out_handle)
Creates a gesture classification tracker.
MLResultMLGestureClassificationDestroy(MLHandle handle)
Destroys a gesture classification tracker.
MLResultMLGestureClassificationGetStaticData(MLHandle handle, MLGestureClassificationStaticData * out_data)
Gets static information about the gesture classification.
MLResultMLGestureClassificationGetData(MLHandle handle, MLGestureClassificationData * out_data)
Queries the state of the gesture classification.

Enums Documentation

MLGestureClassificationHandType

EnumeratorValueDescription
MLGestureClassificationHandType_Left0Left hand.
MLGestureClassificationHandType_Right1Right hand.
MLGestureClassificationHandType_Count2Number of hands.
MLGestureClassificationHandType_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Available hand types.


MLGestureClassificationPostureType

EnumeratorValueDescription
MLGestureClassificationPostureType_None0None.
MLGestureClassificationPostureType_Pinch1Pinch posture.
MLGestureClassificationPostureType_Point2Point posture.
MLGestureClassificationPostureType_Grasp3Grasp posture.
MLGestureClassificationPostureType_Open4Open hand.
MLGestureClassificationPostureType_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

System gesture classification posture type.

API Level:

  • 20

MLGestureClassificationKeyPoseType

EnumeratorValueDescription
MLGestureClassificationKeyPoseType_None0None.
MLGestureClassificationKeyPoseType_OK1OK pose.
MLGestureClassificationKeyPoseType_C2C pose.
MLGestureClassificationKeyPoseType_Pinch3Pinch pose.
MLGestureClassificationKeyPoseType_Finger4Finger pose.
MLGestureClassificationKeyPoseType_L5L pose.
MLGestureClassificationKeyPoseType_Thumb6Thumb up pose.
MLGestureClassificationKeyPoseType_Fist7Fist pose.
MLGestureClassificationKeyPoseType_Open8Open pose.
MLGestureClassificationKeyPoseType_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

System gesture classification key pose type.

API Level:

  • 20

Types Documentation

MLGestureClassificationStaticData

typedef struct MLGestureClassificationStaticData MLGestureClassificationStaticData;

Static information about the gesture classification.

Populate with MLGestureClassificationGetStaticData(). This structure must be initialized by calling MLGestureClassificationStaticDataInit() before use.

More Info

API Level:

  • 20

MLGestureClassificationPostureFingerData

typedef struct MLGestureClassificationPostureFingerData MLGestureClassificationPostureFingerData;

Gesture classification posture related finger data.

Pinch values are measured between the finger and thumb. In case thumb is the finger, values are same with index's values.

More Info

API Level:

  • 20

MLGestureClassificationFingerState

typedef struct MLGestureClassificationFingerState MLGestureClassificationFingerState;

Gesture classification state of a single finger.

More Info

API Level:

  • 20

MLGestureClassificationState

typedef struct MLGestureClassificationState MLGestureClassificationState;

Gesture classification state of a single hand.

More Info

API Level:

  • 20

MLGestureClassificationData

typedef struct MLGestureClassificationData MLGestureClassificationData;

Data which is received when querying tracker from MLGestureClassificationGetData().

This structure must be initialized by calling MLGestureClassificationDataInit() before use.

More Info

API Level:

  • 20

Functions Documentation

MLGestureClassificationStaticDataInit

static inline void MLGestureClassificationStaticDataInit(
MLGestureClassificationStaticData * inout_data
)

Initializes default values for MLGestureClassificationStaticData.

Parameters

MLGestureClassificationStaticData *inout_dataThe object to initialize with default settings.

API Level:

  • 20

MLGestureClassificationDataInit

static inline void MLGestureClassificationDataInit(
MLGestureClassificationData * inout_data
)

Initializes default values for MLGestureClassificationData.

Parameters

MLGestureClassificationData *inout_dataThe object to initialize with default settings.

API Level:

  • 20

MLGestureClassificationCreate

MLResult MLGestureClassificationCreate(
MLHandle * out_handle
)

Creates a gesture classification tracker.

Parameters

MLHandle *out_handleA handle to the created gesture classification tracker. Only valid if the return value is MLResult_Ok.

Returns

MLResultMLResult_InvalidParamFailed to create a tracker due to an invalid parameter.
MLResultMLResult_OkThe tracker was created successfully.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_PrivilegeDeniedThe application lacks privilege.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • com.magicleap.permission.HAND_TRACKING (protection level: normal)

API Level:

  • 20

MLGestureClassificationDestroy

MLResult MLGestureClassificationDestroy(
MLHandle handle
)

Destroys a gesture classification tracker.

Parameters

MLHandlehandleA handle to a gesture classification tracker created by MLGestureClassificationCreate().

Returns

MLResultMLResult_InvalidParamFailed to destroy a tracker due to an invalid parameter.
MLResultMLResult_OkIt successfully destroyed the tracker.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None

API Level:

  • 20

MLGestureClassificationGetStaticData

MLResult MLGestureClassificationGetStaticData(
MLHandle handle,
MLGestureClassificationStaticData * out_data
)

Gets static information about the gesture classification.

Parameters

MLHandlehandleA handle to a gesture classification tracker created by MLGestureClassificationCreate().
MLGestureClassificationStaticData *out_dataTarget to populate the data about the gesture classification.

Returns

MLResultMLResult_InvalidParamFailed to get static data due to an invalid parameter.
MLResultMLResult_OkGesture classification static data was successfully received.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None

API Level:

  • 20

MLGestureClassificationGetData

MLResult MLGestureClassificationGetData(
MLHandle handle,
MLGestureClassificationData * out_data
)

Queries the state of the gesture classification.

Parameters

MLHandlehandleA handle to a gesture classification tracker created by MLGestureClassificationCreate().
MLGestureClassificationData *out_dataPointer to MLGestureClassificationData structure.

Returns

MLResultMLResult_InvalidParamFailed to retrieve data due to an invalid parameter.
MLResultMLResult_OkThe state information was available and the information in out_data is valid.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_UnspecifiedFailureThe operation failed with an unspecified error.

Required Permissions:

  • None

API Level:

  • 20

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2022 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"

#include <string.h>

ML_EXTERN_C_BEGIN

typedef enum MLGestureClassificationHandType {
MLGestureClassificationHandType_Left = 0,
MLGestureClassificationHandType_Right = 1,
MLGestureClassificationHandType_Count = 2,
MLGestureClassificationHandType_Ensure32Bits = 0x7FFFFFFF
} MLGestureClassificationHandType;


typedef struct MLGestureClassificationStaticData {
uint32_t version;
MLCoordinateFrameUID hand_interaction[MLGestureClassificationHandType_Count];
MLCoordinateFrameUID hand_transform[MLGestureClassificationHandType_Count];
} MLGestureClassificationStaticData;

ML_STATIC_INLINE void MLGestureClassificationStaticDataInit(MLGestureClassificationStaticData* inout_data) {
if (NULL != inout_data) {
memset(inout_data, 0, sizeof(MLGestureClassificationStaticData));
inout_data->version = 1u;
}
}

typedef enum MLGestureClassificationPostureType {
MLGestureClassificationPostureType_None = 0,
MLGestureClassificationPostureType_Pinch = 1,
MLGestureClassificationPostureType_Point = 2,
MLGestureClassificationPostureType_Grasp = 3,
MLGestureClassificationPostureType_Open = 4,
MLGestureClassificationPostureType_Ensure32Bits = 0x7FFFFFFF
} MLGestureClassificationPostureType;

typedef enum MLGestureClassificationKeyPoseType {
MLGestureClassificationKeyPoseType_None = 0,
MLGestureClassificationKeyPoseType_OK = 1,
MLGestureClassificationKeyPoseType_C = 2,
MLGestureClassificationKeyPoseType_Pinch = 3,
MLGestureClassificationKeyPoseType_Finger = 4,
MLGestureClassificationKeyPoseType_L = 5,
MLGestureClassificationKeyPoseType_Thumb = 6,
MLGestureClassificationKeyPoseType_Fist = 7,
MLGestureClassificationKeyPoseType_Open = 8,
MLGestureClassificationKeyPoseType_Ensure32Bits = 0x7FFFFFFF
} MLGestureClassificationKeyPoseType;

typedef struct MLGestureClassificationPostureFingerData {
float pinch_normalized_angle;
float pinch_angle_of_separation_deg;
float pinch_normalized_distance;
float pinch_distance_m;
} MLGestureClassificationPostureFingerData;

typedef struct MLGestureClassificationFingerState {
bool is_extended;
float length_m;
float normalized_extension;
float angle_to_palm;
MLGestureClassificationPostureFingerData posture_data;
} MLGestureClassificationFingerState;

typedef struct MLGestureClassificationState {
MLGestureClassificationPostureType posture_type;
MLGestureClassificationKeyPoseType keypose_type;
MLGestureClassificationFingerState thumb;
MLGestureClassificationFingerState index;
MLGestureClassificationFingerState middle;
MLGestureClassificationFingerState ring;
MLGestureClassificationFingerState pinky;
float angle_thumb_index_deg;
float angle_index_middle_deg;
float angle_middle_ring_deg;
float angle_ring_pinky_deg;
} MLGestureClassificationState;

typedef struct MLGestureClassificationData {
uint32_t version;
MLGestureClassificationState hand_state[MLGestureClassificationHandType_Count];
} MLGestureClassificationData;

ML_STATIC_INLINE void MLGestureClassificationDataInit(MLGestureClassificationData* inout_data) {
if (NULL != inout_data) {
memset(inout_data, 0, sizeof(MLGestureClassificationData));
inout_data->version = 1u;
}
}

ML_API MLResult ML_CALL MLGestureClassificationCreate(MLHandle* out_handle);

ML_API MLResult ML_CALL MLGestureClassificationDestroy(MLHandle handle);

ML_API MLResult ML_CALL MLGestureClassificationGetStaticData(MLHandle handle, MLGestureClassificationStaticData *out_data);

ML_API MLResult ML_CALL MLGestureClassificationGetData(MLHandle handle, MLGestureClassificationData *out_data);

ML_EXTERN_C_END