Version: 12 Dec 2024

ml_marker_tracking.h

Classes

	Name
struct	MLMarkerTrackerDecodedTypedData Structure type selector.
struct	MLMarkerTrackerDecodedArucoData Aruco decoded data.
struct	MLMarkerTrackerDecodedBinaryData Binary decoded data.
struct	MLMarkerTrackerDecodedData Represents the decoded data.
struct	MLMarkerTrackerResult Represents the result for a single marker.
struct	MLMarkerTrackerResultArray An array of all the marker results from the Marker Tracker.
struct	MLMarkerTrackerCustomProfile Marker Tracker Custom Profile.
struct	MLMarkerTrackerSettings Marker Tracker Settings.

Types

	Name
typedef struct MLMarkerTrackerDecodedTypedData	MLMarkerTrackerDecodedTypedData Structure type selector.
typedef struct MLMarkerTrackerDecodedArucoData	MLMarkerTrackerDecodedArucoData Aruco decoded data.
typedef struct MLMarkerTrackerDecodedBinaryData	MLMarkerTrackerDecodedBinaryData Binary decoded data.
typedef MLMarkerTrackerDecodedBinaryData	MLMarkerTrackerDecodedQRData QR Code data.
typedef MLMarkerTrackerDecodedBinaryData	MLMarkerTrackerDecodedEAN13Data EAN-13 data.
typedef MLMarkerTrackerDecodedBinaryData	MLMarkerTrackerDecodedUPCAData UPC-A data.
typedef MLMarkerTrackerDecodedBinaryData	MLMarkerTrackerDecodedCode128Data Code 128 data.
typedef struct MLMarkerTrackerDecodedData	MLMarkerTrackerDecodedData Represents the decoded data.
typedef struct MLMarkerTrackerResult	MLMarkerTrackerResult Represents the result for a single marker.
typedef struct MLMarkerTrackerResultArray	MLMarkerTrackerResultArray An array of all the marker results from the Marker Tracker.
typedef struct MLMarkerTrackerCustomProfile	MLMarkerTrackerCustomProfile Marker Tracker Custom Profile.
typedef struct MLMarkerTrackerSettings	MLMarkerTrackerSettings Marker Tracker Settings.

Enums

	Name
