Clarify Anchor vs AnchorOffset in the API

[speigg]

Some apis that reference an "Anchor" are actually expecting or returning an XRAnchorOffset or a string, and other apis either expect or return an XRAnchor, which seems confusing.

For example, here are my immediate expectations of various apis just based on the names of the methods, in comparison to the actual implementation:

XRPresentationSession.anchors
Expectation: a sequence of XRAnchor instances
Implementation: Works as expected

XRPresentationSession.addAnchor
Parameter Expectation: Accepts an instance of XRAnchor.
Implementation: Accepts a coordinate system, position, and orientation, and returns a string (a uuid for an Anchor). (No XRAnchor instance is passed or returned at all!). Also, the name addAnchor implies that we are adding an existing instance of an XRAnchor (rather than creating a new instance), so I think it would be better named createAnchor.

XRPresentationSession.removeAnchor
Expectation: Accept an instance of XRAnchor.
Implementation: Accepts an anchor uid (string). Rename to removeAnchorByUid ?

XRPresentationSession.getAnchor
Expectation: Should return a an instance of XRAnchor
Implementation: Somewhat works as expected, but can be made clearer if the method was named getAnchorByUid

XRPresentationSession.findAnchor
Expectation: Should return a promise that resolves to an instance of XRAnchor
Implementation: Returns a promise that resolves to an instance of XRAnchorOffset, which is NOT an XRAnchor (does not inherit from XRAnchor). If this is going to return an XRAnchorOffset, the name should probably be changed to findAnchorOffset or something similar.

XRPresentationSession.findFloorAnchor
Expectation: Should return a promise that resolves to an instance of XRAnchor
Implementation: Returns a promise that resolves to an instance of XRAnchorOffset, which is NOT an XRAnchor (does not inherit from XRAnchor). Like the previous one, should probably be changed to findFloorAnchorOffset

[blairmacintyre]

Some comments. Probably need to update the docs. But, really, need to see where the w3c WebXR spec is going with these sorts of things.

I think (in general) things might be more tightly coupled to the underlying ARKit / WebXR Viewer implementation that we'd like. For example, the XRAnchorOffset exists because we want to return something that has a "real" anchor (i.e., an ARKit or other system level Anchor) but is an intersection with the plane or object associated with that anchor.

Also, some of the promises are awkward: a future / real implementation would probably not need (or want) to use them as much because they could be synchronous.

[speigg]

I looked at the w3c WebXR spec, and currently it is still basically WebVR (no Anchors or anything AR specific), so if anything it seems like our implementation here will/should inform the new WebXR spec as it develops.

Regarding AnchorOffset, I’m not sure I understand what problem it solves. This kind of thing doesn’t seem to exist in ARKit.

Promises for the Anchors do seem strange to me, as I would expect that they can be created at any time, and provide an “undefined” pose until they have a known pose.

[speigg]

I spoke with Blair about this yesterday, and I understand now what AnchorOffset is for here. It seems, however, that an AnchorOffset should always be associated with a hitTest, and otherwise doesn't need to exist in the API.