Skip to main content
Version: 20 Mar 2024

Hand Tracking

APIs for the Hand Tracking system. More...

Classes

Name
structMLHandTrackingCFUIDs
MLCoordinateFrameUIDs for the keypoints.
structMLHandTrackingStaticData
Static information about a hand tracker.
structMLHandTrackingHandState
State of a single hand.
structMLHandTrackingData
Data which is received when querying hand tracker from MLHandTrackingGetData().
structMLHandTrackingSettings
Settings of the hand tracking system.

Types

Name
typedef struct MLHandTrackingCFUIDsMLHandTrackingCFUIDs
MLCoordinateFrameUIDs for the keypoints.
typedef struct MLHandTrackingStaticDataMLHandTrackingStaticData
Static information about a hand tracker.
typedef struct MLHandTrackingHandStateMLHandTrackingHandState
State of a single hand.
typedef struct MLHandTrackingDataMLHandTrackingData
Data which is received when querying hand tracker from MLHandTrackingGetData().
typedef struct MLHandTrackingSettingsMLHandTrackingSettings
Settings of the hand tracking system.

Enums

Name
enumMLHandTrackingHandType
{
MLHandTrackingHandType_Left = 0,
MLHandTrackingHandType_Right = 1,
MLHandTrackingHandType_Count = 2,
MLHandTrackingHandType_Ensure32Bits = 0x7FFFFFFF
}
enumAnonymous Enum 12
{
MLHandTrackingStaticData_MaxKeyPoints = 28
}
enumMLHandTrackingKeyPoint
{
MLHandTrackingKeyPoint_Thumb_Tip = 0,
MLHandTrackingKeyPoint_Thumb_IP,
MLHandTrackingKeyPoint_Thumb_MCP,
MLHandTrackingKeyPoint_Thumb_CMC,
MLHandTrackingKeyPoint_Index_Tip,
MLHandTrackingKeyPoint_Index_DIP,
MLHandTrackingKeyPoint_Index_PIP,
MLHandTrackingKeyPoint_Index_MCP,
MLHandTrackingKeyPoint_Middle_Tip,
MLHandTrackingKeyPoint_Middle_DIP,
MLHandTrackingKeyPoint_Middle_PIP,
MLHandTrackingKeyPoint_Middle_MCP,
MLHandTrackingKeyPoint_Ring_Tip,
MLHandTrackingKeyPoint_Ring_DIP,
MLHandTrackingKeyPoint_Ring_PIP,
MLHandTrackingKeyPoint_Ring_MCP,
MLHandTrackingKeyPoint_Pinky_Tip,
MLHandTrackingKeyPoint_Pinky_DIP,
MLHandTrackingKeyPoint_Pinky_PIP,
MLHandTrackingKeyPoint_Pinky_MCP,
MLHandTrackingKeyPoint_Wrist_Center,
MLHandTrackingKeyPoint_Wrist_Ulnar,
MLHandTrackingKeyPoint_Wrist_Radial,
MLHandTrackingKeyPoint_Hand_Center,
MLHandTrackingKeyPoint_Index_Meta,
MLHandTrackingKeyPoint_Middle_Meta,
MLHandTrackingKeyPoint_Ring_Meta,
MLHandTrackingKeyPoint_Pinky_Meta,
MLHandTrackingKeyPoint_Count = MLHandTrackingStaticData_MaxKeyPoints,
MLHandTrackingKeyPoint_Ensure32Bits = 0x7FFFFFFF
}
Keypoint index ordering.
enumMLHandTrackingSettingsFlags
{
MLHandTrackingSettingsFlags_None = 0,
MLHandTrackingSettingsFlags_UnfilteredKeypoints = 1 << 0,
MLHandTrackingSettingsFlags_Ensure32Bits = 0x7FFFFFFF
}
Enumeration of flags to select settings related to hand tracking.

Functions

Name
voidMLHandTrackingStaticDataInit(MLHandTrackingStaticData * inout_attr)
Initializes default values for MLHandTrackingStaticData.
voidMLHandTrackingDataInit(MLHandTrackingData * inout_attr)
Initializes values for MLHandTrackingData.
voidMLHandTrackingSettingsInit(MLHandTrackingSettings * inout_settings)
Initializes default values for MLHandTrackingSettings.
MLResultMLHandTrackingCreate(MLHandle * out_handle)
Creates a hand tracker.
MLResultMLHandTrackingCreateEx(const MLHandTrackingSettings settings, MLHandle out_handle)
Creates a hand tracker.
MLResultMLHandTrackingUpdateSettings(MLHandle hand_tracker, const MLHandTrackingSettings * settings)
Updates settings.
MLResultMLHandTrackingDestroy(MLHandle hand_tracker)
Destroys a hand tracker.
MLResultMLHandTrackingGetData(MLHandle hand_tracker, MLHandTrackingData * out_data)
Queries the state of the hand tracker.
MLResultMLHandTrackingGetStaticData(MLHandle hand_tracker, MLHandTrackingStaticData * out_data)
Gets static information about hand tracking system.