enum	MLMarkerTrackerDetectorType { 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.
enum	MLMarkerTrackerProfile { 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.
enum	MLMarkerTrackingFpsHint { MLMarkerTrackingFpsHint_Low = 0, MLMarkerTrackingFpsHint_Medium = 1, MLMarkerTrackingFpsHint_High = 2, MLMarkerTrackingFpsHint_Max = 3, MLMarkerTrackingFpsHint_Ensure32Bits = 0x7FFFFFFF } Marker tracker FPS hint.
enum	MLMarkerTrackingResolutionHint { MLMarkerTrackingResolutionHint_Low = 0, MLMarkerTrackingResolutionHint_Medium = 1, MLMarkerTrackingResolutionHint_High = 2, MLMarkerTrackingResolutionHint_Ensure32Bits = 0x7FFFFFFF } Marker tracker resolution hint.
enum	MLMarkerTrackerCameraHint { MLMarkerTrackerCameraHint_RGB_Camera = 0, MLMarkerTrackerCameraHint_World_Cameras = 1, MLMarkerTrackerCameraHint_Ensure32Bits = 0x7FFFFFFF } Marker tracker camera hint.
enum	MLMarkerTrackerCornerRefineMethod { MLMarkerTrackerCornerRefineMethod_None = 0, MLMarkerTrackerCornerRefineMethod_Subpix = 1, MLMarkerTrackerCornerRefineMethod_Contour = 2, MLMarkerTrackerCornerRefineMethod_AprilTag = 3, MLMarkerTrackerCornerRefineMethod_Ensure32Bits = 0x7FFFFFFF } Corner Refinement Method.
enum	MLMarkerTrackerFullAnalysisIntervalHint { MLMarkerTrackerFullAnalysisIntervalHint_Max = 0, MLMarkerTrackerFullAnalysisIntervalHint_Fast = 1, MLMarkerTrackerFullAnalysisIntervalHint_Medium = 2, MLMarkerTrackerFullAnalysisIntervalHint_Slow = 3, MLMarkerTrackerFullAnalysisIntervalHint_Ensure32Bits = 0x7FFFFFFF } Full Frame Analysis Time Interval.
enum	MLMarkerTrackerArucoDictionaryName { 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.
enum	MLMarkerTrackingDecodedDataType { 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
MLResult	MLMarkerTrackerResultArrayInit(MLMarkerTrackerResultArray * inout_result_array) Initializes default values for MLMarkerTrackerResultArray.
MLResult	MLMarkerTrackerSettingsInit(MLMarkerTrackerSettings * inout_settings) Initializes default values for MLMarkerTrackerSettings.
MLResult	MLMarkerTrackerCreate(const MLMarkerTrackerSettings settings, MLHandle out_handle) Create a Marker Tracker.
MLResult	MLMarkerTrackerUpdateSettings(MLHandle tracker_handle, const MLMarkerTrackerSettings * tracker_settings) Update the Marker Tracker with new settings.
MLResult	MLMarkerTrackerDestroy(MLHandle tracker_handle) Destroy an Marker Tracker.
MLResult	MLMarkerTrackerGetResult(MLHandle tracker_handle, MLMarkerTrackerResultArray * out_data) Get the results for Marker Tracking.
MLResult	MLMarkerTrackerReleaseResult(MLMarkerTrackerResultArray * data) Release the resources for the results array.

Enums Documentation

MLMarkerTrackerDetectorType

Enumerator	Value	Description
MLMarkerTrackerDetectorType_None	0	Represents no marker type.
MLMarkerTrackerDetectorType_QR	1 << 0	QR code.
MLMarkerTrackerDetectorType_Aruco	1 << 1	Aruco and AprilTag.
MLMarkerTrackerDetectorType_EAN_13	1 << 2	EAN-13 (experimental).
MLMarkerTrackerDetectorType_UPC_A	1 << 3	UPC-A (experimental).
MLMarkerTrackerDetectorType_Code_128	1 << 4	Code 128 decoded data (experimental).
MLMarkerTrackerDetectorType_All	0x3FFFFFFF	All supported marker types.
MLMarkerTrackerDetectorType_Ensure32Bits	0x7FFFFFFF	Ensure 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:

MLMarkerTrackerProfile

Enumerator	Value	Description
MLMarkerTrackerProfile_Default	0	Generic 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_Custom	1	Customer Tracker Profile. Application can define a custom traker profiler. See MLMarkerTrackerCustomProfile for more details.
MLMarkerTrackerProfile_Speed	2	Optimized for speed. Use this profile to reduce the compute load and increase detection/tracker speed. This can result poor poses.
MLMarkerTrackerProfile_Accuracy	3	Optimized for accuracy. Use this profile to optimize for accurate marker poses. This can cause increased load on the compute.
MLMarkerTrackerProfile_SmallTargets	4	Optimized 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_FoV	6	Optimized 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_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Represents the different tracker profiles.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLMarkerTrackingFpsHint

Enumerator	Value	Description
MLMarkerTrackingFpsHint_Low	0	Low FPS.
MLMarkerTrackingFpsHint_Medium	1	Medium FPS.
MLMarkerTrackingFpsHint_High	2	High FPS.
MLMarkerTrackingFpsHint_Max	3	Max possible FPS.
MLMarkerTrackingFpsHint_Ensure32Bits	0x7FFFFFFF	Ensure 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:

MLMarkerTrackingResolutionHint

Enumerator	Value	Description
MLMarkerTrackingResolutionHint_Low	0	Low Resolution.
MLMarkerTrackingResolutionHint_Medium	1	Medium Resolution.
MLMarkerTrackingResolutionHint_High	2	High Resolution.
MLMarkerTrackingResolutionHint_Ensure32Bits	0x7FFFFFFF	Ensure 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.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLMarkerTrackerCameraHint

Enumerator	Value	Description
MLMarkerTrackerCameraHint_RGB_Camera	0	Single RGB camera.
MLMarkerTrackerCameraHint_World_Cameras	1	One or more world cameras.
MLMarkerTrackerCameraHint_Ensure32Bits	0x7FFFFFFF	Ensure 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:

MLMarkerTrackerCornerRefineMethod

Enumerator	Value	Description
MLMarkerTrackerCornerRefineMethod_None	0	No refinement. Inaccurate corners.
MLMarkerTrackerCornerRefineMethod_Subpix	1	Subpixel refinement. Corners have subpixel coordinates. High detection rate, very fast, reasonable accuracy.
MLMarkerTrackerCornerRefineMethod_Contour	2	Contour refinement. High detection rate, fast, reasonable accuracy.
MLMarkerTrackerCornerRefineMethod_AprilTag	3	AprilTag refinement. Reasonable detection rate, slowest, but very accurate.
MLMarkerTrackerCornerRefineMethod_Ensure32Bits	0x7FFFFFFF	Ensure 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:

MLMarkerTrackerFullAnalysisIntervalHint

Enumerator	Value	Description
MLMarkerTrackerFullAnalysisIntervalHint_Max	0	Detector analyzes every frame fully.
MLMarkerTrackerFullAnalysisIntervalHint_Fast	1	Detector analyzes frame fully very often.
MLMarkerTrackerFullAnalysisIntervalHint_Medium	2	Detector analyzes frame fully a few times per second.
MLMarkerTrackerFullAnalysisIntervalHint_Slow	3	Detector analyzes frame fully about every second.
MLMarkerTrackerFullAnalysisIntervalHint_Ensure32Bits	0x7FFFFFFF	Ensure 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:

MLMarkerTrackerArucoDictionaryName

Enumerator	Value	Description
MLMarkerTrackerArucoDictionaryName_NotInitialized	-1	Default value. Nothing will be detected.
MLMarkerTrackerArucoDictionaryName_DICT_4X4_50	0	4 by 4 pixel Aruco marker dictionary with 50 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_4X4_100		4 by 4 pixel Aruco marker dictionary with 100 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_4X4_250		4 by 4 pixel Aruco marker dictionary with 250 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_4X4_1000		4 by 4 pixel Aruco marker dictionary with 1000 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_5X5_50		5 by 5 pixel Aruco marker dictionary with 50 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_5X5_100		5 by 5 pixel Aruco marker dictionary with 100 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_5X5_250		5 by 5 pixel Aruco marker dictionary with 250 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_5X5_1000		5 by 5 pixel Aruco marker dictionary with 1000 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_6X6_50		6 by 6 pixel Aruco marker dictionary with 50 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_6X6_100		6 by 6 pixel Aruco marker dictionary with 100 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_6X6_250		6 by 6 pixel Aruco marker dictionary with 250 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_6X6_1000		6 by 6 pixel Aruco marker dictionary with 1000 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_7X7_50		7 by 7 pixel Aruco marker dictionary with 50 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_7X7_100		7 by 7 pixel Aruco marker dictionary with 100 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_7X7_250		7 by 7 pixel Aruco marker dictionary with 250 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_7X7_1000		7 by 7 pixel Aruco marker dictionary with 1000 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_ARUCO_ORIGINAL		5 by 5 pixel Aruco marker dictionary with 1024 IDs.
MLMarkerTrackerArucoDictionaryName_DICT_APRILTAG_16h5		4 by 4 bits, minimum hamming distance between any two codes = 5, 30 codes.
MLMarkerTrackerArucoDictionaryName_DICT_APRILTAG_25h9		5 by 5 bits, minimum hamming distance between any two codes = 9, 35 codes.
MLMarkerTrackerArucoDictionaryName_DICT_APRILTAG_36h10		6 by 6 bits, minimum hamming distance between any two codes = 10, 2320 codes.
MLMarkerTrackerArucoDictionaryName_DICT_APRILTAG_36h11		6 by 6 bits, minimum hamming distance between any two codes = 11, 587 codes.
MLMarkerTrackerArucoDictionaryName_Ensure32Bits	0x7FFFFFFF	Ensure 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:

MLMarkerTrackingDecodedDataType

Enumerator	Value	Description
MLMarkerTrackingDecodedDataType_None	0	Represents no decoded data.
MLMarkerTrackingDecodedDataType_Aruco	1	Aruco and AprilTag decoded data.
MLMarkerTrackingDecodedDataType_QR	2	QR decoded data.
MLMarkerTrackingDecodedDataType_EAN_13	3	EAN-13 decoded data.
MLMarkerTrackingDecodedDataType_UPC_A	4	UPC-A decoded data.
MLMarkerTrackingDecodedDataType_Code_128	5	Code 128 decoded data.
MLMarkerTrackingDecodedDataType_Ensure32Bits	0x7FFFFFFF	Ensure 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:

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:

MLMarkerTrackerDecodedArucoData

typedef struct MLMarkerTrackerDecodedArucoData MLMarkerTrackerDecodedArucoData;

Aruco decoded data.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLMarkerTrackerDecodedBinaryData

typedef struct MLMarkerTrackerDecodedBinaryData MLMarkerTrackerDecodedBinaryData;

Binary decoded data.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLMarkerTrackerDecodedQRData

typedef MLMarkerTrackerDecodedBinaryData MLMarkerTrackerDecodedQRData;

QR Code data.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLMarkerTrackerDecodedEAN13Data

typedef MLMarkerTrackerDecodedBinaryData MLMarkerTrackerDecodedEAN13Data;

EAN-13 data.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLMarkerTrackerDecodedUPCAData

typedef MLMarkerTrackerDecodedBinaryData MLMarkerTrackerDecodedUPCAData;

UPC-A data.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLMarkerTrackerDecodedCode128Data

typedef MLMarkerTrackerDecodedBinaryData MLMarkerTrackerDecodedCode128Data;

Code 128 data.

More Info

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

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:

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:

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:

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:

Functions Documentation

MLMarkerTrackerResultArrayInit

static inline MLResult MLMarkerTrackerResultArrayInit(
    MLMarkerTrackerResultArray * inout_result_array
)

Initializes default values for MLMarkerTrackerResultArray.

Parameters


MLMarkerTrackerResultArray *	inout_result_array	The object to initialize to an empty result array.

Returns


MLResult	MLResult_InvalidParam	Failed to init result array due to pointer being NULL.
MLResult	MLResult_Ok	Successfully initialized the marker tracking result array.

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLMarkerTrackerSettingsInit

static inline MLResult MLMarkerTrackerSettingsInit(
    MLMarkerTrackerSettings * inout_settings
)

Initializes default values for MLMarkerTrackerSettings.

Parameters


MLMarkerTrackerSettings *	inout_settings	The object to initialize with default settings.

Returns


MLResult	MLResult_InvalidParam	Failed to init settings array due to pointer being NULL.
MLResult	MLResult_Ok	Successfully 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:

MLMarkerTrackerCreate

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

Create a Marker Tracker.

Parameters


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

Returns


MLResult	MLResult_InvalidParam	Failed to create Marker Tracker due to invalid out_handle.
MLResult	MLResult_Ok	Successfully created Marker Tracker.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_PermissionDenied	Failed to create tracker due to lack of permission(s).
MLResult	MLResult_UnspecifiedFailure	Failed 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:

MLMarkerTrackerUpdateSettings

MLResult MLMarkerTrackerUpdateSettings(
    MLHandle tracker_handle,
    const MLMarkerTrackerSettings * tracker_settings
)

Update the Marker Tracker with new settings.

Parameters


MLHandle	tracker_handle	MLHandle to the Marker Tracker created by MLMarkerTrackerCreate().
const MLMarkerTrackerSettings *	tracker_settings	List of new Marker Tracker settings.

Returns


MLResult	MLResult_InvalidParam	Failed to update the settings due to invalid tracker_settings.
MLResult	MLResult_Ok	Successfully updated the Marker Tracker settings.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_UnspecifiedFailure	Failed to update the settings due to an internal error.

Required Permissions:

None

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLMarkerTrackerDestroy

MLResult MLMarkerTrackerDestroy(
    MLHandle tracker_handle
)

Destroy an Marker Tracker.

Parameters


MLHandle	tracker_handle	MLHandle to the Marker Tracker created by MLMarkerTrackerCreate().

Returns


MLResult	MLResult_Ok	Successfully destroyed the Marker Tracker.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_UnspecifiedFailure	Failed to destroy the tracker due to an internal error.

Required Permissions:

None

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLMarkerTrackerGetResult

MLResult MLMarkerTrackerGetResult(
    MLHandle tracker_handle,
    MLMarkerTrackerResultArray * out_data
)

Get the results for Marker Tracking.

Parameters


MLHandle	tracker_handle	MLHandle to the Marker Tracker created by MLMarkerTrackerCreate().
MLMarkerTrackerResultArray *	out_data	Pointer to an array of pointers to MLMarkerTrackerResult. The content will be freed by the MLMarkerTrackerReleaseResult.

Returns


MLResult	MLResult_InvalidParam	Failed to return detection data due to invalid out_data.
MLResult	MLResult_Ok	Successfully fetched and returned all detections.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_UnspecifiedFailure	Failed to return detections due to an internal error.

Required Permissions:

None

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

MLMarkerTrackerReleaseResult

MLResult MLMarkerTrackerReleaseResult(
    MLMarkerTrackerResultArray * data
)

Release the resources for the results array.

Parameters


MLMarkerTrackerResultArray *	data	The list of detections to be freed.

Returns


MLResult	MLResult_InvaldParam	Failed to free structure due to invalid data.
MLResult	MLResult_Ok	Successfully freed data structure.
MLResult	MLResult_PerceptionSystemNotStarted	Perception System has not been started.
MLResult	MLResult_UnspecifiedFailure	Failed to free data due to an internal error.

Required Permissions:

None

Deprecated

Deprecated since 1.6.0. Scheduled for removal.

API Level:

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2021 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 "ml_coordinate_frame_uid.h"

#include <string.h>

ML_EXTERN_C_BEGIN

typedef enum MLMarkerTrackerDetectorType {
  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
} MLMarkerTrackerDetectorType;

typedef enum MLMarkerTrackerProfile {
  MLMarkerTrackerProfile_Default = 0,
  MLMarkerTrackerProfile_Custom = 1,
  MLMarkerTrackerProfile_Speed = 2,
  MLMarkerTrackerProfile_Accuracy = 3,
  MLMarkerTrackerProfile_SmallTargets = 4,
  MLMarkerTrackerProfile_Large_FoV = 6,
  MLMarkerTrackerProfile_Ensure32Bits = 0x7FFFFFFF
} MLMarkerTrackerProfile;

typedef enum MLMarkerTrackingFpsHint {
  MLMarkerTrackingFpsHint_Low = 0,
  MLMarkerTrackingFpsHint_Medium = 1,
  MLMarkerTrackingFpsHint_High = 2,
  MLMarkerTrackingFpsHint_Max = 3,
  MLMarkerTrackingFpsHint_Ensure32Bits = 0x7FFFFFFF
} MLMarkerTrackingFpsHint;

typedef enum MLMarkerTrackingResolutionHint {
  MLMarkerTrackingResolutionHint_Low = 0,
  MLMarkerTrackingResolutionHint_Medium = 1,
  MLMarkerTrackingResolutionHint_High = 2,
  MLMarkerTrackingResolutionHint_Ensure32Bits = 0x7FFFFFFF
} MLMarkerTrackingResolutionHint;

typedef enum MLMarkerTrackerCameraHint {
  MLMarkerTrackerCameraHint_RGB_Camera = 0,
  MLMarkerTrackerCameraHint_World_Cameras = 1,
  MLMarkerTrackerCameraHint_Ensure32Bits = 0x7FFFFFFF
} MLMarkerTrackerCameraHint;


typedef enum MLMarkerTrackerCornerRefineMethod {
  MLMarkerTrackerCornerRefineMethod_None = 0,
  MLMarkerTrackerCornerRefineMethod_Subpix = 1,
  MLMarkerTrackerCornerRefineMethod_Contour = 2,
  MLMarkerTrackerCornerRefineMethod_AprilTag = 3,
  MLMarkerTrackerCornerRefineMethod_Ensure32Bits = 0x7FFFFFFF
} MLMarkerTrackerCornerRefineMethod;

typedef enum MLMarkerTrackerFullAnalysisIntervalHint {
  MLMarkerTrackerFullAnalysisIntervalHint_Max = 0,
  MLMarkerTrackerFullAnalysisIntervalHint_Fast = 1,
  MLMarkerTrackerFullAnalysisIntervalHint_Medium = 2,
  MLMarkerTrackerFullAnalysisIntervalHint_Slow = 3,
  MLMarkerTrackerFullAnalysisIntervalHint_Ensure32Bits = 0x7FFFFFFF
} MLMarkerTrackerFullAnalysisIntervalHint;

typedef enum MLMarkerTrackerArucoDictionaryName {
  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
} MLMarkerTrackerArucoDictionaryName;

typedef enum MLMarkerTrackingDecodedDataType {
  MLMarkerTrackingDecodedDataType_None = 0,
  MLMarkerTrackingDecodedDataType_Aruco = 1,
  MLMarkerTrackingDecodedDataType_QR = 2,
  MLMarkerTrackingDecodedDataType_EAN_13 = 3,
  MLMarkerTrackingDecodedDataType_UPC_A = 4,
  MLMarkerTrackingDecodedDataType_Code_128 = 5,
  MLMarkerTrackingDecodedDataType_Ensure32Bits = 0x7FFFFFFF
} MLMarkerTrackingDecodedDataType;

typedef ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.") struct MLMarkerTrackerDecodedTypedData {
  MLMarkerTrackingDecodedDataType type;
} MLMarkerTrackerDecodedTypedData;

typedef ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.") struct MLMarkerTrackerDecodedArucoData {
  MLMarkerTrackingDecodedDataType type;
  MLMarkerTrackerArucoDictionaryName dictionary;
  uint32_t id;
} MLMarkerTrackerDecodedArucoData;


typedef ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.") struct MLMarkerTrackerDecodedBinaryData {
  MLMarkerTrackingDecodedDataType type;
  uint32_t data_size;
  const char data[];
} MLMarkerTrackerDecodedBinaryData;

typedef ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.") MLMarkerTrackerDecodedBinaryData MLMarkerTrackerDecodedQRData;

typedef ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.") MLMarkerTrackerDecodedBinaryData MLMarkerTrackerDecodedEAN13Data;

typedef ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.") MLMarkerTrackerDecodedBinaryData MLMarkerTrackerDecodedUPCAData;

typedef ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.") MLMarkerTrackerDecodedBinaryData MLMarkerTrackerDecodedCode128Data;

typedef ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.") struct MLMarkerTrackerDecodedData {
  const MLMarkerTrackerDecodedTypedData *data;

