Skip to main content
Version: 14 May 2024

Fiducial Marker Tracking

APIs for the Marker Tracking system. More...

Classes

Name
structMLMarkerTrackerDecodedTypedData
Structure type selector.
structMLMarkerTrackerDecodedArucoData
Aruco decoded data.
structMLMarkerTrackerDecodedBinaryData
Binary decoded data.
structMLMarkerTrackerDecodedData
Represents the decoded data.
structMLMarkerTrackerResult
Represents the result for a single marker.
structMLMarkerTrackerResultArray
An array of all the marker results from the Marker Tracker.
structMLMarkerTrackerCustomProfile
Marker Tracker Custom Profile.
structMLMarkerTrackerSettings
Marker Tracker Settings.

Types

Name
typedef struct MLMarkerTrackerDecodedTypedDataMLMarkerTrackerDecodedTypedData
Structure type selector.
typedef struct MLMarkerTrackerDecodedArucoDataMLMarkerTrackerDecodedArucoData
Aruco decoded data.
typedef struct MLMarkerTrackerDecodedBinaryDataMLMarkerTrackerDecodedBinaryData
Binary decoded data.
typedef MLMarkerTrackerDecodedBinaryDataMLMarkerTrackerDecodedQRData
QR Code data.
typedef MLMarkerTrackerDecodedBinaryDataMLMarkerTrackerDecodedEAN13Data
EAN-13 data.
typedef MLMarkerTrackerDecodedBinaryDataMLMarkerTrackerDecodedUPCAData
UPC-A data.
typedef MLMarkerTrackerDecodedBinaryDataMLMarkerTrackerDecodedCode128Data
Code 128 data.
typedef struct MLMarkerTrackerDecodedDataMLMarkerTrackerDecodedData
Represents the decoded data.
typedef struct MLMarkerTrackerResultMLMarkerTrackerResult
Represents the result for a single marker.
typedef struct MLMarkerTrackerResultArrayMLMarkerTrackerResultArray
An array of all the marker results from the Marker Tracker.
typedef struct MLMarkerTrackerCustomProfileMLMarkerTrackerCustomProfile
Marker Tracker Custom Profile.
typedef struct MLMarkerTrackerSettingsMLMarkerTrackerSettings
Marker Tracker Settings.

Enums

