WebXR Anchors Module

Draft Community Group Report,

This version:
https://immersive-web.github.io/anchors/
Issue Tracking:
GitHub
Inline In Spec
Editors:
(Google)
Participate:
File an issue (open issues)
Mailing list archive
W3C’s #immersive-web IRC

Abstract

Describes a method to create anchors tracked by underlying system.

1. Introduction

WebXR Anchors module enables applications to ask the underlying XR system to track changes to a particular three-dimensional pose (position and orientation) as the system’s understanding of the world changes. This allows the application to adjust the location of the virtual objects that it placed in the scene in a way that helps with maintaining the illusion that the placed objects are really present in the user’s environment.

1.1. Terminology

Pose, as understood by this document, signifies a position and orientation in 3D space.

Anchor, as understood by this document, is an entity that keeps track of the pose that is fixed relative to the real world, and is created by the application.

2. Initialization

2.1. Feature descriptor

In order for the applications to signal their interest in using anchors during a session, the session must be requested with appropriate feature descriptor. The string anchors is introduced by this module as a new valid feature descriptor for anchors feature.

A device is capable of supporting the anchors feature if the device’s tracking system exposes a native anchors capability. The inline XR device MUST NOT be treated as capable of supporting the anchors feature. The user agents SHOULD attempt to support anchors feature for sessions with mode equal to "immersive-ar".

Note: Even though anchors feature support is not required, anchors are one of the basic features needed by the AR-enabled applications to provide good user experience. Therefore, it is *highly* recommended that the user agents support them for "immersive-ar" sessions.

3. Anchors

3.1. XRAnchor

[SecureContext, Exposed=Window]
interface XRAnchor {
  readonly attribute XRSpace anchorSpace;

  void delete();
};

An XRAnchor contains anchorSpace that can be used to locate the anchor relative to other XRSpaces. If this attribute is accessed when deleted is set to true, the user agent MUST throw an InvalidStateError.

Each XRAnchor has an associated deleted boolean value that is initially set to false.

Each XRAnchor has an associated native origin.

Each XRAnchor has an associated session.

In order to create new anchor object from native origin and session, the user agent MUST run the following steps:
  1. Let anchor be a new XRAnchor.

  2. Set anchor’s native origin to native origin.

  3. Set anchor’s session to session.

  4. Set anchor’s deleted to false.

  5. Set anchor’s anchorSpace to a new XRSpace object created with session set to anchor’s session and native origin set to native origin.

  6. Return anchor.

4. Anchor creation

The XRSession is extended to contain an associated set of tracked anchors.

The XRSession is extended to contain an associated map of new anchors that is keyed with XRAnchor object and maps to Promise<XRAnchor> object.

partial interface XRFrame {
  Promise<XRAnchor> createAnchor(XRRigidTransform pose, XRSpace space);
};

partial interface XRHitTestResult {
  Promise<XRAnchor> createAnchor(XRRigidTransform pose);
};

The XRHitTestResult is extended to contain an associated native entity. If the underlying system does not provide information about native entity that resulted in computing the result, it will be assumed that native entity is set to null.

The application can create an anchor using one of the 2 ways:

In order to create an anchor from frame, the application can call XRFrame's createAnchor(pose, space) method.

The createAnchor(pose, space) method, when invoked on an XRFrame frame with pose and space, MUST run the following steps:
  1. Let promise be a new Promise.

  2. If frame’s active boolean is false, reject promise with InvalidStateError and abort these steps.

  3. Let session be frame’s session.

  4. Add update anchors algorithm to session’s list of frame updates if it is not already present there.

  5. Let device be session’s XR device.

  6. Let effective origin be space’s effective origin.

  7. Let anchor native origin be a new native origin returned from the device’s call to create a new anchor using pose, interpreted as if expressed relative to effective origin at the frame’s time.

  8. Create new anchor object anchor using anchor native origin and session.

  9. Add anchor to session’s set of tracked anchors.

  10. Add a mapping from anchor to promise to session’s map of new anchors.

Note: It is the responsibility of user agents to ensure that the physical origin tracked by the anchor returned by each createAnchor(pose, space) call aligns as closely as possible with the physical location of pose within space at the time represented by the frame on which the method is called. Specifically, this means that for spaces that are dynamically changing, user agents should attempt to capture the native origin of such spaces at the app’s specified time. This text is non-normative, but expresses the intent of the specification author(s) and contributors and thus it is highly recommended that it is followed by the implementations to ensure consistent behavior across different vendors.

In order to create an anchor from hit test result, the application can call XRHitTestResult's createAnchor(pose) method.

The createAnchor(pose) method, when invoked on an XRHitTestResult hitTestResult with pose, MUST run the following steps:
  1. Let promise be a new Promise.

  2. Let frame be hitTestResult’s frame.

  3. If frame’s active boolean is false, reject promise with InvalidStateError and abort these steps.

  4. Let session be frame’s session.

  5. Add update anchors algorithm to session’s list of frame updates if it is not already present there.

  6. Let device be session’s XR device.

  7. Let nativeEntity be the hitTestResult’s native entity.

  8. Let anchor native origin be a new native origin returned from the device’s call to create a new anchor using pose, interpreted as if expressed relative to hitTestResult’s native origin and attached to nativeEntity, at the frame’s time.

  9. Create new anchor object anchor using anchor native origin and session.

  10. Add anchor to session’s set of tracked anchors.

  11. Add a mapping from anchor to promise to session’s map of new anchors.

