Draft spec by m-alkalbani · Pull Request #19 · immersive-web/marker-tracking

m-alkalbani · 2026-09-04T14:22:52Z

First attempt at the marker-tracking spec (draft)

First draft of marker-tracking spec

m-alkalbani · 2026-09-04T14:23:49Z

@himorin can we set up the action to build the HTML for gh pages please?

m-alkalbani · 2026-09-04T14:35:57Z

I am aware folks are away for a while currently, so adding @toji for info

himorin · 2026-09-04T15:12:28Z

before setting up GHAction (basically you can include copy of .github/workflows/auto-publish.yml from some other repository - without echidna specific config), you need to fix group and status.
it's totally up to CG co-chairs (no W3C staff assigned to any CG as contact), but there is immersivewebwg in bikeshed boilerplate, but no immersivewebcg. Once CG co-chairs defines/decides way to go (e.g. having CG/UD template in immersivewebwg, or new immersivewebcg), I of course could help on modification.

also you may want to have .pr-preview.json.

See PR #20

m-alkalbani · 2026-09-11T16:25:45Z

/agenda heads up on spec draft and issues in #3

toji

A bunch of comments from my first pass through the doc, though a fair amount of it can be chalked up to normalizing bikeshed use with the other immersive web specs. Really encouraging first draft! Thanks!

toji · 2026-09-14T21:16:46Z