Name
enumMLMarkerTrackerDetectorType
{
MLMarkerTrackerDetectorType_None = 0,
MLMarkerTrackerDetectorType_QR = 1 << 0,
MLMarkerTrackerDetectorType_Aruco = 1 << 1,
MLMarkerTrackerDetectorType_EAN_13 = 1 << 2,
MLMarkerTrackerDetectorType_UPC_A = 1 << 3,
MLMarkerTrackerDetectorType_Code_128 = 1 << 4,
MLMarkerTrackerDetectorType_All = 0x3FFFFFFF,
MLMarkerTrackerDetectorType_Ensure32Bits = 0x7FFFFFFF
}
Represents the different detector types supported by the API.
enumMLMarkerTrackerProfile
{
MLMarkerTrackerProfile_Default = 0,
MLMarkerTrackerProfile_Custom = 1,
MLMarkerTrackerProfile_Speed = 2,
MLMarkerTrackerProfile_Accuracy = 3,
MLMarkerTrackerProfile_SmallTargets = 4,
MLMarkerTrackerProfile_Large_FoV = 6,
MLMarkerTrackerProfile_Ensure32Bits = 0x7FFFFFFF
}
Represents the different tracker profiles.
enumMLMarkerTrackingFpsHint
{
MLMarkerTrackingFpsHint_Low = 0,
MLMarkerTrackingFpsHint_Medium = 1,
MLMarkerTrackingFpsHint_High = 2,
MLMarkerTrackingFpsHint_Max = 3,
MLMarkerTrackingFpsHint_Ensure32Bits = 0x7FFFFFFF
}
Marker tracker FPS hint.
enumMLMarkerTrackingResolutionHint
{
MLMarkerTrackingResolutionHint_Low = 0,
MLMarkerTrackingResolutionHint_Medium = 1,
MLMarkerTrackingResolutionHint_High = 2,
MLMarkerTrackingResolutionHint_Ensure32Bits = 0x7FFFFFFF
}
Marker tracker resolution hint.
enumMLMarkerTrackerCameraHint
{
MLMarkerTrackerCameraHint_RGB_Camera = 0,
MLMarkerTrackerCameraHint_World_Cameras = 1,
MLMarkerTrackerCameraHint_Ensure32Bits = 0x7FFFFFFF
}
Marker tracker camera hint.
enumMLMarkerTrackerCornerRefineMethod
{
MLMarkerTrackerCornerRefineMethod_None = 0,
MLMarkerTrackerCornerRefineMethod_Subpix = 1,
MLMarkerTrackerCornerRefineMethod_Contour = 2,
MLMarkerTrackerCornerRefineMethod_AprilTag = 3,
MLMarkerTrackerCornerRefineMethod_Ensure32Bits = 0x7FFFFFFF
}
Corner Refinement Method.
enumMLMarkerTrackerFullAnalysisIntervalHint
{
MLMarkerTrackerFullAnalysisIntervalHint_Max = 0,
MLMarkerTrackerFullAnalysisIntervalHint_Fast = 1,
MLMarkerTrackerFullAnalysisIntervalHint_Medium = 2,
MLMarkerTrackerFullAnalysisIntervalHint_Slow = 3,
MLMarkerTrackerFullAnalysisIntervalHint_Ensure32Bits = 0x7FFFFFFF
}
Full Frame Analysis Time Interval.
enumMLMarkerTrackerArucoDictionaryName
{
MLMarkerTrackerArucoDictionaryName_NotInitialized = -1,
MLMarkerTrackerArucoDictionaryName_DICT_4X4_50 = 0,
MLMarkerTrackerArucoDictionaryName_DICT_4X4_100,
MLMarkerTrackerArucoDictionaryName_DICT_4X4_250,
MLMarkerTrackerArucoDictionaryName_DICT_4X4_1000,
MLMarkerTrackerArucoDictionaryName_DICT_5X5_50,
MLMarkerTrackerArucoDictionaryName_DICT_5X5_100,
MLMarkerTrackerArucoDictionaryName_DICT_5X5_250,
MLMarkerTrackerArucoDictionaryName_DICT_5X5_1000,
MLMarkerTrackerArucoDictionaryName_DICT_6X6_50,
MLMarkerTrackerArucoDictionaryName_DICT_6X6_100,
MLMarkerTrackerArucoDictionaryName_DICT_6X6_250,
MLMarkerTrackerArucoDictionaryName_DICT_6X6_1000,
MLMarkerTrackerArucoDictionaryName_DICT_7X7_50,
MLMarkerTrackerArucoDictionaryName_DICT_7X7_100,
MLMarkerTrackerArucoDictionaryName_DICT_7X7_250,
MLMarkerTrackerArucoDictionaryName_DICT_7X7_1000,
MLMarkerTrackerArucoDictionaryName_DICT_ARUCO_ORIGINAL,
MLMarkerTrackerArucoDictionaryName_DICT_APRILTAG_16h5,
MLMarkerTrackerArucoDictionaryName_DICT_APRILTAG_25h9,
MLMarkerTrackerArucoDictionaryName_DICT_APRILTAG_36h10,
MLMarkerTrackerArucoDictionaryName_DICT_APRILTAG_36h11,
MLMarkerTrackerArucoDictionaryName_Ensure32Bits = 0x7FFFFFFF
}
Supported pre-defined Aruco dictionary and AprilTags.
enumMLMarkerTrackingDecodedDataType
{
MLMarkerTrackingDecodedDataType_None = 0,
MLMarkerTrackingDecodedDataType_Aruco = 1,
MLMarkerTrackingDecodedDataType_QR = 2,
MLMarkerTrackingDecodedDataType_EAN_13 = 3,
MLMarkerTrackingDecodedDataType_UPC_A = 4,
MLMarkerTrackingDecodedDataType_Code_128 = 5,
MLMarkerTrackingDecodedDataType_Ensure32Bits = 0x7FFFFFFF
}
Decoded Data Type enumeration.

