Version: 10 Jul 2024

ml_gesture_classification.h

Classes

	Name
struct	MLGestureClassificationStaticData Static information about the gesture classification.
struct	MLGestureClassificationPostureFingerData Gesture classification posture related finger data.
struct	MLGestureClassificationFingerState Gesture classification state of a single finger.
struct	MLGestureClassificationState Gesture classification state of a single hand.
struct	MLGestureClassificationData Data which is received when querying tracker from MLGestureClassificationGetData().

Types

	Name
typedef struct MLGestureClassificationStaticData	MLGestureClassificationStaticData Static information about the gesture classification.
typedef struct MLGestureClassificationPostureFingerData	MLGestureClassificationPostureFingerData Gesture classification posture related finger data.
typedef struct MLGestureClassificationFingerState	MLGestureClassificationFingerState Gesture classification state of a single finger.
typedef struct MLGestureClassificationState	MLGestureClassificationState Gesture classification state of a single hand.
typedef struct MLGestureClassificationData	MLGestureClassificationData Data which is received when querying tracker from MLGestureClassificationGetData().

Enums

	Name
enum	MLGestureClassificationHandType { MLGestureClassificationHandType_Left = 0, MLGestureClassificationHandType_Right = 1, MLGestureClassificationHandType_Count = 2, MLGestureClassificationHandType_Ensure32Bits = 0x7FFFFFFF }
enum	MLGestureClassificationPostureType { MLGestureClassificationPostureType_None = 0, MLGestureClassificationPostureType_Pinch = 1, MLGestureClassificationPostureType_Point = 2, MLGestureClassificationPostureType_Grasp = 3, MLGestureClassificationPostureType_Open = 4, MLGestureClassificationPostureType_Ensure32Bits = 0x7FFFFFFF } System gesture classification posture type.
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 } System gesture classification key pose type.

Functions

	Name
void	MLGestureClassificationStaticDataInit(MLGestureClassificationStaticData * inout_data) Initializes default values for MLGestureClassificationStaticData.
void	MLGestureClassificationDataInit(MLGestureClassificationData * inout_data) Initializes default values for MLGestureClassificationData.
MLResult	MLGestureClassificationCreate(MLHandle * out_handle) Creates a gesture classification tracker.
MLResult	MLGestureClassificationDestroy(MLHandle handle) Destroys a gesture classification tracker.
MLResult	MLGestureClassificationGetStaticData(MLHandle handle, MLGestureClassificationStaticData * out_data) Gets static information about the gesture classification.
MLResult	MLGestureClassificationGetData(MLHandle handle, MLGestureClassificationData * out_data) Queries the state of the gesture classification.

Enums Documentation

MLGestureClassificationHandType

Enumerator	Value	Description
MLGestureClassificationHandType_Left	0	Left hand.
MLGestureClassificationHandType_Right	1	Right hand.
MLGestureClassificationHandType_Count	2	Number of hands.
MLGestureClassificationHandType_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Available hand types.

MLGestureClassificationPostureType

Enumerator	Value	Description
MLGestureClassificationPostureType_None	0	None.
MLGestureClassificationPostureType_Pinch	1	Pinch posture.
MLGestureClassificationPostureType_Point	2	Point posture.
MLGestureClassificationPostureType_Grasp	3	Grasp posture.
MLGestureClassificationPostureType_Open	4	Open hand.
MLGestureClassificationPostureType_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

System gesture classification posture type.

API Level:

MLGestureClassificationKeyPoseType

Enumerator	Value	Description
MLGestureClassificationKeyPoseType_None	0	None.
MLGestureClassificationKeyPoseType_OK	1	OK pose.
MLGestureClassificationKeyPoseType_C	2	C pose.
MLGestureClassificationKeyPoseType_Pinch	3	Pinch pose.
MLGestureClassificationKeyPoseType_Finger	4	Finger pose.
MLGestureClassificationKeyPoseType_L	5	L pose.
MLGestureClassificationKeyPoseType_Thumb	6	Thumb up pose.
MLGestureClassificationKeyPoseType_Fist	7	Fist pose.
MLGestureClassificationKeyPoseType_Open	8	Open pose.
MLGestureClassificationKeyPoseType_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

System gesture classification key pose type.