Note: The same remark that is present on createAnchor(pose, space) method applies here as well.

Session’s "list of frame updates" might need to have a way of specifying ordering - some algorithms may depend on others.

5. Anchor updates

interface XRAnchorSet {
  readonly setlike<XRAnchor>;
};

partial interface XRFrame {
  [SameObject] readonly attribute XRAnchorSet trackedAnchors;
};

An XRAnchorSet interface is introduced as a way to expose a collection of anchors.

An XRFrame is extended to contain a trackedAnchors attribute which contains all anchors still tracked in the frame. At XRFrame creation, the set is initially empty and will be populated by the update anchors algorithm.

In order to update anchors for frame, the user agent MUST run the following steps:
  1. Let session be a frame’s session.

  2. Let device be a session’s XR device.

  3. For each anchor in session’s set of tracked anchors, run:

    1. Query the device’s tracking system for the anchor’s native origin information.

    2. If the device’s tracking system no longer tracks the anchor, run the following steps:

      1. Remove anchor from the session’s set of tracked anchors.

      2. If session’s map of new anchors contains a mapping from anchor to promise, reject the promise and remove the mapping.

      3. Continue to the next entry in session’s set of tracked anchors.

    3. Add anchor to frame’s trackedAnchors set.

    4. If session’s map of new anchors contains a mapping from anchor to promise, resolve the promise with anchor and remove the mapping.

6. Anchor removal

When an application is no longer interested in receiving updates to an anchor, it can delete an anchor by calling delete().

The delete() method, when invoked on an XRAnchor anchor, MUST delete an anchor by running the following steps:
  1. If anchor’s deleted is true, abort these steps.

  2. Set anchor’s anchorSpace to null.

  3. Set anchor’s deleted to true.

  4. Let session be an anchor’s session.

  5. Let device be a session’s XR device.

  6. Let native origin be an anchor’s native origin.

  7. Inform the device’s tracking system that the native origin is no longer to be tracked.

  8. Remove anchor from session’s set of tracked anchors.

7. Native device concepts

In order for the user agents to be able to implement the anchors API, the underlying XR device should provide native support of this feature. This section describes requirements placed on the underlying XR system, and is by necessity under-specified to allow the implementation of anchors API on top of various frameworks / devices.

7.1. Native anchor

The underlying XR device is capable of supporting the anchors feature if it supports the following capabilities related to anchors:

In case the underlying device does not support native anchors, the user agents MAY decide to implement the anchors API through emulated native anchors. This approach assumes that anchors, once created, never change their pose, and their pose is the pose passed in by the application to the anchor creation methods such as XRFrame's createAnchor(pose, space) or XRHitTestResult's createAnchor(pose).

Note: The emulated native anchors approach is equivalent to the applications emulating the anchors feature themselves and can help reduce the number of different cases that the applications need to handle. It might also allow the applications to re-use the same code for "immersive-ar" and "immersive-vr" sessions.

8. Privacy & Security Considerations

The anchors API does not directly expose access to the information about the user environment. In case the session was created with hit-test support enabled and the device supports tracking moving objects, it may be possible for the application to infer the layout of the user’s environment by observing changes to anchor poses of objects that are, for example, carried around. This offers similar level of information about user’s environment as hit-testing API. Anchor feature has to be declared when creating an XR session, which will allow the user agents to notify the users about potential privacy implications of allowing the anchors API to be used by the website.

I’m not aware of devices that support tracking general objects that move - should they be considered by the spec at all? Are there any examples of such devices?

9. Acknowledgements

The following individuals have contributed to the design of the WebXR Anchors specification:

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WebIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/
[WEBXR]
Brandon Jones; Nell Waliczek. WebXR Device API. 10 October 2019. WD. URL: https://www.w3.org/TR/webxr/
[WEBXR-AR-MODULE-1]
Brandon Jones; Nell Waliczek; Manish Goregaokar. WebXR Augmented Reality Module - Level 1. 10 October 2019. WD. URL: https://www.w3.org/TR/webxr-ar-module-1/

IDL Index

[SecureContext, Exposed=Window]
interface XRAnchor {
  readonly attribute XRSpace anchorSpace;

  void delete();
};

partial interface XRFrame {
  Promise<XRAnchor> createAnchor(XRRigidTransform pose, XRSpace space);
};

partial interface XRHitTestResult {
  Promise<XRAnchor> createAnchor(XRRigidTransform pose);
};

interface XRAnchorSet {
  readonly setlike<XRAnchor>;
};

partial interface XRFrame {
  [SameObject] readonly attribute XRAnchorSet trackedAnchors;
};

Issues Index

Session’s "list of frame updates" might need to have a way of specifying ordering - some algorithms may depend on others.
I’m not aware of devices that support tracking general objects that move - should they be considered by the spec at all? Are there any examples of such devices?