  uint32_t size;
} MLMarkerTrackerDecodedData;

typedef ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.") struct MLMarkerTrackerResult {
  MLMarkerTrackerDecodedData decoded_data;

  MLMarkerTrackerDetectorType detector_type;

  bool valid_pose;

  MLCoordinateFrameUID coord_frame_marker;

  float reprojection_err;

} MLMarkerTrackerResult;

typedef ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.") struct MLMarkerTrackerResultArray {
  uint32_t version;

  MLMarkerTrackerResult** detections;

  size_t count;
} MLMarkerTrackerResultArray;


ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.")
ML_STATIC_INLINE MLResult MLMarkerTrackerResultArrayInit(MLMarkerTrackerResultArray *inout_result_array) {
  if (inout_result_array == NULL) {
    return MLResult_InvalidParam;
  }
  inout_result_array->version = 1u;
  inout_result_array->detections = NULL;
  inout_result_array->count = 0;
  return MLResult_Ok;
}

typedef ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.") struct MLMarkerTrackerCustomProfile {
  MLMarkerTrackingFpsHint fps_hint;

  MLMarkerTrackingResolutionHint resolution_hint;

  MLMarkerTrackerCameraHint camera_hint;

  MLMarkerTrackerCornerRefineMethod corner_refine_method;

  bool use_edge_refinement;

  MLMarkerTrackerFullAnalysisIntervalHint full_analysis_interval_hint;

} MLMarkerTrackerCustomProfile;



