Skip to main content
Version: 21 Aug 2024

MLMarkerTracker

NameSpace: MagicLeap

This API can be used to scan markers. For QR codes it also provides 6DOF poses. The scanner supports up to 16 markers. Identical markers will be treated as seperate markers and reported individually. List of currently supported trackable markers (with pose info): More...

Inherits from:
MLAutoAPISingleton< MLMarkerTracker >,
MLLazySingleton< T >

Detailed Description

public class MLMarkerTracker : MLAutoAPISingleton< MLMarkerTracker > 

Details*

* QR codes of Model 1 and Model 2 * ArUco markers List of currently supported detectable markers (without pose info): * EAN-13 (experimental) * UPC-A (experimental)


Public Methods

async Task< MLResult > SetSettingsAsync

Instance.settings setter. If called with the same value while a settings update operation is in progress, nothing will happen.

public static async Task< MLResult > SetSettingsAsync(
TrackerSettings value
)

Parameters

TypeNameDescription
TrackerSettingsvalue

async Task< MLResult > StartScanningAsync

Asynchronous utility method to enable marker scanning using the current ScannerSettings . Does nothing if scanning is already enabled. Note that enabling scanning has a performance cost until scanning is disabled using StopScanning or by setting ScannerSettings.enabled to false .

public static async Task< MLResult > StartScanningAsync(
TrackerSettings? settings =null
)

Parameters

TypeNameDescription
TrackerSettings?settings

async Task< MLResult > StopScanningAsync

Asynchronous method to disable marker scanning if previously activated. Otherwise, this does nothing.

public static async Task< MLResult > StopScanningAsync()

Protected Methods

OnApplicationPause

Callback sent to all MagicLeap APIs on application pause.

protected virtual override void OnApplicationPause(
bool pauseStatus
)

Parameters

TypeNameDescription
boolpauseStatusTrue if the application is paused, else False.

Reimplements: OnApplicationPause


StartAPI

Do API-specific creation/initialization of ML resources for this API, such as creating trackers, etc. Called automatically the first time Instance is accessed. Error checking on the return value is performed in the base class.

protected virtual override MLResult.Code StartAPI()

Reimplements: StartAPI


StopAPI

API-specific cleanup. Will be called whenever MLDevice is destroyed (at the latest, when the application is shutting down). Error checking on the return value is performed in the base class.

protected virtual override MLResult.Code StopAPI()

Reimplements: StopAPI


Update

Runs once per Unity Update loop.

protected virtual override void Update()

Reimplements: Update


Public Attributes

IsScanning

Are markers currently being scanned?


public static bool IsScanning => Instance.settings.EnableMarkerScanning;


Public Events

OnMLMarkerTrackerResultsFound

When any results are found from marker scanning, this event will be raised.

public static Action< MarkerData > OnMLMarkerTrackerResultsFound()

OnMLMarkerTrackerResultsFoundArray

When any results are found from marker scanning, this event will be raised with an array of all markers found.

public static Action< MarkerData[]> OnMLMarkerTrackerResultsFoundArray()

Public Enums

ArucoDictionaryName

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/ Note: Due to 4X4 dictionaries suffering from frequent false detections, we discourage their use.

EnumeratorValueDescription
NotInitialized-1Default value. Nothing will be detected.
DICT_4X4_5004 by 4 pixel ArUco marker dictionary with 50 IDs.
DICT_4X4_1004 by 4 pixel ArUco marker dictionary with 100 IDs.
DICT_4X4_2504 by 4 pixel ArUco marker dictionary with 250 IDs.
DICT_4X4_10004 by 4 pixel ArUco marker dictionary with 1000 IDs.
DICT_5X5_505 by 5 pixel ArUco marker dictionary with 50 IDs.
DICT_5X5_1005 by 5 pixel ArUco marker dictionary with 100 IDs.
DICT_5X5_2505 by 5 pixel ArUco marker dictionary with 250 IDs.
DICT_5X5_10005 by 5 pixel ArUco marker dictionary with 1000 IDs.
DICT_6X6_506 by 6 pixel ArUco marker dictionary with 50 IDs.
DICT_6X6_1006 by 6 pixel ArUco marker dictionary with 100 IDs.
DICT_6X6_2506 by 6 pixel ArUco marker dictionary with 250 IDs.
DICT_6X6_10006 by 6 pixel ArUco marker dictionary with 1000 IDs.
DICT_7X7_507 by 7 pixel ArUco marker dictionary with 50 IDs.
DICT_7X7_1007 by 7 pixel ArUco marker dictionary with 100 IDs.
DICT_7X7_2507 by 7 pixel ArUco marker dictionary with 250 IDs.
DICT_7X7_10007 by 7 pixel ArUco marker dictionary with 1000 IDs.
DICT_ARUCO_ORIGINAL5 by 5 pixel ArUco marker dictionary with 1024 IDs
DICT_APRILTAG_16h54x4 bits, minimum hamming distance between any two codes = 5, 30 codes
DICT_APRILTAG_25h95x5 bits, minimum hamming distance between any two codes = 9, 35 codes
DICT_APRILTAG_36h106x6 bits, minimum hamming distance between any two codes = 10, 2320 codes
DICT_APRILTAG_36h116x6 bits, minimum hamming distance between any two codes = 11, 587 codes

CameraHint

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

EnumeratorValueDescription
RGBSingle RGB Camera.
WorldOne or more world cameras.

Details*

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. from far.


CornerRefineMethod

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. Corner refinement only applies to Aruco and April tags, not QR codes.

EnumeratorValueDescription
NoneNo refinement, may have inaccurate corners.
SubpixCorners have subpixel coordinates. High detection rate, very fast, reasonable accuracy.
ContourHigh detection rate, fast, reasonable accuracy.
AprilTagReasonable detection rate, slowest, but very accurate.

FPSHint

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.

EnumeratorValueDescription
Low
Medium
High
Max

Details*

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


FullAnalysisIntervalHint

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.

EnumeratorValueDescription
MaxDetector analyzes every frame fully.
FastDetector analyzes frame fully very often.
MediumDetector analyzes frame fully a few times per second.
SlowDetector analyzes frame fully about every second.

MarkerType

Represents the different marker types supported by the API

EnumeratorValueDescription
None0Represents no marker
QR1QR code of Model 1 or 2
Aruco_April2Aruco marker and AprilTag
EAN_134EAN-13 (experimental)
UPC_A8UPC-A (experimental)
All0x3FFFFFFFAll supported markers

Profile

Represents the different tracker profiles used to optimize marker tracking in difference use cases.

EnumeratorValueDescription
DefaultGeneric tracker profile. Tracker profile that covers standard use cases. If this does not fit the needs of the application try the other profiles listed below.
CustomApplication can define a custom tracker profiler.
SpeedUse this profile to reduce the compute load and increase detection/tracker speed. This can result poor poses.
AccuracyUse this profile to optimize for accurate marker poses. This can cause increased load on the compute.
SmallTargetsUse this profile to optimize for markers that are small or for larger markers that need to detected from far.
Large_FOV6Use this profile to be able to detect markers across a larger Field Of View. Marker Tracker system will attempt to use multiple cameras to detect the markers.

ResolutionHint

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

EnumeratorValueDescription
Low
Medium
High

Details*

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.