Detailed Description

APIs for the Hand Tracking system.

Shared Object:

  • perception.magicleap*

Enums Documentation

MLHandTrackingHandType

EnumeratorValueDescription
MLHandTrackingHandType_Left0Left hand.
MLHandTrackingHandType_Right1Right hand.
MLHandTrackingHandType_Count2Number of hands.
MLHandTrackingHandType_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Available hand types.


Anonymous Enum 12

EnumeratorValueDescription
MLHandTrackingStaticData_MaxKeyPoints28Maximum number of key points per hand.

MLHandTrackingKeyPoint

EnumeratorValueDescription
MLHandTrackingKeyPoint_Thumb_Tip0
MLHandTrackingKeyPoint_Thumb_IP
MLHandTrackingKeyPoint_Thumb_MCP
MLHandTrackingKeyPoint_Thumb_CMC
MLHandTrackingKeyPoint_Index_Tip
MLHandTrackingKeyPoint_Index_DIP
MLHandTrackingKeyPoint_Index_PIP
MLHandTrackingKeyPoint_Index_MCP
MLHandTrackingKeyPoint_Middle_Tip
MLHandTrackingKeyPoint_Middle_DIP
MLHandTrackingKeyPoint_Middle_PIP
MLHandTrackingKeyPoint_Middle_MCP
MLHandTrackingKeyPoint_Ring_Tip
MLHandTrackingKeyPoint_Ring_DIP
MLHandTrackingKeyPoint_Ring_PIP
MLHandTrackingKeyPoint_Ring_MCP
MLHandTrackingKeyPoint_Pinky_Tip
MLHandTrackingKeyPoint_Pinky_DIP
MLHandTrackingKeyPoint_Pinky_PIP
MLHandTrackingKeyPoint_Pinky_MCP
MLHandTrackingKeyPoint_Wrist_Center
MLHandTrackingKeyPoint_Wrist_Ulnar
MLHandTrackingKeyPoint_Wrist_Radial
MLHandTrackingKeyPoint_Hand_Center
MLHandTrackingKeyPoint_Index_Meta
MLHandTrackingKeyPoint_Middle_Meta
MLHandTrackingKeyPoint_Ring_Meta
MLHandTrackingKeyPoint_Pinky_Meta
MLHandTrackingKeyPoint_CountMLHandTrackingStaticData_MaxKeyPointsMaximum number of key points per gesture.
MLHandTrackingKeyPoint_Ensure32Bits0x7FFFFFFF

Keypoint index ordering.

The index ordering of 28 keypoints exposed in array keypoints_mask[MLHandTrackingStaticData_MaxKeyPoints] and left_frame/right_frame[MLHandTrackingStaticData_MaxKeyPoints].

API Level:

  • 7

MLHandTrackingSettingsFlags

EnumeratorValueDescription
MLHandTrackingSettingsFlags_None0No additional settings used.
MLHandTrackingSettingsFlags_UnfilteredKeypoints1 << 0Enable unfiltered keypoints. See MLHandTrackingGetStaticData for more details.
MLHandTrackingSettingsFlags_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Enumeration of flags to select settings related to hand tracking.

Filtered keypoints are always available, no matter the settings.

API Level:

  • 28

Types Documentation

MLHandTrackingCFUIDs

typedef struct MLHandTrackingCFUIDs MLHandTrackingCFUIDs;

MLCoordinateFrameUIDs for the keypoints.

See MLHandTrackingKeyPoint for more details.

More Info

API Level:

  • 20

MLHandTrackingStaticData

typedef struct MLHandTrackingStaticData MLHandTrackingStaticData;

Static information about a hand tracker.

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

More Info

API Level:

  • 28

MLHandTrackingHandState

typedef struct MLHandTrackingHandState MLHandTrackingHandState;

State of a single hand.

Same for both filtered and unfiltered keypoints.

More Info

API Level:

  • 20

MLHandTrackingData

typedef struct MLHandTrackingData MLHandTrackingData;

Data which is received when querying hand tracker from MLHandTrackingGetData().

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

More Info

API Level:

  • 20

MLHandTrackingSettings

typedef struct MLHandTrackingSettings MLHandTrackingSettings;

Settings of the hand tracking system.