Functions

Name
MLResultMLMarkerTrackerResultArrayInit(MLMarkerTrackerResultArray * inout_result_array)
Initializes default values for MLMarkerTrackerResultArray.
MLResultMLMarkerTrackerSettingsInit(MLMarkerTrackerSettings * inout_settings)
Initializes default values for MLMarkerTrackerSettings.
MLResultMLMarkerTrackerCreate(const MLMarkerTrackerSettings settings, MLHandle out_handle)
Create a Marker Tracker.
MLResultMLMarkerTrackerUpdateSettings(MLHandle tracker_handle, const MLMarkerTrackerSettings * tracker_settings)
Update the Marker Tracker with new settings.
MLResultMLMarkerTrackerDestroy(MLHandle tracker_handle)
Destroy an Marker Tracker.
MLResultMLMarkerTrackerGetResult(MLHandle tracker_handle, MLMarkerTrackerResultArray * out_data)
Get the results for Marker Tracking.
MLResultMLMarkerTrackerReleaseResult(MLMarkerTrackerResultArray * data)
Release the resources for the results array.

Detailed Description

APIs for the Marker Tracking system.

This API can be used to track fiducial markers like QR codes, April tags and Aruco markers. For fiducial markers, this API provides 6DOF poses, and the encoded information.

The scanner supports up to 16 markers. Identical QR codes will be treated as separate targets and reported individually, identical Aruco markers or April tags will lead to a collision and won't be reported separately.

List of supported, trackable markers (with pose info):

  • Aruco markers.

  • AprilTag v2.

  • QR codes (model 1 & 2). List of supported, detectable markers (no pose info):

  • EAN-13 (experimental).

  • UPC-A (experimental).

  • Code 128 (experimental). Starting at API level 28 all ArUco marker, QR code and April tag poses reported from this API are consistently following the convention below.

Marker axes convention: The marker has its own coordinate system (which in the case of a marker coplanar with the image plane and facing the camera means a 180° rotation around the vertical axis).

In RUB coordinates, this means that we will have:

      y ^
__|___
| | |
x <--|--+ |
|_____|

Z-axis pointing backwards away from the camera.

Warning

THIS API IS DEPRECATED IN FAVOR OF OPENXR XR_ML_marker_understanding EXTENSION: https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#XR_ML_marker_understanding

Shared Object:

  • perception.magicleap*

Enums Documentation

MLMarkerTrackerDetectorType

EnumeratorValueDescription
MLMarkerTrackerDetectorType_None0Represents no marker type.
MLMarkerTrackerDetectorType_QR1 << 0QR code.
MLMarkerTrackerDetectorType_Aruco1 << 1Aruco and AprilTag.
MLMarkerTrackerDetectorType_EAN_131 << 2EAN-13 (experimental).
MLMarkerTrackerDetectorType_UPC_A1 << 3UPC-A (experimental).
MLMarkerTrackerDetectorType_Code_1281 << 4Code 128 decoded data (experimental).
MLMarkerTrackerDetectorType_All0x3FFFFFFFAll supported marker types.
MLMarkerTrackerDetectorType_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Represents the different detector types supported by the API.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLMarkerTrackerProfile

EnumeratorValueDescription
MLMarkerTrackerProfile_Default0Generic tracker profile. Tracker profile that covers standard use cases. If this does not suite the needs of the application try the other profiles listed below.
MLMarkerTrackerProfile_Custom1Customer Tracker Profile. Application can define a custom traker profiler. See MLMarkerTrackerCustomProfile for more details.
MLMarkerTrackerProfile_Speed2Optimized for speed. Use this profile to reduce the compute load and increase detection/tracker speed. This can result poor poses.
MLMarkerTrackerProfile_Accuracy3Optimized for accuracy. Use this profile to optimize for accurate marker poses. This can cause increased load on the compute.
MLMarkerTrackerProfile_SmallTargets4Optimized for small targets. Use this profile to optimize for markers that are small or for larger markers that need to detected from far.
MLMarkerTrackerProfile_Large_FoV6Optimized for FoV. Use this profile to be able to detect markers across a larger FoV. Marker Tracker system will attempt to use multiple cameras to detect the markers.
MLMarkerTrackerProfile_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Represents the different tracker profiles.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 21