API Level:

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:

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:

MLGestureClassificationFingerState

typedef struct MLGestureClassificationFingerState MLGestureClassificationFingerState;

Gesture classification state of a single finger.

More Info

API Level:

MLGestureClassificationState

typedef struct MLGestureClassificationState MLGestureClassificationState;

Gesture classification state of a single hand.

More Info

API Level:

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:

Functions Documentation

MLGestureClassificationStaticDataInit

static inline void MLGestureClassificationStaticDataInit(
    MLGestureClassificationStaticData * inout_data
)

Initializes default values for MLGestureClassificationStaticData.

Parameters


MLGestureClassificationStaticData *	inout_data	The object to initialize with default settings.

API Level:

MLGestureClassificationDataInit

static inline void MLGestureClassificationDataInit(
    MLGestureClassificationData * inout_data
)

Initializes default values for MLGestureClassificationData.

Parameters


MLGestureClassificationData *	inout_data	The object to initialize with default settings.

API Level:

MLGestureClassificationCreate

MLResult MLGestureClassificationCreate(
    MLHandle * out_handle
)

Creates a gesture classification tracker.

Parameters


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

Returns


MLResult	MLResult_InvalidParam	Failed to create a tracker due to an invalid parameter.
MLResult	MLResult_Ok	The tracker was created successfully.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_PrivilegeDenied	The application lacks privilege.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

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

API Level:

MLGestureClassificationDestroy

MLResult MLGestureClassificationDestroy(
    MLHandle handle
)

Destroys a gesture classification tracker.

Parameters


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

Returns


MLResult	MLResult_InvalidParam	Failed to destroy a tracker due to an invalid parameter.
MLResult	MLResult_Ok	It successfully destroyed the tracker.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

API Level:

MLGestureClassificationGetStaticData

MLResult MLGestureClassificationGetStaticData(
    MLHandle handle,
    MLGestureClassificationStaticData * out_data
)

Gets static information about the gesture classification.

Parameters


MLHandle	handle	A handle to a gesture classification tracker created by MLGestureClassificationCreate().
MLGestureClassificationStaticData *	out_data	Target to populate the data about the gesture classification.

Returns


MLResult	MLResult_InvalidParam	Failed to get static data due to an invalid parameter.
MLResult	MLResult_Ok	Gesture classification static data was successfully received.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

API Level:

MLGestureClassificationGetData

MLResult MLGestureClassificationGetData(
    MLHandle handle,
    MLGestureClassificationData * out_data
)

Queries the state of the gesture classification.

Parameters


MLHandle	handle	A handle to a gesture classification tracker created by MLGestureClassificationCreate().
MLGestureClassificationData *	out_data	Pointer to MLGestureClassificationData structure.

Returns


MLResult	MLResult_InvalidParam	Failed to retrieve data due to an invalid parameter.
MLResult	MLResult_Ok	The state information was available and the information in out_data is valid.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

API Level:

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

ml_gesture_classification.h

Classes​

Types​

Enums​

Functions​

Enums Documentation​

MLGestureClassificationHandType​

MLGestureClassificationPostureType​

MLGestureClassificationKeyPoseType​

Types Documentation​

MLGestureClassificationStaticData​

MLGestureClassificationPostureFingerData​

MLGestureClassificationFingerState​

MLGestureClassificationState​

MLGestureClassificationData​

Functions Documentation​

MLGestureClassificationStaticDataInit​

MLGestureClassificationDataInit​

MLGestureClassificationCreate​

MLGestureClassificationDestroy​

MLGestureClassificationGetStaticData​

MLGestureClassificationGetData​

Source code​

Classes

Types

Enums

Functions

Enums Documentation

MLGestureClassificationHandType

MLGestureClassificationPostureType

MLGestureClassificationKeyPoseType

Types Documentation

MLGestureClassificationStaticData

MLGestureClassificationPostureFingerData

MLGestureClassificationFingerState

MLGestureClassificationState

MLGestureClassificationData

Functions Documentation

MLGestureClassificationStaticDataInit

MLGestureClassificationDataInit

MLGestureClassificationCreate

MLGestureClassificationDestroy

MLGestureClassificationGetStaticData

MLGestureClassificationGetData

Source code