GitHubX

Setup and User Experience

Follow along in the MeshMap XR > Marker Tracking sample.

Scene Objects

Hierarchy window

There are four required assets to use fiducial marker tracking:

  • XR rig — Represents the player.

  • Marker Tracker — Contains all the components for tracking markers, calibrating the results, and interacting with menus.

  • Content group(s) — Parent GameObjects that contain the assets you want to localize. Each content group should correspond to at least one marker.

  • Marker visual(s) — Visual indicators that show accuracy of tracking. One visual per marker.

Organize your scene around these four assets to keep the relationships clear.

Marker Tracker Setup

Marker Tracker with canvas and dependency injection manager

The Marker Tracker object includes a Canvas for users to start and cancel the tracking process, a toggle input to show/hide the menu and marker visuals, and a dependency injection manager which connects its core components.

Refer to Marker Tracker.prefab for the preconfigured fields.

Organize Content into Nearby Groups to Improve Accuracy

Content groups

In the screenshot above, the "Content" section of the scene has four content groups, each with its respective markers and objects as children.

It's best practice to use separate content groups for different areas of your location-based experience. Each content group is localized by a unique fiducial marker (e.g., AprilTag).

As you move further away from the marker, the localization accuracy may decrease. This is because any small errors in the rotational angles of the marker's perceived pose increase with distance.

The formula to calculate accuracy as you move further away is:

error distance=2r⋅sin⁡(error degree of rotational angle2)\text{error distance} = 2r \cdot \sin\left(\frac{\text{error degree of rotational angle}}{2}\right)

Separating your content into local chunks helps maintain accuracy and keep your project organized.

For example, if you are creating an experience for a park you can make one content group for the entrance area, a second for a walking path, and another for the central fountain.

You can use as many content groups as you have unique Marker IDs for, and put as many GameObjects within each as you like. Just keep in mind how often you want the player to have to localize (i.e., track) to another marker to continue the experience.

There is a trade-off between the accuracy gained from having markers span shorter distances and the user friction of having to repeatedly track new markers.

Marker-Visual-Content Relationship

Section of the Marker Tracking Controls component in the Inspector window

Connect the markers, visuals, and content groups in the MarkerTrackingControls component of the Marker Tracker prefab.

In the left column, list the Marker IDs (the number which will be read from the AprilTag, ArUco marker, or QR code) that you are using for your app. They do not have to be sequential, but that makes it easier.

In the right columns, list the corresponding marker visuals and the content groups.

Multiple fiducial markers can be used to localize the same content group.

In the screenshot above, markers 3, 4, and 5 all localize Content3.

This many-to-one relationship let's you have backup marker locations in case one happens to be unavailable. For example, due to public works renovations or a group of people standing in the place.

Marker Tracker UI/UX

Localization panel of the Marker Tracker prefab canvas

The Marker Tracker prefab's Localization panel includes an option to set whether the fiducial marker is flat (e.g., on the ground) or upright (e.g., on a wall).

It also includes options to "freeze" any of the rotational axes. This can be useful if you only need to adjust the pitch (X), yaw (Y), or roll (Z). Often, if a marker is on the ground, freezing X and Z can remove error introduced by an unlevel surface.

Calibration UI/UX

Calibration panel of the Marker Tracker prefab canvas

Since marker tracking-based localization gets less accurate as you move farther away, you can use the Calibration panel to tweak the position of content as you go.

Face in the Z-forward direction of the most recent fiducial marker that you localized (i.e., tracked) to and press the buttons to incrementally tweak the pose of its content group. You must localize to a marker before you can calibrate.

PreviousMarker TrackingNextMagic Leap 2 Support

Last updated