Skip to content

Markers

Markers act as the bridge between visual detection and world-aware behavior.

Markers can be used for two main purposes:

  • as anchors to attach AR objects relative to them
  • to enable transformations between the local and world coordinate systems, when their position and orientation are known in the world reference frame

Marker usage consists of two stages: detection and attachment.

Using markers

Markers can be detected by calling CameraSession.requestMarkers, which enables the detection process. When a marker is detected, the callback passed to CameraSession.requestMarkers is triggered. To proceed, a MarkerInfo object must be provided using CameraSession.attachMarker, supplying all the necessary information about the marker. If an unknown marker is detected, it is recommended to call CameraSession.discardMarker to stop receiving callbacks for that marker. If the attachment is successful, the callback is invoked again with DetectionState.ATTACHED and a non-null Marker object.

This procedure is designed to allow applications to store marker data in any preferred format. To simplify this process, the Catalog class can be used. Please refer to the dedicated section for further information.

World anchoring

When the position and orientation of one or — preferably — multiple markers are available, the runtime can provide updates in the world reference frame.

Tracking updates are delivered through the CameraSession.trackingUpdates stream. Whenever world anchoring is available, each TrackingUpdate contains:

  • the current TrackingState
  • the current HookState
  • the device position in the world coordinate system
  • the device orientation as a quaternion

The HookState indicates the quality of the world anchoring:

  • NOT_HOOKED_UP: the runtime does not have a valid world anchor.
  • SINGLE_MARKER: the world anchor is based on a single marker and may be less stable.
  • DOUBLE_MARKERS: the world anchor is based on multiple markers, providing a more stable and reliable spatial reference.

The accuracy of the resulting pose still depends on environmental conditions and the runtime state. However, the HookState provides a practical indication of the current quality of the world anchoring.

Augmented Reality

Markers can be used in AuRea by passing them to the AuAnchor constructor. Virtual objects can then be attached to this anchor, allowing them to be rendered relative to the marker’s position.

  • When the position and orientation of a single marker are known, it can be used as a reference to enable world-to-local alignment. However, this typically provides limited accuracy and stability.
  • When the positions of at least two markers are available, significantly improved accuracy and robustness can be achieved.

Marker lifetime

A Marker object should be treated as session-bound runtime state.

In practical terms:

  • it is valid only while the owning session remains valid
  • it may become unusable after disposal or detachment
  • it should not be treated as a persistent data object

Applications should store marker metadata persistently only in their own domain layer, not by keeping runtime marker handles beyond the session lifecycle.