MLMarkerTrackingFpsHint

EnumeratorValueDescription
MLMarkerTrackingFpsHint_Low0Low FPS.
MLMarkerTrackingFpsHint_Medium1Medium FPS.
MLMarkerTrackingFpsHint_High2High FPS.
MLMarkerTrackingFpsHint_Max3Max possible FPS.
MLMarkerTrackingFpsHint_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Marker tracker FPS hint.

The MLMarkerTrackingFpsHint enum values are used to hint to the back-end the max frames per second that should be analyzed. This is set in the MLMarkerTrackerCustomProfile structure and this setting applies to all enabled trackers.

CPU load is a combination of enabled detector types, FpsHint and ResolutionHint. More detectors and a higher fps and resolution hints will result in a higher CPU load. High CPU load can affect the performance of your system.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLMarkerTrackingResolutionHint

EnumeratorValueDescription
MLMarkerTrackingResolutionHint_Low0Low Resolution.
MLMarkerTrackingResolutionHint_Medium1Medium Resolution.
MLMarkerTrackingResolutionHint_High2High Resolution.
MLMarkerTrackingResolutionHint_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Marker tracker resolution hint.

The MLMarkerTrackingResolutionHint enum values are used to hint to the back-end the resolution that should be used. This is set in the MLMarkerTrackerCustomProfile structure and this setting currently only applies to the QR, UPC and EAN detectors.

CPU load is a combination of enabled detector types, FpsHint and ResolutionHint. More detectors and a higher fps and resolution hints will result in a higher CPU load. High CPU load can affect the performance of your system.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLMarkerTrackerCameraHint

EnumeratorValueDescription
MLMarkerTrackerCameraHint_RGB_Camera0Single RGB camera.
MLMarkerTrackerCameraHint_World_Cameras1One or more world cameras.
MLMarkerTrackerCameraHint_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Marker tracker camera hint.

The MLMarkerTrackerCameraHint enum values are used to hint to the camera that should be used. This is set in the MLMarkerTrackerCustomProfile structure and this setting currently only applies to the aruco detectors.

RGB camera has higher resolution than world cameras and are better suited for use cases where the target to be tracked is small or needs to be detected from far.

World cameras make use of multiple world cameras to improve accuracy and increase the FoV for detection.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 21

MLMarkerTrackerCornerRefineMethod

EnumeratorValueDescription
MLMarkerTrackerCornerRefineMethod_None0No refinement. Inaccurate corners.
MLMarkerTrackerCornerRefineMethod_Subpix1Subpixel refinement. Corners have subpixel coordinates. High detection rate, very fast, reasonable accuracy.
MLMarkerTrackerCornerRefineMethod_Contour2Contour refinement. High detection rate, fast, reasonable accuracy.
MLMarkerTrackerCornerRefineMethod_AprilTag3AprilTag refinement. Reasonable detection rate, slowest, but very accurate.
MLMarkerTrackerCornerRefineMethod_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Corner Refinement Method.

The Aruco/April tag detector comes with several corner refinement methods. Choosing the right corner refinement method has an impact on the accuracy and speed trade-off that comes with each detection pipeline.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

note

Corner refinement only applies to Aruco and April tags, not QR codes.

API Level:

  • 20

MLMarkerTrackerFullAnalysisIntervalHint

EnumeratorValueDescription
MLMarkerTrackerFullAnalysisIntervalHint_Max0Detector analyzes every frame fully.
MLMarkerTrackerFullAnalysisIntervalHint_Fast1Detector analyzes frame fully very often.
MLMarkerTrackerFullAnalysisIntervalHint_Medium2Detector analyzes frame fully a few times per second.
MLMarkerTrackerFullAnalysisIntervalHint_Slow3Detector analyzes frame fully about every second.
MLMarkerTrackerFullAnalysisIntervalHint_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Full Frame Analysis Time Interval.