typedef ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.") struct MLMarkerTrackerSettings {
  uint32_t version;

  bool enable_marker_tracking;

  uint32_t enabled_detector_types;

  MLMarkerTrackerArucoDictionaryName dictionary;

  float aruco_marker_length;

  float qr_code_length;

  MLMarkerTrackerProfile tracker_profile;

  MLMarkerTrackerCustomProfile custom_tracker_profile;
} MLMarkerTrackerSettings;

ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.")
ML_STATIC_INLINE MLResult MLMarkerTrackerSettingsInit(MLMarkerTrackerSettings *inout_settings) {
  if (inout_settings == NULL) {
    return MLResult_InvalidParam;
  }
  memset(inout_settings, 0, sizeof(MLMarkerTrackerSettings));
  inout_settings->version = 6u;
  inout_settings->dictionary = MLMarkerTrackerArucoDictionaryName_NotInitialized;
  inout_settings->aruco_marker_length = 0.1f;
  inout_settings->qr_code_length = 0.1f;
  inout_settings->enable_marker_tracking = true;
  inout_settings->tracker_profile = MLMarkerTrackerProfile_Default;
  return MLResult_Ok;
}

ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.")
ML_API MLResult ML_CALL MLMarkerTrackerCreate(const MLMarkerTrackerSettings *settings, MLHandle *out_handle);

ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.")
ML_API MLResult ML_CALL MLMarkerTrackerUpdateSettings(MLHandle tracker_handle,
                                                     const MLMarkerTrackerSettings *tracker_settings);

ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.")
ML_API MLResult ML_CALL MLMarkerTrackerDestroy(MLHandle tracker_handle);

ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.")
ML_API MLResult ML_CALL MLMarkerTrackerGetResult(MLHandle tracker_handle,
                                                MLMarkerTrackerResultArray *out_data);