+</pre>
+
+The `XRMarkerTrackingState` values correspond to the [=marker tracking state=] values defined in the [[#marker-tracking-discovery-model|Discovery Model]].
+The `"untracked"` value is used by the algorithms in this module, but marker-tracking results only include markers whose tracking state is `"tracked"` or `"emulated"`.


This is interesting. I feel like I've seen at least one other instance in a web spec of an enum value that was only used by internal algorithms, but I don't recall where. (Might be in WebXR, in which case I'm embarrassed in advance that I don't recall my own writing.)

In any case, it feels like it could cause some developers confusion because the presence of the state in the enum may make them think they have to check for it.

Perhaps the better question is: What do we expect developers to do with the differences between "tracked" and "emulated" markers? If we don't have a compelling use case for exposing the value then it may be best to leave this state entirely internal. Also, could the existing emulatedPosition boolean of an XRPose be used instead?

Great points thanks! I may be wrong here, but I looked a little more into emulatedPosition and to my understanding it describes whether an XRPose between two XRSpace objects relies on an emulated position, not whether a particular marker is (or is not) currently being tracked/observed. So an emulatedPosition can become true for reasons unrelated to marker visibility (?).

I looked into AndroidXR's way of doing this and it seems to treat marker observation/tracking independent of pose emulation, so it still feels to me that this approach would be useful to describe whether the physical marker is currently being observed or not, rather than whether a particular XRSpace pose relies on emulation.

I made a few changes here based on my (potentially wrong) understanding: removed "untracked" from XRMarkerTrackingState as it doesn't need to be exposed, expanded "tracked" and "emulated" descriptions/justification and developer guidance around them and added a small note to distinguish between emulatedPosition and the current approach.

All this being said, this is definitely worth discussing again! (#10).

Changes: 8cac5d7

toji · 2026-09-14T21:28:55Z

+    readonly attribute XRMarkerTrackingState trackingState;
+    readonly attribute DOMString? payloadString;
+    readonly attribute XRMarkerExtent? extent;
+};


Looking through the rest of the text it's not clear how developers are intended to correlate markers from frame to frame. We have some values, such as Anchors, where the spec takes care to specify that the JavaScript object returned will be the same each frame, so developers can use the object for equality checks or as a map key. That approach also leaves a "live" object in the developers hands, though, which can be tricky in some circumstances.

If that's not a guarantee we want to provide then the marker identifier should be exposed here. (If it's not exposed then I'm not completely clear on what the purpose of the identifier is?)

Thanks for flagging this, I reworked this slightly following the discussion in the group by introducing an XRMarker object so results for the same marker across frames will reference the same object (IDLs have been updated accordingly). The marker identifier can remain unexposed and internal for now.

I am not entirely sure the marker identifier is (still) needed actually, but we can discuss this further (#5). Changes: 3ec6971

Please refer to: 8cac5d7

Regarding anchors and whether they should be returned or exposed here, I mentioned this in #5 to discuss further (still thinking on it)

toji · 2026-09-14T21:30:36Z

+3. For each [=tracked marker=] |marker| in |session|'s [=list of tracked markers=]:
+    1. If |marker|'s [=marker tracking state=] is `"untracked"`, continue to the next entry.
+
+    2. Let |result| be a new `XRMarkerTrackingResult`.


Related to the above concern: This explicitly says that the JS value won't be comparable frame-to-frame, so a separate identifier would be needed. That's not how WebXR has generally approached these types of concerns, though, so it's worth further discussion.

I should have done this in the previous PR (apologies!) - updated the algorithm for the new XRMarker object. A new XRMarkerTrackingResult is still being created for each frame but it now references the marker object. I am not entirely sure this is the right way to go so definitely worth further discussions (#5).

Changes: a3d7c65

Please refer to: 8cac5d7

toji · 2026-09-14T21:33:21Z

+
+<section class="non-normative">
+Marker tracking is not intended to provide frame-perfect object tracking. Applications SHOULD account for tracking-state changes, pose updates and possible discontinuities when attaching virtual content to a marker.
+In particular, applications SHOULD avoid presenting emulated marker poses as though they were actively tracked poses for moving physical markers.


This partially answers my question from earlier about how developers are supposed to use the emulated information (though it may still be possible to support it through XRPose.emulatedPosition) I'm still a little unclear on what this means in practice, though?

Please refer to: 8cac5d7 (do we still need a solid example here maybe?)

toji · 2026-09-14T21:40:53Z

+  <a class="self-link" href="#set-up-marker-tracking-section"></a>
+</h4>
+
+In order to <dfn export>set up marker tracking</dfn> for a {{XRSystem/requestSession()}} session request, add the following steps to [=initialize the session=] for the new [=XRSession=] |session|:


I suspect that marker tracking will have non-trivial computational overhead. Do we need a way to turn it on and off over the course of the session? Do the underlying native capabilities support that?

I know that we've had similar conversations for other features, but browsing through similar tracking specs I'm not seeing start/stop methods, so perhaps it's a non-issue. Worth at least discussing, though.

This is a great point. I am leaning more towards providing a way to turn it on and off as that feels like the right thing to do from a web sustainability/performance point of view, and that would also be consistent with other modules in WebXR. It would also cover more use cases (i.e. some experiences may only need marker tracking briefly, while others may need continuous tracking or want to re-enable it later). Opened #21

Co-authored-by: Brandon Jones <tojiro@gmail.com>

…iptions/justification

Co-authored-by: Matthew Tylee Atkinson <matatk@users.noreply.github.com>

m-alkalbani · 2026-09-22T10:58:13Z

@himorin the pr-preview still doesn't seem to work, I tried adding it manually to the first comment but that didn't work either. Can you help when you have the chance please?

m-alkalbani · 2026-09-23T15:46:58Z

/tpac

himorin · 2026-09-23T17:16:21Z

@himorin the pr-preview still doesn't seem to work, I tried adding it manually to the first comment but that didn't work either. Can you help when you have the chance please?

check thread of https://lists.w3.org/Archives/Public/spec-prod/2026JulSep/0006.html

himorin · 2026-09-24T07:49:15Z

For validation error, consider switching <section class="non-normative"> part into 1) moving all into html including markdown heading part , or 2) having some other element to wrap them.

m-alkalbani · 2026-09-28T16:02:07Z

/agenda

Draft spec

7512afc

First draft of marker-tracking spec

m-alkalbani assigned toji, AdaRoseCannon and alcooper91 and unassigned toji, AdaRoseCannon and alcooper91 Sep 4, 2026

m-alkalbani requested review from AdaRoseCannon, alcooper91 and toji September 4, 2026 14:34

himorin mentioned this pull request Sep 4, 2026

init setup repo for automation #20

Merged

himorin mentioned this pull request Sep 9, 2026

fixup GHAction immersive-web/real-world-meshing#7

Draft

probot-label Bot added the agenda label Sep 11, 2026

himorin mentioned this pull request Sep 14, 2026

[wg/immersive-web] updated marker detection as current draft w3c/charter-drafts#880

Merged

Trigger pr-preview

b589930

toji reviewed Sep 14, 2026

View reviewed changes

m-alkalbani and others added 9 commits September 15, 2026 15:46

Apply suggestion from @toji

5d7c53a

Co-authored-by: Brandon Jones <tojiro@gmail.com>

Apply suggestion from @toji

d016275

Co-authored-by: Brandon Jones <tojiro@gmail.com>

Apply suggestion from @toji

132b384

Co-authored-by: Brandon Jones <tojiro@gmail.com>

Apply suggestion from @toji

b7181f4

Co-authored-by: Brandon Jones <tojiro@gmail.com>

expand marker symbology definition

217985f

expand dfn descriptions and reference fixes

eb9e4e2

amend XRMarkerTrackingState and expand "tracked" and "emulated" descr…

8cac5d7

…iptions/justification

add XRMarker object and update IDLs

3ec6971

update algorithm to include xrmarker object

a3d7c65

m-alkalbani mentioned this pull request Sep 18, 2026

Turn marker tracking on and off? #21

Open

This was referenced Sep 18, 2026

Supported code types #4

Open

What should a marker result expose? #5

Open

m-alkalbani removed the agenda label Sep 21, 2026

matatk reviewed Sep 22, 2026

View reviewed changes

Comment thread index.bs Outdated

Update index.bs

737fca7

Co-authored-by: Matthew Tylee Atkinson <matatk@users.noreply.github.com>

matatk reviewed Sep 22, 2026

View reviewed changes

Comment thread index.bs Outdated

matatk reviewed Sep 22, 2026

View reviewed changes

Comment thread index.bs Outdated

m-alkalbani and others added 3 commits September 22, 2026 10:21

Fix parsing errors

46dc8bd

Co-authored-by: Matthew Tylee Atkinson <matatk@users.noreply.github.com>

Fix parsing errors

1025aca

Co-authored-by: Matthew Tylee Atkinson <matatk@users.noreply.github.com>

Fix headings throughout

f8a57da

probot-label Bot added the TPAC label Sep 23, 2026

m-alkalbani requested review from cabanier and toji September 23, 2026 15:53

himorin mentioned this pull request Sep 25, 2026

[wg/immersive-web] Immersive Web WG 2026 Group Charter w3c/strategy#564

Open

1 of 4 tasks

probot-label Bot added the agenda label Sep 28, 2026

Conversation

m-alkalbani commented Sep 4, 2026 • edited by matatk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

m-alkalbani commented Sep 4, 2026

Uh oh!

m-alkalbani commented Sep 4, 2026

Uh oh!

himorin commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

m-alkalbani commented Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

toji left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

m-alkalbani commented Sep 22, 2026

Uh oh!

m-alkalbani commented Sep 23, 2026

Uh oh!

himorin commented Sep 23, 2026

Uh oh!

himorin commented Sep 24, 2026

Uh oh!

m-alkalbani commented Sep 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

m-alkalbani commented Sep 4, 2026 •

edited by matatk

Loading

himorin commented Sep 4, 2026 •

edited

Loading

m-alkalbani commented Sep 11, 2026 •

edited

Loading