In order to improve performance, the detectors don't always run on the full frame. Full frame analysis is however necessary to detect new markers that weren't detected before. Use this option to control how often the detector may detect new markers and its impact on tracking performance.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLMarkerTrackerArucoDictionaryName

EnumeratorValueDescription
MLMarkerTrackerArucoDictionaryName_NotInitialized-1Default value. Nothing will be detected.
MLMarkerTrackerArucoDictionaryName_DICT_4X4_5004 by 4 pixel Aruco marker dictionary with 50 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_4X4_1004 by 4 pixel Aruco marker dictionary with 100 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_4X4_2504 by 4 pixel Aruco marker dictionary with 250 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_4X4_10004 by 4 pixel Aruco marker dictionary with 1000 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_5X5_505 by 5 pixel Aruco marker dictionary with 50 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_5X5_1005 by 5 pixel Aruco marker dictionary with 100 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_5X5_2505 by 5 pixel Aruco marker dictionary with 250 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_5X5_10005 by 5 pixel Aruco marker dictionary with 1000 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_6X6_506 by 6 pixel Aruco marker dictionary with 50 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_6X6_1006 by 6 pixel Aruco marker dictionary with 100 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_6X6_2506 by 6 pixel Aruco marker dictionary with 250 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_6X6_10006 by 6 pixel Aruco marker dictionary with 1000 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_7X7_507 by 7 pixel Aruco marker dictionary with 50 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_7X7_1007 by 7 pixel Aruco marker dictionary with 100 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_7X7_2507 by 7 pixel Aruco marker dictionary with 250 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_7X7_10007 by 7 pixel Aruco marker dictionary with 1000 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_ARUCO_ORIGINAL5 by 5 pixel Aruco marker dictionary with 1024 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_APRILTAG_16h54 by 4 bits, minimum hamming distance between any two codes = 5, 30 codes.
MLMarkerTrackerArucoDictionaryName_DICT_APRILTAG_25h95 by 5 bits, minimum hamming distance between any two codes = 9, 35 codes.
MLMarkerTrackerArucoDictionaryName_DICT_APRILTAG_36h106 by 6 bits, minimum hamming distance between any two codes = 10, 2320 codes.
MLMarkerTrackerArucoDictionaryName_DICT_APRILTAG_36h116 by 6 bits, minimum hamming distance between any two codes = 11, 587 codes.
MLMarkerTrackerArucoDictionaryName_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Supported pre-defined Aruco dictionary and AprilTags.