ML_DEPRECATED_MSG("Use XR_ML_marker_understanding OpenXR extention.")
ML_API MLResult ML_CALL MLMarkerTrackerReleaseResult(MLMarkerTrackerResultArray *data);

ML_EXTERN_C_END

ml_marker_tracking.h

Classes​

Types​

Enums​

Functions​

Enums Documentation​

MLMarkerTrackerDetectorType​

MLMarkerTrackerProfile​

MLMarkerTrackingFpsHint​

MLMarkerTrackingResolutionHint​

MLMarkerTrackerCameraHint​

MLMarkerTrackerCornerRefineMethod​

MLMarkerTrackerFullAnalysisIntervalHint​

MLMarkerTrackerArucoDictionaryName​

MLMarkerTrackingDecodedDataType​

Types Documentation​

MLMarkerTrackerDecodedTypedData​

MLMarkerTrackerDecodedArucoData​

MLMarkerTrackerDecodedBinaryData​

MLMarkerTrackerDecodedQRData​

MLMarkerTrackerDecodedEAN13Data​

MLMarkerTrackerDecodedUPCAData​

MLMarkerTrackerDecodedCode128Data​

MLMarkerTrackerDecodedData​

MLMarkerTrackerResult​

MLMarkerTrackerResultArray​

MLMarkerTrackerCustomProfile​