This structure must be initialized by calling MLHandTrackingSettingsInit().

More Info

API Level:

  • 28

Functions Documentation

MLHandTrackingStaticDataInit

static inline void MLHandTrackingStaticDataInit(
MLHandTrackingStaticData * inout_attr
)

Initializes default values for MLHandTrackingStaticData.

Parameters

MLHandTrackingStaticData *inout_attrThe object to initialize with default values.

API Level:

  • 28

MLHandTrackingDataInit

static inline void MLHandTrackingDataInit(
MLHandTrackingData * inout_attr
)

Initializes values for MLHandTrackingData.

Parameters

MLHandTrackingData *inout_attrThe object to initialize.

API Level:

  • 20

MLHandTrackingSettingsInit

static inline void MLHandTrackingSettingsInit(
MLHandTrackingSettings * inout_settings
)

Initializes default values for MLHandTrackingSettings.

Parameters

MLHandTrackingSettings *inout_settingsThe object to initialize with default settings.

API Level:

  • 28

MLHandTrackingCreate

MLResult MLHandTrackingCreate(
MLHandle * out_handle
)

Creates a hand tracker.

Parameters

MLHandle *out_handleA pointer to an MLHandle which will contain the handle of the hand tracker. If this operation fails, out_handle will be ML_INVALID_HANDLE.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkThe tracker was created successfully.
MLResultMLResult_PermissionDeniedThe application lacks the required permission.
MLResultMLResult_UnspecifiedFailureFailed to create the tracker.

Required Permissions:

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

Deprecated since 1.3.0. Scheduled for removal. Replaced by MLHandTrackingCreateEx.

API Level:

  • 20

MLHandTrackingCreateEx

MLResult MLHandTrackingCreateEx(
const MLHandTrackingSettings * settings,
MLHandle * out_handle
)

Creates a hand tracker.

Parameters

const MLHandTrackingSettings *settingsA pointer to a previously initialized MLHandTrackingSettings struct.
MLHandle *out_handleA pointer to an MLHandle which will contain the handle of the hand tracker. If this operation fails, out_handle will be ML_INVALID_HANDLE.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkThe tracker was created successfully.
MLResultMLResult_PermissionDeniedThe application lacks the required permission.
MLResultMLResult_UnspecifiedFailureFailed to create the tracker.

Required Permissions:

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

API Level:

  • 28

MLHandTrackingUpdateSettings

MLResult MLHandTrackingUpdateSettings(
MLHandle hand_tracker,
const MLHandTrackingSettings * settings
)

Updates settings.

Parameters

MLHandlehand_trackerA handle to a Hand Tracker created by MLHandTrackingCreateEx().
const MLHandTrackingSettings *settingsA pointer to a previously initialized MLHandTrackingSettings struct.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkThe settings were updated successfully.
MLResultMLResult_UnspecifiedFailureFailed to update the settings.

Required Permissions:

  • None

API Level:

  • 28

MLHandTrackingDestroy

MLResult MLHandTrackingDestroy(
MLHandle hand_tracker
)

Destroys a hand tracker.

Parameters

MLHandlehand_trackerA handle to a Hand Tracker created by MLHandTrackingCreateEx().

Returns

MLResultMLResult_OkIt successfully destroyed the tracker.
MLResultMLResult_UnspecifiedFailureFailed to destroy the tracker.

Required Permissions:

  • None

API Level:

  • 20

MLHandTrackingGetData

MLResult MLHandTrackingGetData(
MLHandle hand_tracker,
MLHandTrackingData * out_data
)

Queries the state of the hand tracker.

Parameters

MLHandlehand_trackerA handle to a Hand Tracker created by MLHandTrackingCreateEx().
MLHandTrackingData *out_dataPointer to a variable that receives information about the tracked hands.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkThe hand information was available and the information in out_data is valid.
MLResultMLResult_UnspecifiedFailureFailed to get the hand information.

Required Permissions:

  • None

The MLHandTrackingData is the same for both filtered and unfiltered keypoints.

API Level:

  • 20

MLHandTrackingGetStaticData

MLResult MLHandTrackingGetStaticData(
MLHandle hand_tracker,
MLHandTrackingStaticData * out_data
)

Gets static information about hand tracking system.

Parameters

MLHandlehand_trackerA handle to a Hand Tracker created by MLHandTrackingCreateEx().
MLHandTrackingStaticData *out_dataPointer to a variable that receives static data about the hand tracker.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkThe hand information was available and the information in out_data is valid.
MLResultMLResult_UnspecifiedFailureFailed to get the hand information.

Required Permissions:

  • None

See MLHandTrackingStaticData for more details.

API Level:

  • 20