Marker Tracker supports pre-defined Aruco dictionary and AprilTags. Aruco dictionaries can be looked up and markers can be generated for them here: [http://chev.me/arucogen/]

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

note

: Due to the 4X4 and the 'Aruco Original' dictionaries suffering from frequent false detections, we discourage their use.

API Level:

  • 20

MLMarkerTrackingDecodedDataType

EnumeratorValueDescription
MLMarkerTrackingDecodedDataType_None0Represents no decoded data.
MLMarkerTrackingDecodedDataType_Aruco1Aruco and AprilTag decoded data.
MLMarkerTrackingDecodedDataType_QR2QR decoded data.
MLMarkerTrackingDecodedDataType_EAN_133EAN-13 decoded data.
MLMarkerTrackingDecodedDataType_UPC_A4UPC-A decoded data.
MLMarkerTrackingDecodedDataType_Code_1285Code 128 decoded data.
MLMarkerTrackingDecodedDataType_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Decoded Data Type enumeration.

Each decoder may output different types of decoded data structures. The type field of #MLMarkerTrackingDecodedTypedData holds this enum and can be used to cast #MLMarkerTrackingDecodedTypedData to the correct sub type.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

Types Documentation

MLMarkerTrackerDecodedTypedData

typedef struct MLMarkerTrackerDecodedTypedData MLMarkerTrackerDecodedTypedData;

Structure type selector.

Different Marker Decoders will produce different data. Use this structure to find what the data structure is.

switch ( data->type ) {
case MLMarkerTrackingDecodedDataType_Aruco:
MLMarkerTrackerDecodedArucoData * aruco = reinterpret_cast<MLMarkerTrackerDecodedArucoData*>(data);
MLog(Verbose, "Received Aruco Code %u", aruco->id);
break;
default:
MLog(Verbose, "Unhandled type received");
}

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLMarkerTrackerDecodedArucoData

typedef struct MLMarkerTrackerDecodedArucoData MLMarkerTrackerDecodedArucoData;

Aruco decoded data.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLMarkerTrackerDecodedBinaryData

typedef struct MLMarkerTrackerDecodedBinaryData MLMarkerTrackerDecodedBinaryData;

Binary decoded data.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLMarkerTrackerDecodedQRData

typedef MLMarkerTrackerDecodedBinaryData MLMarkerTrackerDecodedQRData;

QR Code data.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLMarkerTrackerDecodedEAN13Data

typedef MLMarkerTrackerDecodedBinaryData MLMarkerTrackerDecodedEAN13Data;

EAN-13 data.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLMarkerTrackerDecodedUPCAData

typedef MLMarkerTrackerDecodedBinaryData MLMarkerTrackerDecodedUPCAData;

UPC-A data.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLMarkerTrackerDecodedCode128Data

typedef MLMarkerTrackerDecodedBinaryData MLMarkerTrackerDecodedCode128Data;

Code 128 data.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 25

MLMarkerTrackerDecodedData

typedef struct MLMarkerTrackerDecodedData MLMarkerTrackerDecodedData;

Represents the decoded data.

The different detectors will have different decoded outputs. See MLMarkerTrackerDecodedTypedData for details on the output formats supported.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLMarkerTrackerResult

typedef struct MLMarkerTrackerResult MLMarkerTrackerResult;

Represents the result for a single marker.

A list of these detections will be returned by the Marker Tracker, after processing a camera frame succesfully.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLMarkerTrackerResultArray

typedef struct MLMarkerTrackerResultArray MLMarkerTrackerResultArray;

An array of all the marker results from the Marker Tracker.

Free this array with MLMarkerTrackerReleaseResult.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLMarkerTrackerCustomProfile

typedef struct MLMarkerTrackerCustomProfile MLMarkerTrackerCustomProfile;

Marker Tracker Custom Profile.

Marker Tracker system provides a set of standard tracking profiles (see MLMarkerTrackerProfile) to configure the tracker settings. If this does not meet the application's needs then the application can choose to define a custom tracker profile using MLMarkerTrackerCustomProfile.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.


MLMarkerTrackerSettings

typedef struct MLMarkerTrackerSettings MLMarkerTrackerSettings;

Marker Tracker Settings.

When creating a Marker Tracker, this list of settings needs to be passed to configure the tracker properly. The tracker will only output detections of markers that belong to the defined dictionary and the estimated poses will only be correct if the marker length has been set correctly.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 21

Functions Documentation

MLMarkerTrackerResultArrayInit

static inline MLResult MLMarkerTrackerResultArrayInit(
MLMarkerTrackerResultArray * inout_result_array
)

Initializes default values for MLMarkerTrackerResultArray.

Parameters

MLMarkerTrackerResultArray *inout_result_arrayThe object to initialize to an empty result array.

Returns

MLResultMLResult_InvalidParamFailed to init result array due to pointer being NULL.
MLResultMLResult_OkSuccessfully initialized the marker tracking result array.
Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLMarkerTrackerSettingsInit

static inline MLResult MLMarkerTrackerSettingsInit(
MLMarkerTrackerSettings * inout_settings
)

Initializes default values for MLMarkerTrackerSettings.

Parameters

MLMarkerTrackerSettings *inout_settingsThe object to initialize with default settings.

Returns

MLResultMLResult_InvalidParamFailed to init settings array due to pointer being NULL.
MLResultMLResult_OkSuccessfully initialized the marker tracking settings array.

This call initializes a setting struct with default values. Default values will not start any tracking as the API user needs to add which detector types should be enabled and in case of Aruco/April tag tracking also the corresponding dictionary.

Default marker size is 10cm, but smaller or larger sizes are supported as long as they are detectable with the camera.

Default corner refinement method is 'Contour'. Edge refinement is deactivated.

Max time between fully analyzed frames is 1s.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 28

MLMarkerTrackerCreate

MLResult MLMarkerTrackerCreate(
const MLMarkerTrackerSettings * settings,
MLHandle * out_handle
)

Create a Marker Tracker.

Parameters

const MLMarkerTrackerSettings *settingsList of settings of type MLMarkerTrackerSettings that configure the tracker.
MLHandle *out_handleA pointer to an MLHandle to the newly created Marker Tracker. If this operation fails, out_handle will be ML_INVALID_HANDLE.

Returns

MLResultMLResult_InvalidParamFailed to create Marker Tracker due to invalid out_handle.
MLResultMLResult_OkSuccessfully created Marker Tracker.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_PermissionDeniedFailed to create tracker due to lack of permission(s).
MLResultMLResult_UnspecifiedFailureFailed to create the Marker Tracker due to an internal error.

Required Permissions:

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

Deprecated since 1.6.0. Scheduled for removal.

note

Only one marker tracker is allowed per app/session. This call will fail when called multiple times. Use MLMarkerTrackerUpdateSettings and update values if you want to change the detector.

API Level:

  • 21

MLMarkerTrackerUpdateSettings

MLResult MLMarkerTrackerUpdateSettings(
MLHandle tracker_handle,
const MLMarkerTrackerSettings * tracker_settings
)

Update the Marker Tracker with new settings.

Parameters

MLHandletracker_handleMLHandle to the Marker Tracker created by MLMarkerTrackerCreate().
const MLMarkerTrackerSettings *tracker_settingsList of new Marker Tracker settings.

Returns

MLResultMLResult_InvalidParamFailed to update the settings due to invalid tracker_settings.
MLResultMLResult_OkSuccessfully updated the Marker Tracker settings.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_UnspecifiedFailureFailed to update the settings due to an internal error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 21

MLMarkerTrackerDestroy

MLResult MLMarkerTrackerDestroy(
MLHandle tracker_handle
)

Destroy an Marker Tracker.

Parameters

MLHandletracker_handleMLHandle to the Marker Tracker created by MLMarkerTrackerCreate().

Returns

MLResultMLResult_OkSuccessfully destroyed the Marker Tracker.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_UnspecifiedFailureFailed to destroy the tracker due to an internal error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLMarkerTrackerGetResult

MLResult MLMarkerTrackerGetResult(
MLHandle tracker_handle,
MLMarkerTrackerResultArray * out_data
)

Get the results for Marker Tracking.

Parameters

MLHandletracker_handleMLHandle to the Marker Tracker created by MLMarkerTrackerCreate().
MLMarkerTrackerResultArray *out_dataPointer to an array of pointers to MLMarkerTrackerResult. The content will be freed by the MLMarkerTrackerReleaseResult.

Returns

MLResultMLResult_InvalidParamFailed to return detection data due to invalid out_data.
MLResultMLResult_OkSuccessfully fetched and returned all detections.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_UnspecifiedFailureFailed to return detections due to an internal error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20

MLMarkerTrackerReleaseResult

MLResult MLMarkerTrackerReleaseResult(
MLMarkerTrackerResultArray * data
)

Release the resources for the results array.

Parameters

MLMarkerTrackerResultArray *dataThe list of detections to be freed.

Returns

MLResultMLResult_InvaldParamFailed to free structure due to invalid data.
MLResultMLResult_OkSuccessfully freed data structure.
MLResultMLResult_PerceptionSystemNotStartedPerception System has not been started.
MLResultMLResult_UnspecifiedFailureFailed to free data due to an internal error.

Required Permissions:

  • None
Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

  • 20