MLMarkerTrackerSettings​

Functions Documentation​

MLMarkerTrackerResultArrayInit​

MLMarkerTrackerSettingsInit​

MLMarkerTrackerCreate​

MLMarkerTrackerUpdateSettings​

MLMarkerTrackerDestroy​

MLMarkerTrackerGetResult​

MLMarkerTrackerReleaseResult​

Source code​

Classes

Types

Enums

Functions

Enums Documentation

MLMarkerTrackerDetectorType

MLMarkerTrackerProfile

MLMarkerTrackingFpsHint

MLMarkerTrackingResolutionHint

MLMarkerTrackerCameraHint

MLMarkerTrackerCornerRefineMethod

MLMarkerTrackerFullAnalysisIntervalHint

MLMarkerTrackerArucoDictionaryName

MLMarkerTrackingDecodedDataType

Types Documentation

MLMarkerTrackerDecodedTypedData

MLMarkerTrackerDecodedArucoData

MLMarkerTrackerDecodedBinaryData

MLMarkerTrackerDecodedQRData

MLMarkerTrackerDecodedEAN13Data

MLMarkerTrackerDecodedUPCAData

MLMarkerTrackerDecodedCode128Data

MLMarkerTrackerDecodedData

MLMarkerTrackerResult

MLMarkerTrackerResultArray

MLMarkerTrackerCustomProfile

MLMarkerTrackerSettings

Functions Documentation

MLMarkerTrackerResultArrayInit

MLMarkerTrackerSettingsInit

MLMarkerTrackerCreate

MLMarkerTrackerUpdateSettings

MLMarkerTrackerDestroy

MLMarkerTrackerGetResult

MLMarkerTrackerReleaseResult

Source code