-
Notifications
You must be signed in to change notification settings - Fork 13
/
index.html
1700 lines (1609 loc) · 116 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!doctype html><html lang="en">
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta content="width=device-width, initial-scale=1, shrink-to-fit=no" name="viewport">
<title>WebXR Marker Tracking Module</title>
<meta content="CG-DRAFT" name="w3c-status">
<link href="https://www.w3.org/StyleSheets/TR/2016/cg-draft" rel="stylesheet">
<link href="https://www.w3.org/2008/site/images/favicon.ico" rel="icon">
<meta content="Bikeshed version 3d6a6fcbb, updated Wed Jun 16 16:19:39 2021 -0700" name="generator">
<link href="https://immersive-web.github.io/marker-tracking/" rel="canonical">
<link href="favicon-32x32.png" rel="icon" sizes="32x32" type="image/png">
<link href="favicon-96x96.png" rel="icon" sizes="96x96" type="image/png">
<style>
.unstable::before {
content: "This section is not stable";
display: block;
font-weight: bold;
text-align: right;
color: red;
}
.unstable {
border: thin solid pink;
border-radius: .5em;
padding: .5em;
margin: .5em calc(-0.5em - 1px);
background-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='300' height='290'><text transform='rotate(-45)' text-anchor='middle' font-family='sans-serif' font-weight='bold' font-size='70' y='210' opacity='.1'>Unstable</text></svg>");
background-repeat: repeat;
background-color: #FFF4F4;
}
.unstable h3:first-of-type {
margin-top: 0.5rem;
}
.unstable.example:not(.no-marker)::before {
content: "Example " counter(example) " (Unstable)";
float: none;
}
.non-normative::before {
content: "This section is non-normative.";
font-style: italic;
}
.tg {
border-collapse: collapse;
border-spacing: 0;
}
.tg th {
border-style: solid;
border-width: 1px;
background: #90b8de;
color: #fff;
font-family: sans-serif;
font-weight: bold;
border-color: grey;
}
.tg td {
padding: 4px 5px;
background-color: rgb(221, 238, 255);
font-family: monospace;
border-style: solid;
border-width: 1px;
border-color: grey;
overflow: hidden;
word-break: normal;
}
</style>
<style>/* style-autolinks */
.css.css, .property.property, .descriptor.descriptor {
color: var(--a-normal-text);
font-size: inherit;
font-family: inherit;
}
.css::before, .property::before, .descriptor::before {
content: "‘";
}
.css::after, .property::after, .descriptor::after {
content: "’";
}
.property, .descriptor {
/* Don't wrap property and descriptor names */
white-space: nowrap;
}
.type { /* CSS value <type> */
font-style: italic;
}
pre .property::before, pre .property::after {
content: "";
}
[data-link-type="property"]::before,
[data-link-type="propdesc"]::before,
[data-link-type="descriptor"]::before,
[data-link-type="value"]::before,
[data-link-type="function"]::before,
[data-link-type="at-rule"]::before,
[data-link-type="selector"]::before,
[data-link-type="maybe"]::before {
content: "‘";
}
[data-link-type="property"]::after,
[data-link-type="propdesc"]::after,
[data-link-type="descriptor"]::after,
[data-link-type="value"]::after,
[data-link-type="function"]::after,
[data-link-type="at-rule"]::after,
[data-link-type="selector"]::after,
[data-link-type="maybe"]::after {
content: "’";
}
[data-link-type].production::before,
[data-link-type].production::after,
.prod [data-link-type]::before,
.prod [data-link-type]::after {
content: "";
}
[data-link-type=element],
[data-link-type=element-attr] {
font-family: Menlo, Consolas, "DejaVu Sans Mono", monospace;
font-size: .9em;
}
[data-link-type=element]::before { content: "<" }
[data-link-type=element]::after { content: ">" }
[data-link-type=biblio] {
white-space: pre;
}</style>
<style>/* style-colors */
/* Any --*-text not paired with a --*-bg is assumed to have a transparent bg */
:root {
color-scheme: light dark;
--text: black;
--bg: white;
--unofficial-watermark: url(https://www.w3.org/StyleSheets/TR/2016/logos/UD-watermark);
--logo-bg: #1a5e9a;
--logo-active-bg: #c00;
--logo-text: white;
--tocnav-normal-text: #707070;
--tocnav-normal-bg: var(--bg);
--tocnav-hover-text: var(--tocnav-normal-text);
--tocnav-hover-bg: #f8f8f8;
--tocnav-active-text: #c00;
--tocnav-active-bg: var(--tocnav-normal-bg);
--tocsidebar-text: var(--text);
--tocsidebar-bg: #f7f8f9;
--tocsidebar-shadow: rgba(0,0,0,.1);
--tocsidebar-heading-text: hsla(203,20%,40%,.7);
--toclink-text: var(--text);
--toclink-underline: #3980b5;
--toclink-visited-text: var(--toclink-text);
--toclink-visited-underline: #054572;
--heading-text: #005a9c;
--hr-text: var(--text);
--algo-border: #def;
--del-text: red;
--del-bg: transparent;
--ins-text: #080;
--ins-bg: transparent;
--a-normal-text: #034575;
--a-normal-underline: #bbb;
--a-visited-text: var(--a-normal-text);
--a-visited-underline: #707070;
--a-hover-bg: rgba(75%, 75%, 75%, .25);
--a-active-text: #c00;
--a-active-underline: #c00;
--blockquote-border: silver;
--blockquote-bg: transparent;
--blockquote-text: currentcolor;
--issue-border: #e05252;
--issue-bg: #fbe9e9;
--issue-text: var(--text);
--issueheading-text: #831616;
--example-border: #e0cb52;
--example-bg: #fcfaee;
--example-text: var(--text);
--exampleheading-text: #574b0f;
--note-border: #52e052;
--note-bg: #e9fbe9;
--note-text: var(--text);
--noteheading-text: hsl(120, 70%, 30%);
--notesummary-underline: silver;
--assertion-border: #aaa;
--assertion-bg: #eee;
--assertion-text: black;
--advisement-border: orange;
--advisement-bg: #fec;
--advisement-text: var(--text);
--advisementheading-text: #b35f00;
--warning-border: red;
--warning-bg: hsla(40,100%,50%,0.95);
--warning-text: var(--text);
--amendment-border: #330099;
--amendment-bg: #F5F0FF;
--amendment-text: var(--text);
--amendmentheading-text: #220066;
--def-border: #8ccbf2;
--def-bg: #def;
--def-text: var(--text);
--defrow-border: #bbd7e9;
--datacell-border: silver;
--indexinfo-text: #707070;
--indextable-hover-text: black;
--indextable-hover-bg: #f7f8f9;
--outdatedspec-bg: rgba(0, 0, 0, .5);
--outdatedspec-text: black;
--outdated-bg: maroon;
--outdated-text: white;
--outdated-shadow: red;
--editedrec-bg: darkorange;
}</style>
<style>/* style-counters */
body {
counter-reset: example figure issue;
}
.issue {
counter-increment: issue;
}
.issue:not(.no-marker)::before {
content: "Issue " counter(issue);
}
.example {
counter-increment: example;
}
.example:not(.no-marker)::before {
content: "Example " counter(example);
}
.invalid.example:not(.no-marker)::before,
.illegal.example:not(.no-marker)::before {
content: "Invalid Example" counter(example);
}
figcaption {
counter-increment: figure;
}
figcaption:not(.no-marker)::before {
content: "Figure " counter(figure) " ";
}</style>
<style>/* style-dfn-panel */
:root {
--dfnpanel-bg: #ddd;
--dfnpanel-text: var(--text);
}
.dfn-panel {
position: absolute;
z-index: 35;
height: auto;
width: -webkit-fit-content;
width: fit-content;
max-width: 300px;
max-height: 500px;
overflow: auto;
padding: 0.5em 0.75em;
font: small Helvetica Neue, sans-serif, Droid Sans Fallback;
background: var(--dfnpanel-bg);
color: var(--dfnpanel-text);
border: outset 0.2em;
}
.dfn-panel:not(.on) { display: none; }
.dfn-panel * { margin: 0; padding: 0; text-indent: 0; }
.dfn-panel > b { display: block; }
.dfn-panel a { color: var(--dfnpanel-text); }
.dfn-panel a:not(:hover) { text-decoration: none !important; border-bottom: none !important; }
.dfn-panel > b + b { margin-top: 0.25em; }
.dfn-panel ul { padding: 0; }
.dfn-panel li { list-style: inside; }
.dfn-panel.activated {
display: inline-block;
position: fixed;
left: .5em;
bottom: 2em;
margin: 0 auto;
max-width: calc(100vw - 1.5em - .4em - .5em);
max-height: 30vh;
}
.dfn-paneled { cursor: pointer; }
</style>
<style>/* style-md-lists */
/* This is a weird hack for me not yet following the commonmark spec
regarding paragraph and lists. */
[data-md] > :first-child {
margin-top: 0;
}
[data-md] > :last-child {
margin-bottom: 0;
}</style>
<style>/* style-selflinks */
:root {
--selflink-text: white;
--selflink-bg: gray;
--selflink-hover-text: black;
}
.heading, .issue, .note, .example, li, dt {
position: relative;
}
a.self-link {
position: absolute;
top: 0;
left: calc(-1 * (3.5rem - 26px));
width: calc(3.5rem - 26px);
height: 2em;
text-align: center;
border: none;
transition: opacity .2s;
opacity: .5;
}
a.self-link:hover {
opacity: 1;
}
.heading > a.self-link {
font-size: 83%;
}
li > a.self-link {
left: calc(-1 * (3.5rem - 26px) - 2em);
}
dfn > a.self-link {
top: auto;
left: auto;
opacity: 0;
width: 1.5em;
height: 1.5em;
background: var(--selflink-bg);
color: var(--selflink-text);
font-style: normal;
transition: opacity .2s, background-color .2s, color .2s;
}
dfn:hover > a.self-link {
opacity: 1;
}
dfn > a.self-link:hover {
color: var(--selflink-hover-text);
}
a.self-link::before { content: "¶"; }
.heading > a.self-link::before { content: "§"; }
dfn > a.self-link::before { content: "#"; }
</style>
<style>/* style-syntax-highlighting */
pre.idl.highlight {
background: var(--borderedblock-bg, var(--def-bg));
}
code.highlight { padding: .1em; border-radius: .3em; }
pre.highlight, pre > code.highlight { display: block; padding: 1em; margin: .5em 0; overflow: auto; border-radius: 0; }
.highlight:not(.idl) { background: rgba(0, 0, 0, .03); }
c-[a] { color: #990055 } /* Keyword.Declaration */
c-[b] { color: #990055 } /* Keyword.Type */
c-[c] { color: #708090 } /* Comment */
c-[d] { color: #708090 } /* Comment.Multiline */
c-[e] { color: #0077aa } /* Name.Attribute */
c-[f] { color: #669900 } /* Name.Tag */
c-[g] { color: #222222 } /* Name.Variable */
c-[k] { color: #990055 } /* Keyword */
c-[l] { color: #000000 } /* Literal */
c-[m] { color: #000000 } /* Literal.Number */
c-[n] { color: #0077aa } /* Name */
c-[o] { color: #999999 } /* Operator */
c-[p] { color: #999999 } /* Punctuation */
c-[s] { color: #a67f59 } /* Literal.String */
c-[t] { color: #a67f59 } /* Literal.String.Single */
c-[u] { color: #a67f59 } /* Literal.String.Double */
c-[cp] { color: #708090 } /* Comment.Preproc */
c-[c1] { color: #708090 } /* Comment.Single */
c-[cs] { color: #708090 } /* Comment.Special */
c-[kc] { color: #990055 } /* Keyword.Constant */
c-[kn] { color: #990055 } /* Keyword.Namespace */
c-[kp] { color: #990055 } /* Keyword.Pseudo */
c-[kr] { color: #990055 } /* Keyword.Reserved */
c-[ld] { color: #000000 } /* Literal.Date */
c-[nc] { color: #0077aa } /* Name.Class */
c-[no] { color: #0077aa } /* Name.Constant */
c-[nd] { color: #0077aa } /* Name.Decorator */
c-[ni] { color: #0077aa } /* Name.Entity */
c-[ne] { color: #0077aa } /* Name.Exception */
c-[nf] { color: #0077aa } /* Name.Function */
c-[nl] { color: #0077aa } /* Name.Label */
c-[nn] { color: #0077aa } /* Name.Namespace */
c-[py] { color: #0077aa } /* Name.Property */
c-[ow] { color: #999999 } /* Operator.Word */
c-[mb] { color: #000000 } /* Literal.Number.Bin */
c-[mf] { color: #000000 } /* Literal.Number.Float */
c-[mh] { color: #000000 } /* Literal.Number.Hex */
c-[mi] { color: #000000 } /* Literal.Number.Integer */
c-[mo] { color: #000000 } /* Literal.Number.Oct */
c-[sb] { color: #a67f59 } /* Literal.String.Backtick */
c-[sc] { color: #a67f59 } /* Literal.String.Char */
c-[sd] { color: #a67f59 } /* Literal.String.Doc */
c-[se] { color: #a67f59 } /* Literal.String.Escape */
c-[sh] { color: #a67f59 } /* Literal.String.Heredoc */
c-[si] { color: #a67f59 } /* Literal.String.Interpol */
c-[sx] { color: #a67f59 } /* Literal.String.Other */
c-[sr] { color: #a67f59 } /* Literal.String.Regex */
c-[ss] { color: #a67f59 } /* Literal.String.Symbol */
c-[vc] { color: #0077aa } /* Name.Variable.Class */
c-[vg] { color: #0077aa } /* Name.Variable.Global */
c-[vi] { color: #0077aa } /* Name.Variable.Instance */
c-[il] { color: #000000 } /* Literal.Number.Integer.Long */
</style>
<style>/* style-var-click-highlighting */
var { cursor: pointer; }
var.selected0 { background-color: #F4D200; box-shadow: 0 0 0 2px #F4D200; }
var.selected1 { background-color: #FF87A2; box-shadow: 0 0 0 2px #FF87A2; }
var.selected2 { background-color: #96E885; box-shadow: 0 0 0 2px #96E885; }
var.selected3 { background-color: #3EEED2; box-shadow: 0 0 0 2px #3EEED2; }
var.selected4 { background-color: #EACFB6; box-shadow: 0 0 0 2px #EACFB6; }
var.selected5 { background-color: #82DDFF; box-shadow: 0 0 0 2px #82DDFF; }
var.selected6 { background-color: #FFBCF2; box-shadow: 0 0 0 2px #FFBCF2; }
</style>
<style>/* style-darkmode */
@media (prefers-color-scheme: dark) {
:root {
--text: #ddd;
--bg: black;
--unofficial-watermark: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='400'%3E%3Cg fill='%23100808' transform='translate(200 200) rotate(-45) translate(-200 -200)' stroke='%23100808' stroke-width='3'%3E%3Ctext x='50%25' y='220' style='font: bold 70px sans-serif; text-anchor: middle; letter-spacing: 6px;'%3EUNOFFICIAL%3C/text%3E%3Ctext x='50%25' y='305' style='font: bold 70px sans-serif; text-anchor: middle; letter-spacing: 6px;'%3EDRAFT%3C/text%3E%3C/g%3E%3C/svg%3E");
--logo-bg: #1a5e9a;
--logo-active-bg: #c00;
--logo-text: white;
--tocnav-normal-text: #999;
--tocnav-normal-bg: var(--bg);
--tocnav-hover-text: var(--tocnav-normal-text);
--tocnav-hover-bg: #080808;
--tocnav-active-text: #f44;
--tocnav-active-bg: var(--tocnav-normal-bg);
--tocsidebar-text: var(--text);
--tocsidebar-bg: #080808;
--tocsidebar-shadow: rgba(255,255,255,.1);
--tocsidebar-heading-text: hsla(203,20%,40%,.7);
--toclink-text: var(--text);
--toclink-underline: #6af;
--toclink-visited-text: var(--toclink-text);
--toclink-visited-underline: #054572;
--heading-text: #8af;
--hr-text: var(--text);
--algo-border: #456;
--del-text: #f44;
--del-bg: transparent;
--ins-text: #4a4;
--ins-bg: transparent;
--a-normal-text: #6af;
--a-normal-underline: #555;
--a-visited-text: var(--a-normal-text);
--a-visited-underline: var(--a-normal-underline);
--a-hover-bg: rgba(25%, 25%, 25%, .2);
--a-active-text: #f44;
--a-active-underline: var(--a-active-text);
--borderedblock-bg: rgba(255, 255, 255, .05);
--blockquote-border: silver;
--blockquote-bg: var(--borderedblock-bg);
--blockquote-text: currentcolor;
--issue-border: #e05252;
--issue-bg: var(--borderedblock-bg);
--issue-text: var(--text);
--issueheading-text: hsl(0deg, 70%, 70%);
--example-border: hsl(50deg, 90%, 60%);
--example-bg: var(--borderedblock-bg);
--example-text: var(--text);
--exampleheading-text: hsl(50deg, 70%, 70%);
--note-border: hsl(120deg, 100%, 35%);
--note-bg: var(--borderedblock-bg);
--note-text: var(--text);
--noteheading-text: hsl(120, 70%, 70%);
--notesummary-underline: silver;
--assertion-border: #444;
--assertion-bg: var(--borderedblock-bg);
--assertion-text: var(--text);
--advisement-border: orange;
--advisement-bg: #222218;
--advisement-text: var(--text);
--advisementheading-text: #f84;
--warning-border: red;
--warning-bg: hsla(40,100%,20%,0.95);
--warning-text: var(--text);
--amendment-border: #330099;
--amendment-bg: #080010;
--amendment-text: var(--text);
--amendmentheading-text: #cc00ff;
--def-border: #8ccbf2;
--def-bg: #080818;
--def-text: var(--text);
--defrow-border: #136;
--datacell-border: silver;
--indexinfo-text: #aaa;
--indextable-hover-text: var(--text);
--indextable-hover-bg: #181818;
--outdatedspec-bg: rgba(255, 255, 255, .5);
--outdatedspec-text: black;
--outdated-bg: maroon;
--outdated-text: white;
--outdated-shadow: red;
--editedrec-bg: darkorange;
}
/* In case a transparent-bg image doesn't expect to be on a dark bg,
which is quite common in practice... */
img { background: white; }
}
@media (prefers-color-scheme: dark) {
:root {
--selflink-text: black;
--selflink-bg: silver;
--selflink-hover-text: white;
}
}
@media (prefers-color-scheme: dark) {
:root {
--dfnpanel-bg: #222;
--dfnpanel-text: var(--text);
}
}
@media (prefers-color-scheme: dark) {
.highlight:not(.idl) { background: rgba(255, 255, 255, .05); }
c-[a] { color: #d33682 } /* Keyword.Declaration */
c-[b] { color: #d33682 } /* Keyword.Type */
c-[c] { color: #2aa198 } /* Comment */
c-[d] { color: #2aa198 } /* Comment.Multiline */
c-[e] { color: #268bd2 } /* Name.Attribute */
c-[f] { color: #b58900 } /* Name.Tag */
c-[g] { color: #cb4b16 } /* Name.Variable */
c-[k] { color: #d33682 } /* Keyword */
c-[l] { color: #657b83 } /* Literal */
c-[m] { color: #657b83 } /* Literal.Number */
c-[n] { color: #268bd2 } /* Name */
c-[o] { color: #657b83 } /* Operator */
c-[p] { color: #657b83 } /* Punctuation */
c-[s] { color: #6c71c4 } /* Literal.String */
c-[t] { color: #6c71c4 } /* Literal.String.Single */
c-[u] { color: #6c71c4 } /* Literal.String.Double */
c-[ch] { color: #2aa198 } /* Comment.Hashbang */
c-[cp] { color: #2aa198 } /* Comment.Preproc */
c-[cpf] { color: #2aa198 } /* Comment.PreprocFile */
c-[c1] { color: #2aa198 } /* Comment.Single */
c-[cs] { color: #2aa198 } /* Comment.Special */
c-[kc] { color: #d33682 } /* Keyword.Constant */
c-[kn] { color: #d33682 } /* Keyword.Namespace */
c-[kp] { color: #d33682 } /* Keyword.Pseudo */
c-[kr] { color: #d33682 } /* Keyword.Reserved */
c-[ld] { color: #657b83 } /* Literal.Date */
c-[nc] { color: #268bd2 } /* Name.Class */
c-[no] { color: #268bd2 } /* Name.Constant */
c-[nd] { color: #268bd2 } /* Name.Decorator */
c-[ni] { color: #268bd2 } /* Name.Entity */
c-[ne] { color: #268bd2 } /* Name.Exception */
c-[nf] { color: #268bd2 } /* Name.Function */
c-[nl] { color: #268bd2 } /* Name.Label */
c-[nn] { color: #268bd2 } /* Name.Namespace */
c-[py] { color: #268bd2 } /* Name.Property */
c-[ow] { color: #657b83 } /* Operator.Word */
c-[mb] { color: #657b83 } /* Literal.Number.Bin */
c-[mf] { color: #657b83 } /* Literal.Number.Float */
c-[mh] { color: #657b83 } /* Literal.Number.Hex */
c-[mi] { color: #657b83 } /* Literal.Number.Integer */
c-[mo] { color: #657b83 } /* Literal.Number.Oct */
c-[sa] { color: #6c71c4 } /* Literal.String.Affix */
c-[sb] { color: #6c71c4 } /* Literal.String.Backtick */
c-[sc] { color: #6c71c4 } /* Literal.String.Char */
c-[dl] { color: #6c71c4 } /* Literal.String.Delimiter */
c-[sd] { color: #6c71c4 } /* Literal.String.Doc */
c-[se] { color: #6c71c4 } /* Literal.String.Escape */
c-[sh] { color: #6c71c4 } /* Literal.String.Heredoc */
c-[si] { color: #6c71c4 } /* Literal.String.Interpol */
c-[sx] { color: #6c71c4 } /* Literal.String.Other */
c-[sr] { color: #6c71c4 } /* Literal.String.Regex */
c-[ss] { color: #6c71c4 } /* Literal.String.Symbol */
c-[fm] { color: #268bd2 } /* Name.Function.Magic */
c-[vc] { color: #cb4b16 } /* Name.Variable.Class */
c-[vg] { color: #cb4b16 } /* Name.Variable.Global */
c-[vi] { color: #cb4b16 } /* Name.Variable.Instance */
c-[vm] { color: #cb4b16 } /* Name.Variable.Magic */
c-[il] { color: #657b83 } /* Literal.Number.Integer.Long */
}
</style>
<body class="h-entry">
<div class="head">
<p data-fill-with="logo"><a class="logo" href="https://www.w3.org/"> <img alt="W3C" height="48" src="https://www.w3.org/StyleSheets/TR/2016/logos/W3C" width="72"> </a> </p>
<h1 class="p-name no-ref" id="title">WebXR Marker Tracking Module</h1>
<h2 class="no-num no-toc no-ref heading settled" id="profile-and-date"><span class="content">Draft Community Group Report, <time class="dt-updated" datetime="2021-07-02">2 July 2021</time></span></h2>
<div data-fill-with="spec-metadata">
<dl>
<dt>This version:
<dd><a class="u-url" href="https://immersive-web.github.io/marker-tracking/">https://immersive-web.github.io/marker-tracking/</a>
<dt>Issue Tracking:
<dd><a href="https://github.com/immersive-web/marker-tracking/issues/">GitHub</a>
<dt class="editor">Editor:
<dd class="editor p-author h-card vcard" data-editor-id="113597"><a class="p-name fn u-email email" href="mailto:[email protected]">Klaus Weidner</a> (<a class="p-org org" href="http://google.com/">Google</a>)
<dt>Participate:
<dd><a href="https://github.com/immersive-web/marker-tracking/issues/new">File an issue</a> (<a href="https://github.com/immersive-web/marker-tracking/issues">open issues</a>)
<dd><a href="https://lists.w3.org/Archives/Public/public-immersive-web/">Mailing list archive</a>
<dd><a href="irc://irc.w3.org:6665/">W3C’s #immersive-web IRC</a>
</dl>
</div>
<div data-fill-with="warning">
<details class="annoying-warning" open>
<summary>Unstable API</summary>
<p><b>The API represented in this document is under development and may change at any time.</b></p>
<p>For additional context on the use of this API please reference the <a href="https://github.com/immersive-web/marker-tracking/blob/master/explainer.md">WebXR Marker Tracking Module Explainer</a>.</p>
</details>
</div>
<p class="copyright" data-fill-with="copyright"><a href="https://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © 2021 <a href="https://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup> (<a href="https://www.csail.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>, <a href="https://www.ercim.eu/"><abbr title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href="https://www.keio.ac.jp/">Keio</a>, <a href="https://ev.buaa.edu.cn/">Beihang</a>). W3C <a href="https://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="https://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document" rel="license">permissive document license</a> rules apply. </p>
<hr title="Separator for header">
</div>
<div class="p-summary" data-fill-with="abstract">
<h2 class="no-num no-toc no-ref heading settled" id="abstract"><span class="content">Abstract</span></h2>
<p>The Marker Tracking module expands the <a href="https://www.w3.org/TR/webxr/">WebXR Device API</a> with functionality to detect 2D images from a specified set and track their poses in the real world.</p>
</div>
<h2 class="no-num no-toc no-ref heading settled" id="sotd"><span class="content">Status of this document</span></h2>
<div data-fill-with="status">
<p></p>
</div>
<div data-fill-with="at-risk"></div>
<nav data-fill-with="table-of-contents" id="toc">
<h2 class="no-num no-toc no-ref" id="contents">Table of Contents</h2>
<ol class="toc" role="directory">
<li><a href="#intro"><span class="secno">1</span> <span class="content">Introduction</span></a>
<li>
<a href="#model"><span class="secno">2</span> <span class="content">Model</span></a>
<ol class="toc">
<li><a href="#spec-tracked-image"><span class="secno">2.1</span> <span class="content">Tracked Image</span></a>
</ol>
<li>
<a href="#webxr-device-api-integration"><span class="secno">3</span> <span class="content">WebXR Device API Integration</span></a>
<ol class="toc">
<li><a href="#xrsessioninit"><span class="secno">3.1</span> <span class="content">XRSessionInit</span></a>
<li><a href="#xrsession"><span class="secno">3.2</span> <span class="content">XRSession</span></a>
<li><a href="#xrframe"><span class="secno">3.3</span> <span class="content">XRFrame</span></a>
</ol>
<li>
<a href="#security"><span class="secno">4</span> <span class="content">Security, Privacy, and Comfort Considerations</span></a>
<ol class="toc">
<li><a href="#sensitive-information"><span class="secno">4.1</span> <span class="content">Sensitive Information</span></a>
<li>
<a href="#protected-functionality"><span class="secno">4.2</span> <span class="content">Protected functionality</span></a>
<ol class="toc">
<li><a href="#protect-image-presence"><span class="secno">4.2.1</span> <span class="content">Presence of images</span></a>
</ol>
</ol>
<li><a href="#ack"><span class="secno">5</span> <span class="content">Acknowledgements</span></a>
<li>
<a href="#w3c-conformance"><span class="secno"></span> <span class="content">Conformance</span></a>
<ol class="toc">
<li><a href="#w3c-conventions"><span class="secno"></span> <span class="content">Document conventions</span></a>
<li><a href="#w3c-conformant-algorithms"><span class="secno"></span> <span class="content">Conformant Algorithms</span></a>
</ol>
<li>
<a href="#index"><span class="secno"></span> <span class="content">Index</span></a>
<ol class="toc">
<li><a href="#index-defined-here"><span class="secno"></span> <span class="content">Terms defined by this specification</span></a>
<li><a href="#index-defined-elsewhere"><span class="secno"></span> <span class="content">Terms defined by reference</span></a>
</ol>
<li>
<a href="#references"><span class="secno"></span> <span class="content">References</span></a>
<ol class="toc">
<li><a href="#normative"><span class="secno"></span> <span class="content">Normative References</span></a>
</ol>
<li><a href="#idl-index"><span class="secno"></span> <span class="content">IDL Index</span></a>
</ol>
</nav>
<main>
<h2 class="heading settled" data-level="1" id="intro"><span class="secno">1. </span><span class="content">Introduction</span><a class="self-link" href="#intro"></a></h2>
<section class="non-normative">
<p>This module describes a mechanism for detecting 2D images in the real world and tracking their poses (position and orientation). The application supplies a set of images to be tracked when requesting an XR session. The XR device determines if the images are suitable for tracking, and returns information about their real-world position and orientation as they are detected in the user’s environment.</p>
<p>Since detecting and tracking these images happens locally on the device, this functionality can be implemented without providing camera images to the application.</p>
</section>
<h2 class="heading settled" data-level="2" id="model"><span class="secno">2. </span><span class="content">Model</span><a class="self-link" href="#model"></a></h2>
<h3 class="heading settled" data-level="2.1" id="spec-tracked-image"><span class="secno">2.1. </span><span class="content">Tracked Image</span><a class="self-link" href="#spec-tracked-image"></a></h3>
<p>A <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport id="tracked-image">tracked image</dfn> corresponds to the information used by the XR device to track an image.</p>
<p>A <a data-link-type="dfn" href="#tracked-image" id="ref-for-tracked-image">tracked image</a> has an associated integer <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport id="image-index">image index</dfn> which is the zero-based index of this image in the <code class="idl"><a data-link-type="idl" href="#dom-xrsessioninit-trackedimages" id="ref-for-dom-xrsessioninit-trackedimages">trackedImages</a></code> sequence provided in the session request.</p>
<p>A <a data-link-type="dfn" href="#tracked-image" id="ref-for-tracked-image①">tracked image</a> has an associated <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport id="image-trackable">image trackable</dfn> status which corresponds to the XR device’s ability to track this image based on characteristics of the supplied image itself. This is a boolean value, it is <code>false</code> if the image is unsuitable for tracking and guaranteed to never appear in image tracking results for this <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrsession" id="ref-for-xrsession">XRSession</a></code>, and otherwise <code>true</code>.</p>
<p>A <a data-link-type="dfn" href="#tracked-image" id="ref-for-tracked-image②">tracked image</a> has an <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport id="image-was-detected">image was detected</dfn> flag. This is initially <code>false</code>. It is set to <code>true</code> once the <a data-link-type="dfn" href="#suitable-for-tracking" id="ref-for-suitable-for-tracking">suitable for tracking</a> algorithm returns <code>true</code> for a frame, and then remains <code>true</code> for the rest of the <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrsession" id="ref-for-xrsession①">XRSession</a></code>.</p>
<p class="note" role="note"><span>NOTE:</span> A <code>true</code> value returned by the <a data-link-type="dfn" href="#suitable-for-tracking" id="ref-for-suitable-for-tracking①">suitable for tracking</a> algorithm indicates that the XR device has found this image during this session, its current view meets suitability requirements, and that the UA is going to provide tracking information for it from this point onward without further suitability checks.</p>
<p>A <a data-link-type="dfn" href="#tracked-image" id="ref-for-tracked-image③">tracked image</a> has an associated <code class="idl"><a data-link-type="idl" href="#enumdef-xrimagetrackingstate" id="ref-for-enumdef-xrimagetrackingstate">XRImageTrackingState</a></code> <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport id="image-tracking-state">image tracking state</dfn>. This is <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-untracked" id="ref-for-dom-xrimagetrackingstate-untracked">"untracked"</a></code> if the image is not being tracked at all, <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-tracked" id="ref-for-dom-xrimagetrackingstate-tracked">"tracked"</a></code> if it is actively being tracked and visible, or <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-emulated" id="ref-for-dom-xrimagetrackingstate-emulated">"emulated"</a></code> if its pose is extrapolated from a past tracked state.</p>
<p class="note" role="note"><span>NOTE:</span> <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-tracked" id="ref-for-dom-xrimagetrackingstate-tracked①">"tracked"</a></code> typically means the image was recognized and is currently being actively tracked in 3D space, and is at least partially visible to a tracking camera. (This does not necessarily mean that it’s visible in the user’s viewport in case that differs from the tracking camera field of view.) <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-emulated" id="ref-for-dom-xrimagetrackingstate-emulated①">"emulated"</a></code> means that the image was recognized and tracked recently, but may currently be out of camera view or obscured, and the reported pose is based on assuming that the object remains at the same position and orientation as when it was last seen. This pose is likely to be adequate for a poster attached to a wall, but may be unhelpful for an image attached to a moving object.</p>
<p class="note" role="note"><span>NOTE:</span> The <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-untracked" id="ref-for-dom-xrimagetrackingstate-untracked①">"untracked"</a></code> value for <a data-link-type="dfn" href="#image-tracking-state" id="ref-for-image-tracking-state">image tracking state</a> is an internal detail of the algorithms described below. The <code class="idl"><a data-link-type="idl" href="#dom-xrframe-getimagetrackingresults" id="ref-for-dom-xrframe-getimagetrackingresults">getImageTrackingResults()</a></code> API only returns information about images where the state is either <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-tracked" id="ref-for-dom-xrimagetrackingstate-tracked②">"tracked"</a></code> or <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-emulated" id="ref-for-dom-xrimagetrackingstate-emulated②">"emulated"</a></code>.</p>
<p>A <a data-link-type="dfn" href="#tracked-image" id="ref-for-tracked-image④">tracked image</a> has an associated <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrspace" id="ref-for-xrspace">XRSpace</a></code> <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport id="image-space">image space</dfn> that represents the tracking system’s <a data-link-type="dfn" href="https://immersive-web.github.io/webxr/#6dof" id="ref-for-6dof">6DoF</a> pose of the image in the user’s environment. The <a data-link-type="dfn" href="#image-space" id="ref-for-image-space">image space</a> origin is the center point of the tracked image. The +x axis points toward the right edge of the image and +y toward the top of the image. The +z axis is orthogonal to the picture plane, pointing toward the viewer when the image’s front is in view.</p>
<p>The <a data-link-type="dfn" href="#image-space" id="ref-for-image-space①">image space</a> is used for <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#dom-xrframe-getpose" id="ref-for-dom-xrframe-getpose">getPose()</a></code> calls according to the <a data-link-type="dfn" href="https://immersive-web.github.io/webxr/#populate-the-pose" id="ref-for-populate-the-pose">populate the pose</a> algorithm with <code>force emulation</code> set to <code>false</code>. The tracking system MAY provide either actively tracked or statically known (emulated) poses.</p>
<p class="note" role="note"><span>NOTE:</span> A <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#dom-xrframe-getpose" id="ref-for-dom-xrframe-getpose①">getPose()</a></code> call using the <a data-link-type="dfn" href="#image-space" id="ref-for-image-space②">image space</a> of an image with an <a data-link-type="dfn" href="#image-tracking-state" id="ref-for-image-tracking-state①">image tracking state</a> of <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-untracked" id="ref-for-dom-xrimagetrackingstate-untracked②">"untracked"</a></code> will report a <code>null</code> pose.</p>
<p class="note" role="note"><span>NOTE:</span> For tracked images, the returned pose’s <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#dom-xrpose-emulatedposition" id="ref-for-dom-xrpose-emulatedposition">emulatedPosition</a></code> value is always <code>false</code>. This attribute is intended to indicate a pose with a known orientation combined with an unknown position, for example a <a data-link-type="dfn" href="https://immersive-web.github.io/webxr/#3dof" id="ref-for-3dof">3DoF</a> headset, and that doesn’t fit this use case where both orientation and pose are emulated. Instead, the tracking system treats previously seen but not actively tracked images as statically known, and uses the <a data-link-type="dfn" href="#image-tracking-state" id="ref-for-image-tracking-state②">image tracking state</a> <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-emulated" id="ref-for-dom-xrimagetrackingstate-emulated③">"emulated"</a></code> to distinguish them from actively tracked images with <a data-link-type="dfn" href="#image-tracking-state" id="ref-for-image-tracking-state③">image tracking state</a> <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-tracked" id="ref-for-dom-xrimagetrackingstate-tracked③">"tracked"</a></code>.</p>
<p>A <a data-link-type="dfn" href="#tracked-image" id="ref-for-tracked-image⑤">tracked image</a> has an associated float <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport id="measured-width-in-meters">measured width in meters</dfn> corresponding to the physical width of the image as measured by the tracking system. It is zero if the device is unable to measure the image’s size.</p>
<h2 class="heading settled" data-level="3" id="webxr-device-api-integration"><span class="secno">3. </span><span class="content">WebXR Device API Integration</span><a class="self-link" href="#webxr-device-api-integration"></a></h2>
<p>This module expands the definitions of <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#dictdef-xrsessioninit" id="ref-for-dictdef-xrsessioninit">XRSessionInit</a></code>, <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrsession" id="ref-for-xrsession②">XRSession</a></code>, and <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrframe" id="ref-for-xrframe">XRFrame</a></code>.</p>
<h3 class="heading settled" data-level="3.1" id="xrsessioninit"><span class="secno">3.1. </span><span class="content">XRSessionInit</span><a class="self-link" href="#xrsessioninit"></a></h3>
<p>This module introduces the string <dfn class="dfn-paneled" data-dfn-for="feature descriptor" data-dfn-type="dfn" data-export id="feature-descriptor-marker-tracking">marker-tracking</dfn> as a new valid <a data-link-type="dfn" href="https://immersive-web.github.io/webxr/#feature-descriptor" id="ref-for-feature-descriptor">feature descriptor</a> for use in the <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#dom-xrsessioninit-requiredfeatures" id="ref-for-dom-xrsessioninit-requiredfeatures">requiredFeatures</a></code> or <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#dom-xrsessioninit-optionalfeatures" id="ref-for-dom-xrsessioninit-optionalfeatures">optionalFeatures</a></code> sequences for <a data-link-type="dfn" href="https://immersive-web.github.io/webxr/#immersive-session" id="ref-for-immersive-session">immersive sessions</a>.</p>
<p>A device is <a data-link-type="dfn" href="https://immersive-web.github.io/webxr/#capable-of-supporting" id="ref-for-capable-of-supporting">capable of supporting</a> the marker tracking feature if the XR device is capable of detecting and tracking images in the real world.</p>
<p class="note" role="note"><span>NOTE:</span> There is no guarantee that the specific images supplied for a session are trackable. For example, an image where all pixels have the same color would likely be untrackable due to lack of features, and some types of images such as synthetic markers may only be trackable on some implementations. However, a device should not claim to support the feature if it completely lacks tracking capability.</p>
<p>The XRSessionInit dictionary is expanded by adding a new <code class="idl"><a data-link-type="idl" href="#dom-xrsessioninit-trackedimages" id="ref-for-dom-xrsessioninit-trackedimages①">trackedImages</a></code> member that is used to <a data-link-type="dfn" href="#set-up-tracked-images" id="ref-for-set-up-tracked-images">set up tracked images</a>. It is a sequence of <code class="idl"><a data-link-type="idl" href="#dictdef-xrtrackedimageinit" id="ref-for-dictdef-xrtrackedimageinit">XRTrackedImageInit</a></code> values.</p>
<p class="note" role="note"><span>NOTE:</span> <code class="idl"><a data-link-type="idl" href="#dom-xrsessioninit-trackedimages" id="ref-for-dom-xrsessioninit-trackedimages②">trackedImages</a></code> is an optional member of <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#dictdef-xrsessioninit" id="ref-for-dictdef-xrsessioninit①">XRSessionInit</a></code>, but the feature will effectively be inactive if it is not supplied. There is no default set of tracked images.</p>
<pre class="idl highlight def"><c- b>dictionary</c-> <dfn class="dfn-paneled idl-code" data-dfn-type="dictionary" data-export id="dictdef-xrtrackedimageinit"><code><c- g>XRTrackedImageInit</c-></code></dfn> {
<c- b>required</c-> <a data-link-type="idl-name" href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap" id="ref-for-imagebitmap"><c- n>ImageBitmap</c-></a> <dfn class="idl-code" data-dfn-for="XRTrackedImageInit" data-dfn-type="dict-member" data-export data-type="ImageBitmap " id="dom-xrtrackedimageinit-image"><code><c- g>image</c-></code><a class="self-link" href="#dom-xrtrackedimageinit-image"></a></dfn>;
<c- b>required</c-> <a class="idl-code" data-link-type="interface" href="https://heycam.github.io/webidl/#idl-float" id="ref-for-idl-float"><c- b>float</c-></a> <dfn class="dfn-paneled idl-code" data-dfn-for="XRTrackedImageInit" data-dfn-type="dict-member" data-export data-type="float " id="dom-xrtrackedimageinit-widthinmeters"><code><c- g>widthInMeters</c-></code></dfn>;
};
<c- b>partial</c-> <c- b>dictionary</c-> <a class="idl-code" data-link-type="dictionary" href="https://immersive-web.github.io/webxr/#dictdef-xrsessioninit" id="ref-for-dictdef-xrsessioninit②"><c- g>XRSessionInit</c-></a> {
<a data-link-type="dfn" href="https://heycam.github.io/webidl/#idl-sequence" id="ref-for-idl-sequence"><c- b>sequence</c-></a><<a data-link-type="idl-name" href="#dictdef-xrtrackedimageinit" id="ref-for-dictdef-xrtrackedimageinit①"><c- n>XRTrackedImageInit</c-></a>> <dfn class="dfn-paneled idl-code" data-dfn-for="XRSessionInit" data-dfn-type="dict-member" data-export data-type="sequence<XRTrackedImageInit> " id="dom-xrsessioninit-trackedimages"><code><c- g>trackedImages</c-></code></dfn>;
};
</pre>
<p>Each <code class="idl"><a data-link-type="idl" href="#dom-xrsessioninit-trackedimages" id="ref-for-dom-xrsessioninit-trackedimages③">trackedImages</a></code> entry specifies an <code class="idl"><a data-link-type="idl" href="https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html#imagebitmap" id="ref-for-imagebitmap①">ImageBitmap</a></code> and a corresponding <code class="idl"><a data-link-type="idl" href="#dom-xrtrackedimageinit-widthinmeters" id="ref-for-dom-xrtrackedimageinit-widthinmeters">widthInMeters</a></code> value that provides expected physical width measurement for the real-world image being tracked. This width may be approximate but is required. If the actual width differs substantially from the provided width, the tracked image result MAY have an inaccurate reported position.</p>
<p class="note" role="note"><span>NOTE:</span> When viewed from a fixed camera position, a half-sized image at half the distance looks identical to a full-sized image, and the tracking system can’t differentiate these cases without additional context about the environment. The UA may be able to detect the actual size when tracking the image from multiple angles and update the measured width based on this, but is not required to do so.</p>
<p class="note" role="note"><span>NOTE:</span> The UA MAY emit local warnings such as developer console messages if it is unable to support the feature or if the supplied images are unsuitable for tracking.</p>
<div class="algorithm" data-algorithm="set-up-tracked-images">
<p>In order to <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport id="set-up-tracked-images">set up tracked images</dfn> for a <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#dom-xrsystem-requestsession" id="ref-for-dom-xrsystem-requestsession">requestSession()</a></code> session request, add the following steps to <a data-link-type="dfn" href="https://immersive-web.github.io/webxr/#initialize-the-session" id="ref-for-initialize-the-session">initialize the session</a> for the new <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrsession" id="ref-for-xrsession③">XRSession</a></code> <var>session</var>, with <var>requested image list</var> set to the value of <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#dictdef-xrsessioninit" id="ref-for-dictdef-xrsessioninit③">XRSessionInit</a></code>'s <code class="idl"><a data-link-type="idl" href="#dom-xrsessioninit-trackedimages" id="ref-for-dom-xrsessioninit-trackedimages④">trackedImages</a></code> attribute:</p>
<ol>
<li data-md>
<p>Set <var>session</var>’s <a data-link-type="dfn" href="#tracked-image" id="ref-for-tracked-image⑥">tracked images</a> to an empty list.</p>
<li data-md>
<p>If <code>marker-tracking</code> is not <a data-link-type="dfn" href="https://infra.spec.whatwg.org/#list-contain" id="ref-for-list-contain">contained</a> in <var>session</var>’s <a data-link-type="dfn" href="https://immersive-web.github.io/webxr/#xrsession-set-of-granted-features" id="ref-for-xrsession-set-of-granted-features">set of granted features</a>, abort these steps.</p>
<li data-md>
<p>If <var>requested image list</var> is undefined or an empty list, abort these steps.</p>
<li data-md>
<p>For each <var>requested image</var> in <var>requested image list</var>:</p>
<ol>
<li data-md>
<p>Set up any platform resources required to track <var>requested image</var>.</p>
<li data-md>
<p>Create a new <a data-link-type="dfn" href="#tracked-image" id="ref-for-tracked-image⑦">tracked image</a> <var>image</var>:</p>
<ol>
<li data-md>
<p>Set <var>image</var>’s <a data-link-type="dfn" href="#image-index" id="ref-for-image-index">image index</a> to the position index of this image in <var>requested image list</var>.</p>
<li data-md>
<p>Set <var>image</var>’s <a data-link-type="dfn" href="#image-trackable" id="ref-for-image-trackable">image trackable</a> to either <code>true</code> or <code>false</code> depending on the platform’s expected ability to track this image.</p>
<li data-md>
<p>Set <var>image</var>’s <a data-link-type="dfn" href="#image-was-detected" id="ref-for-image-was-detected">image was detected</a> flag to <code>false</code>.</p>
<li data-md>
<p>Set <var>image</var>’s <a data-link-type="dfn" href="#image-tracking-state" id="ref-for-image-tracking-state④">image tracking state</a> to <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-untracked" id="ref-for-dom-xrimagetrackingstate-untracked③">"untracked"</a></code>.</p>
<li data-md>
<p>Set <var>image</var>’s <a data-link-type="dfn" href="#measured-width-in-meters" id="ref-for-measured-width-in-meters">measured width in meters</a> to zero.</p>
<li data-md>
<p>If <a data-link-type="dfn" href="#image-trackable" id="ref-for-image-trackable①">image trackable</a> is true, set <var>image</var>’s <a data-link-type="dfn" href="#image-space" id="ref-for-image-space③">image space</a> to a device <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrspace" id="ref-for-xrspace①">XRSpace</a></code> associated with this image.</p>
</ol>
<li data-md>
<p>Append <var>image</var> to <a data-link-type="dfn" href="#tracked-image" id="ref-for-tracked-image⑧">tracked images</a>.</p>
</ol>
</ol>
</div>
<h3 class="heading settled" data-level="3.2" id="xrsession"><span class="secno">3.2. </span><span class="content">XRSession</span><a class="self-link" href="#xrsession"></a></h3>
<p>Each <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrsession" id="ref-for-xrsession④">XRSession</a></code> has a <dfn class="dfn-paneled" data-dfn-for="XRSession" data-dfn-type="dfn" data-noexport id="xrsession-list-of-tracked-images">list of tracked images</dfn> which is the <code class="idl"><a data-link-type="idl" href="#dom-xrsessioninit-trackedimages" id="ref-for-dom-xrsessioninit-trackedimages⑤">trackedImages</a></code> sequence supplied in the session request.</p>
<p>When a valid <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrsession" id="ref-for-xrsession⑤">XRSession</a></code> has been established with the <a data-link-type="dfn" href="#feature-descriptor-marker-tracking" id="ref-for-feature-descriptor-marker-tracking">marker-tracking</a> feature active, the <code class="idl"><a data-link-type="idl" href="#dom-xrsession-getimagetrackability" id="ref-for-dom-xrsession-getimagetrackability">getImageTrackability()</a></code> method can be used to <a data-link-type="dfn" href="#obtain-image-trackability" id="ref-for-obtain-image-trackability">obtain image trackability</a>, it returns a promise that provides information about the expected ability to use the provided images for tracking.</p>
<pre class="idl highlight def"><c- b>enum</c-> <dfn class="dfn-paneled idl-code" data-dfn-type="enum" data-export id="enumdef-xrimagetrackability"><code><c- g>XRImageTrackability</c-></code></dfn> {
<dfn class="dfn-paneled idl-code" data-dfn-for="XRImageTrackability" data-dfn-type="enum-value" data-export id="dom-xrimagetrackability-untrackable"><code><c- s>"untrackable"</c-></code></dfn>,
<dfn class="dfn-paneled idl-code" data-dfn-for="XRImageTrackability" data-dfn-type="enum-value" data-export id="dom-xrimagetrackability-trackable"><code><c- s>"trackable"</c-></code></dfn>,
};
<c- b>partial</c-> <c- b>interface</c-> <a class="idl-code" data-link-type="interface" href="https://immersive-web.github.io/webxr/#xrsession" id="ref-for-xrsession⑥"><c- g>XRSession</c-></a> {
<a class="idl-code" data-link-type="interface" href="https://heycam.github.io/webidl/#idl-promise" id="ref-for-idl-promise"><c- b>Promise</c-></a><<a class="idl-code" data-link-type="interface" href="https://heycam.github.io/webidl/#idl-frozen-array" id="ref-for-idl-frozen-array"><c- b>FrozenArray</c-></a><<a data-link-type="idl-name" href="#enumdef-xrimagetrackability" id="ref-for-enumdef-xrimagetrackability"><c- n>XRImageTrackability</c-></a>>> <dfn class="dfn-paneled idl-code" data-dfn-for="XRSession" data-dfn-type="method" data-export data-lt="getImageTrackability()" id="dom-xrsession-getimagetrackability"><code><c- g>getImageTrackability</c-></code></dfn>();
};
</pre>
<div class="algorithm" data-algorithm="obtain-image-trackability">
<p>In order to <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport id="obtain-image-trackability">obtain image trackability</dfn> for an <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrsession" id="ref-for-xrsession⑦">XRSession</a></code> <var>session</var>, the user agent MUST run the following steps:</p>
<ol>
<li data-md>
<p>Let <var>promise</var> be <a data-link-type="dfn" href="https://heycam.github.io/webidl/#a-new-promise" id="ref-for-a-new-promise">a new Promise</a> in the <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/webappapis.html#concept-relevant-realm" id="ref-for-concept-relevant-realm">relevant realm</a> of this <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrsession" id="ref-for-xrsession⑧">XRSession</a></code>.</p>
<li data-md>
<p>Run the following steps <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/infrastructure.html#in-parallel" id="ref-for-in-parallel">in parallel</a>:</p>
<ol>
<li data-md>
<p>Set <var>image trackabilities</var> to an empty list.</p>
<li data-md>
<p>For each <a data-link-type="dfn" href="#tracked-image" id="ref-for-tracked-image⑨">tracked image</a> <var>image</var> in <var>session</var>’s <a data-link-type="dfn" href="#xrsession-list-of-tracked-images" id="ref-for-xrsession-list-of-tracked-images">list of tracked images</a>:</p>
<ol>
<li data-md>
<p>Obtain an <code class="idl"><a data-link-type="idl" href="#enumdef-xrimagetrackability" id="ref-for-enumdef-xrimagetrackability①">XRImageTrackability</a></code> <var>trackability</var> from the XR device that represents the trackability of <var>image</var>.</p>
<li data-md>
<p>Append <var>trackability</var> to <var>image trackabilities</var>.</p>
</ol>
<li data-md>
<p><a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/webappapis.html#queue-a-task" id="ref-for-queue-a-task">queue a task</a> to <a data-link-type="dfn" href="https://heycam.github.io/webidl/#resolve" id="ref-for-resolve">resolve</a> <var>promise</var> with the value <var>image trackabilities</var>.</p>
</ol>
<li data-md>
<p>Return <var>promise</var>.</p>
</ol>
</div>
<p>The <code class="idl"><a data-link-type="idl" href="#enumdef-xrimagetrackability" id="ref-for-enumdef-xrimagetrackability②">XRImageTrackability</a></code> enum value <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackability-untrackable" id="ref-for-dom-xrimagetrackability-untrackable">"untrackable"</a></code> means that the image is not usable for tracking, for example due to having insufficient distinctive feature points, and this image MUST NOT appear in tracking results for this session. The value <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackability-trackable" id="ref-for-dom-xrimagetrackability-trackable">"trackable"</a></code> means that the image is potentially detectable.</p>
<p class="note" role="note"><span>NOTE:</span> Future versions of this API may define additional more granular values with quality estimates for trackable images. Applications should treat a value other than <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackability-untrackable" id="ref-for-dom-xrimagetrackability-untrackable①">"untrackable"</a></code> as representing a potentially trackable image.</p>
<h3 class="heading settled" data-level="3.3" id="xrframe"><span class="secno">3.3. </span><span class="content">XRFrame</span><a class="self-link" href="#xrframe"></a></h3>
<p>When marker tracking is active, add the <a data-link-type="dfn" href="#update-tracked-images" id="ref-for-update-tracked-images">update tracked images</a> algorithm to the <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrsession" id="ref-for-xrsession⑨">XRSession</a></code>'s <a data-link-type="dfn" href="https://immersive-web.github.io/webxr/#xrsession-list-of-frame-updates" id="ref-for-xrsession-list-of-frame-updates">list of frame updates</a>.</p>
<div class="algorithm" data-algorithm="update-tracked-images">
<p>In order to <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport id="update-tracked-images">update tracked images</dfn> for an <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrframe" id="ref-for-xrframe①">XRFrame</a></code> <var>frame</var> in an <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrsession" id="ref-for-xrsession①⓪">XRSession</a></code> <var>session</var>, the user agent MUST run the following steps:</p>
<ol>
<li data-md>
<p>For each <a data-link-type="dfn" href="#tracked-image" id="ref-for-tracked-image①⓪">tracked image</a> <var>image</var> in <var>session</var>’s <a data-link-type="dfn" href="#xrsession-list-of-tracked-images" id="ref-for-xrsession-list-of-tracked-images①">list of tracked images</a>, using the current device tracking state of <var>image</var> for <var>frame</var>:</p>
<dl>
<dt data-md>If the XR device has no tracking information for <var>image</var>:
<dd data-md>
<p>Set <var>image</var>’s <a data-link-type="dfn" href="#image-tracking-state" id="ref-for-image-tracking-state⑤">image tracking state</a> to <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-untracked" id="ref-for-dom-xrimagetrackingstate-untracked④">"untracked"</a></code>.</p>
<dt data-md>Otherwise:
<dd data-md>
<ol>
<li data-md>
<p>If <var>image</var>’s <a data-link-type="dfn" href="#image-was-detected" id="ref-for-image-was-detected①">image was detected</a> flag is <code>false</code>, and if the <a data-link-type="dfn" href="#suitable-for-tracking" id="ref-for-suitable-for-tracking②">suitable for tracking</a> algorithm for <var>image</var> returns <code>false</code>, continue to the next entry.</p>
<li data-md>
<p>Set <var>image</var>’s <a data-link-type="dfn" href="#image-was-detected" id="ref-for-image-was-detected②">image was detected</a> attribute to <code>true</code>.</p>
<li data-md>
<p>Set <var>image</var>’s <a data-link-type="dfn" href="#image-tracking-state" id="ref-for-image-tracking-state⑥">image tracking state</a> to <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-tracked" id="ref-for-dom-xrimagetrackingstate-tracked④">"tracked"</a></code> if the image is actively being tracked, or to <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-emulated" id="ref-for-dom-xrimagetrackingstate-emulated④">"emulated"</a></code> if the position is inferred based on previous observations.</p>
<li data-md>
<p>Set <var>image</var>’s <a data-link-type="dfn" href="#image-space" id="ref-for-image-space④">image space</a> based on the XR device’s estimate of the image’s pose.</p>
<li data-md>
<p>Set <var>image</var>’s <a data-link-type="dfn" href="#measured-width-in-meters" id="ref-for-measured-width-in-meters①">measured width in meters</a> based on the XR device’s estimated physical width if available, or set to zero if there is no available estimate.</p>
</ol>
</dl>
</ol>
</div>
<p>Applications can use the <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrframe" id="ref-for-xrframe②">XRFrame</a></code>'s <code class="idl"><a data-link-type="idl" href="#dom-xrframe-getimagetrackingresults" id="ref-for-dom-xrframe-getimagetrackingresults①">getImageTrackingResults()</a></code> method to <a data-link-type="dfn" href="#obtain-image-tracking-results" id="ref-for-obtain-image-tracking-results">obtain image tracking results</a> about the current state of tracked images in that frame.</p>
<pre class="idl highlight def"><c- b>enum</c-> <dfn class="dfn-paneled idl-code" data-dfn-type="enum" data-export id="enumdef-xrimagetrackingstate"><code><c- g>XRImageTrackingState</c-></code></dfn> {
<dfn class="dfn-paneled idl-code" data-dfn-for="XRImageTrackingState" data-dfn-type="enum-value" data-export id="dom-xrimagetrackingstate-untracked"><code><c- s>"untracked"</c-></code></dfn>,
<dfn class="dfn-paneled idl-code" data-dfn-for="XRImageTrackingState" data-dfn-type="enum-value" data-export id="dom-xrimagetrackingstate-tracked"><code><c- s>"tracked"</c-></code></dfn>,
<dfn class="dfn-paneled idl-code" data-dfn-for="XRImageTrackingState" data-dfn-type="enum-value" data-export id="dom-xrimagetrackingstate-emulated"><code><c- s>"emulated"</c-></code></dfn>,
};
[<a class="idl-code" data-link-type="extended-attribute" href="https://heycam.github.io/webidl/#SecureContext" id="ref-for-SecureContext"><c- g>SecureContext</c-></a>, <a class="idl-code" data-link-type="extended-attribute" href="https://heycam.github.io/webidl/#Exposed" id="ref-for-Exposed"><c- g>Exposed</c-></a>=<c- n>Window</c->]
<c- b>interface</c-> <dfn class="dfn-paneled idl-code" data-dfn-type="interface" data-export id="xrimagetrackingresult"><code><c- g>XRImageTrackingResult</c-></code></dfn> {
[<a class="idl-code" data-link-type="extended-attribute" href="https://heycam.github.io/webidl/#SameObject" id="ref-for-SameObject"><c- g>SameObject</c-></a>] <c- b>readonly</c-> <c- b>attribute</c-> <a data-link-type="idl-name" href="https://immersive-web.github.io/webxr/#xrspace" id="ref-for-xrspace②"><c- n>XRSpace</c-></a> <dfn class="dfn-paneled idl-code" data-dfn-for="XRImageTrackingResult" data-dfn-type="attribute" data-export data-readonly data-type="XRSpace" id="dom-xrimagetrackingresult-imagespace"><code><c- g>imageSpace</c-></code></dfn>;
<c- b>readonly</c-> <c- b>attribute</c-> <a class="idl-code" data-link-type="interface" href="https://heycam.github.io/webidl/#idl-unsigned-long" id="ref-for-idl-unsigned-long"><c- b>unsigned</c-> <c- b>long</c-></a> <dfn class="dfn-paneled idl-code" data-dfn-for="XRImageTrackingResult" data-dfn-type="attribute" data-export data-readonly data-type="unsigned long" id="dom-xrimagetrackingresult-index"><code><c- g>index</c-></code></dfn>;
<c- b>readonly</c-> <c- b>attribute</c-> <a data-link-type="idl-name" href="#enumdef-xrimagetrackingstate" id="ref-for-enumdef-xrimagetrackingstate①"><c- n>XRImageTrackingState</c-></a> <dfn class="dfn-paneled idl-code" data-dfn-for="XRImageTrackingResult" data-dfn-type="attribute" data-export data-readonly data-type="XRImageTrackingState" id="dom-xrimagetrackingresult-trackingstate"><code><c- g>trackingState</c-></code></dfn>;
<c- b>readonly</c-> <c- b>attribute</c-> <a class="idl-code" data-link-type="interface" href="https://heycam.github.io/webidl/#idl-float" id="ref-for-idl-float①"><c- b>float</c-></a> <dfn class="dfn-paneled idl-code" data-dfn-for="XRImageTrackingResult" data-dfn-type="attribute" data-export data-readonly data-type="float" id="dom-xrimagetrackingresult-measuredwidthinmeters"><code><c- g>measuredWidthInMeters</c-></code></dfn>;
};
<c- b>partial</c-> <c- b>interface</c-> <a class="idl-code" data-link-type="interface" href="https://immersive-web.github.io/webxr/#xrframe" id="ref-for-xrframe③"><c- g>XRFrame</c-></a> {
<a class="idl-code" data-link-type="interface" href="https://heycam.github.io/webidl/#idl-frozen-array" id="ref-for-idl-frozen-array①"><c- b>FrozenArray</c-></a><<a data-link-type="idl-name" href="#xrimagetrackingresult" id="ref-for-xrimagetrackingresult"><c- n>XRImageTrackingResult</c-></a>> <dfn class="dfn-paneled idl-code" data-dfn-for="XRFrame" data-dfn-type="method" data-export data-lt="getImageTrackingResults()" id="dom-xrframe-getimagetrackingresults"><code><c- g>getImageTrackingResults</c-></code></dfn>();
};
</pre>
<div class="algorithm" data-algorithm="obtain-image-tracking-results">
<p>In order to <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport id="obtain-image-tracking-results">obtain image tracking results</dfn> for an <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrframe" id="ref-for-xrframe④">XRFrame</a></code> <var>frame</var>, the user agent MUST run the following steps:</p>
<ol>
<li data-md>
<p>Let <var>session</var> be <var>frame</var>’s <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#dom-xrframe-session" id="ref-for-dom-xrframe-session">session</a></code> object.</p>
<li data-md>
<p>Let <var>results</var> be an empty list.</p>
<li data-md>
<p>For each <a data-link-type="dfn" href="#tracked-image" id="ref-for-tracked-image①①">tracked image</a> <var>image</var> in <var>session</var>’s <a data-link-type="dfn" href="#xrsession-list-of-tracked-images" id="ref-for-xrsession-list-of-tracked-images②">list of tracked images</a>:</p>
<ol>
<li data-md>
<p>If <var>image</var>’s <a data-link-type="dfn" href="#image-tracking-state" id="ref-for-image-tracking-state⑦">image tracking state</a> is <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-untracked" id="ref-for-dom-xrimagetrackingstate-untracked⑤">"untracked"</a></code>, continue to the next entry.</p>
<li data-md>
<p>Let <var>result</var> be an <code class="idl"><a data-link-type="idl" href="#xrimagetrackingresult" id="ref-for-xrimagetrackingresult①">XRImageTrackingResult</a></code></p>
<li data-md>
<p>Set <var>result</var>’s <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingresult-imagespace" id="ref-for-dom-xrimagetrackingresult-imagespace">imageSpace</a></code> to <var>image</var>’s <a data-link-type="dfn" href="#image-space" id="ref-for-image-space⑤">image space</a>.</p>
<li data-md>
<p>Set <var>result</var>’s <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingresult-index" id="ref-for-dom-xrimagetrackingresult-index">index</a></code> to <var>image</var>’s <a data-link-type="dfn" href="#image-index" id="ref-for-image-index①">image index</a></p>
<li data-md>
<p>Set <var>result</var>’s <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingresult-trackingstate" id="ref-for-dom-xrimagetrackingresult-trackingstate">trackingState</a></code> to <var>image</var>’s <a data-link-type="dfn" href="#image-tracking-state" id="ref-for-image-tracking-state⑧">image tracking state</a></p>
<li data-md>
<p>Set <var>result</var>’s <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingresult-measuredwidthinmeters" id="ref-for-dom-xrimagetrackingresult-measuredwidthinmeters">measuredWidthInMeters</a></code> to <var>image</var>’s <a data-link-type="dfn" href="#measured-width-in-meters" id="ref-for-measured-width-in-meters②">measured width in meters</a></p>
<li data-md>
<p>Append <var>result</var> to <var>results</var>.</p>
</ol>
<li data-md>
<p>Return a new <code class="idl"><a data-link-type="idl" href="https://heycam.github.io/webidl/#idl-frozen-array" id="ref-for-idl-frozen-array②">FrozenArray</a></code> containing the elements of <var>results</var>.</p>
</ol>
</div>
<p class="note" role="note"><span>NOTE:</span> The image tracking results only contains information about images with an <a data-link-type="dfn" href="#image-tracking-state" id="ref-for-image-tracking-state⑨">image tracking state</a> of <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-tracked" id="ref-for-dom-xrimagetrackingstate-tracked⑤">"tracked"</a></code> or <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-emulated" id="ref-for-dom-xrimagetrackingstate-emulated⑤">"emulated"</a></code>. <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingstate-untracked" id="ref-for-dom-xrimagetrackingstate-untracked⑥">"untracked"</a></code> images are omitted from the returned array. Applications can use the <code class="idl"><a data-link-type="idl" href="#dom-xrimagetrackingresult-index" id="ref-for-dom-xrimagetrackingresult-index①">index</a></code> value to associate each result with the underlying image.</p>
<p class="note" role="note"><span>NOTE:</span> Each tracked image can appear at most once in the tracking results. If multiple copies of the same image exist in the user’s environment, the device can choose an arbitrary instance to report a pose, and this choice can change for future <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrframe" id="ref-for-xrframe⑤">XRFrame</a></code>s.</p>
<h2 class="heading settled" data-level="4" id="security"><span class="secno">4. </span><span class="content">Security, Privacy, and Comfort Considerations</span><a class="self-link" href="#security"></a></h2>
<h3 class="heading settled" data-level="4.1" id="sensitive-information"><span class="secno">4.1. </span><span class="content">Sensitive Information</span><a class="self-link" href="#sensitive-information"></a></h3>
<p>In the context of image tracking, <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport id="sensitive-image-information">sensitive image information</dfn> includes, but is not limited to, information about the existence and position of specific real-world images in the user’s environment.</p>
<p class="note" role="note"><span>NOTE:</span> For example, a hostile application might try to detect large-denomination bank notes or other valuable items, specific book covers of titles that may be banned or restricted in certain jurisdictions, or other information that the user may be unwilling to share.</p>
<p class="note" role="note"><span>NOTE:</span> The goal of this API is to provide a reasonable amount of protection against disclosing such information, providing a tradeoff where it provides useful functionality with reduced risk compared to full camera access by the application. If an application were to ask for and receive full camera access, it could scan for all of this sensitive information, and there would be no way for the UA to mitigate the risks.</p>
<h3 class="heading settled" data-level="4.2" id="protected-functionality"><span class="secno">4.2. </span><span class="content">Protected functionality</span><a class="self-link" href="#protected-functionality"></a></h3>
<p>The <a data-link-type="dfn" href="#sensitive-image-information" id="ref-for-sensitive-image-information">sensitive image information</a> exposed by the API has the following threat profiles and necessary protections:</p>
<h4 class="heading settled" data-level="4.2.1" id="protect-image-presence"><span class="secno">4.2.1. </span><span class="content">Presence of images</span><a class="self-link" href="#protect-image-presence"></a></h4>
<div class="algorithm" data-algorithm="suitable-for-tracking">
<p>In order to check if a <a data-link-type="dfn" href="#tracked-image" id="ref-for-tracked-image①②">tracked image</a> <var>image</var> is <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport id="suitable-for-tracking">suitable for tracking</dfn> for an <code class="idl"><a data-link-type="idl" href="https://immersive-web.github.io/webxr/#xrframe" id="ref-for-xrframe⑥">XRFrame</a></code> <var>frame</var>, the user agent MUST run the following steps:</p>
<ol>
<li data-md>
<p>If <var>image</var> is considered unsuitable for tracking due to device or UA limitations, return <code>false</code>.</p>
<li data-md>
<p>If <var>image</var> is not currently being actively tracked by the XR device in <var>frame</var>, return <code>false</code>.</p>
<li data-md>
<p>If <var>image</var>’s current pose indicates it’s outside the user’s central field of view, return <code>false</code>.</p>
<li data-md>
<p>If <var>image</var>’s current pose indicates that the image’s angular size is too small for it to be prominently visible, return <code>false</code>.</p>
<li data-md>
<p>Return <code>true</code>.</p>
</ol>
</div>
<p>The goal of this algorithm is that the image MUST fill a substantial fraction of the user’s central field of view (for a head-mounted device) or camera view (for a handheld screen-based device) to be initially detected, and MUST have an angular area large enough to indicate an intent that the user is actively focusing on the image and is aware of it.</p>
<p>The UA MUST NOT initiate tracking for distant or small images, or images that only appear in peripheral vision.</p>
<p class="note" role="note"><span>NOTE:</span> The UA’s detailed criteria for initiating tracking are left to the UA’s discretion and depend on the device and tracking system.</p>
<p class="note" role="note"><span>NOTE:</span> For example, a smartphone AR system may require that the image fills at least 25% of the camera frame’s area for initial detection.</p>
<p class="note" role="note"><span>NOTE:</span> This limitation only applies to initial detection. Once an image has been determined to be suitable for tracking, the UA is free to continue reporting poses for that image even if it is distant or partially occluded.</p>
<h2 class="heading settled" data-level="5" id="ack"><span class="secno">5. </span><span class="content">Acknowledgements</span><a class="self-link" href="#ack"></a></h2>
<p>The following individuals have contributed to the design of the WebXR Marker Tracking specification:</p>
<ul>
<li data-md>
<li data-md>
<p>Alex Turner (Microsoft)</p>
</ul>
</main>
<div data-fill-with="conformance">
<h2 class="no-ref no-num heading settled" id="w3c-conformance"><span class="content">Conformance</span><a class="self-link" href="#w3c-conformance"></a></h2>
<h3 class="no-ref no-num heading settled" id="w3c-conventions"><span class="content">Document conventions</span><a class="self-link" href="#w3c-conventions"></a></h3>
<p>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. </p>
<p>All of the text of this specification is normative
except sections explicitly marked as non-normative, examples, and notes. <a data-link-type="biblio" href="#biblio-rfc2119">[RFC2119]</a> </p>
<p>Examples in this specification are introduced with the words “for example”
or are set apart from the normative text
with <code>class="example"</code>,
like this: </p>
<div class="example" id="w3c-example">
<a class="self-link" href="#w3c-example"></a>
<p>This is an example of an informative example. </p>
</div>
<p>Informative notes begin with the word “Note”
and are set apart from the normative text
with <code>class="note"</code>,
like this: </p>
<p class="note" role="note">Note, this is an informative note. </p>
<h3 class="no-ref no-num heading settled" id="w3c-conformant-algorithms"><span class="content">Conformant Algorithms</span><a class="self-link" href="#w3c-conformant-algorithms"></a></h3>
<p>Requirements phrased in the imperative as part of algorithms
(such as "strip any leading space characters"
or "return false and abort these steps")
are to be interpreted with the meaning of the key word
("must", "should", "may", etc)
used in introducing the algorithm. </p>
<p>Conformance requirements phrased as algorithms or specific steps
can be implemented in any manner,
so long as the end result is equivalent.
In particular, the algorithms defined in this specification
are intended to be easy to understand
and are not intended to be performant.
Implementers are encouraged to optimize. </p>
</div>
<script src="https://www.w3.org/scripts/TR/2016/fixup.js"></script>
<h2 class="no-num no-ref heading settled" id="index"><span class="content">Index</span><a class="self-link" href="#index"></a></h2>
<h3 class="no-num no-ref heading settled" id="index-defined-here"><span class="content">Terms defined by this specification</span><a class="self-link" href="#index-defined-here"></a></h3>
<ul class="index">
<li><a href="#dom-xrimagetrackingstate-emulated">"emulated"</a><span>, in §3.3</span>
<li><a href="#dom-xrsession-getimagetrackability">getImageTrackability()</a><span>, in §3.2</span>
<li><a href="#dom-xrframe-getimagetrackingresults">getImageTrackingResults()</a><span>, in §3.3</span>
<li><a href="#dom-xrtrackedimageinit-image">image</a><span>, in §3.1</span>
<li><a href="#image-index">image index</a><span>, in §2.1</span>
<li><a href="#image-space">image space</a><span>, in §2.1</span>
<li><a href="#dom-xrimagetrackingresult-imagespace">imageSpace</a><span>, in §3.3</span>