- Docs
- Features
World tracking guide
World tracking needs no picture. The phone finds the floor or a table, a ring shows where the content will go, a tap places it, and it stays there while you walk around it. Sizes are in meters: a 20 cm box is 0.2.
It runs on WebXR, so it works in Chrome on an Android phone with ARCore. iPhone Safari has no WebXR: iPhone support needs the native App Clip, which comes later. Open the page examples/world/ on your phone: its panel tells you what the phone supports.
Try it: the A-Frame example and the Three.js example.
A-Frame
<script src="aframe.min.js"></script>
<script src="tempusxr-aframe.min.js"></script>
<script src="tempusxr-tracker-world.min.js"></script>
<a-scene tempusxr="tracker: world; anchors: spot">
<a-entity tempusxr-anchor="index: 0">
<a-box position="0 0.1 0" width="0.2" height="0.2" depth="0.2" color="#fecb02"></a-box>
</a-entity>
<a-entity tempusxr-reticle>
<a-ring rotation="-90 0 0" radius-inner="0.06" radius-outer="0.075"></a-ring>
</a-entity>
</a-scene>
A Start AR button appears: WebXR can only begin from a tap. anchors: spot is placed by a tap, anchors: spot:auto at the first surface found. tempusxr-reticle is the ring.
Three.js
import { create } from '@tempusxr/sdk-three';
import { WebXRProvider } from '@tempusxr/sdk-core';
import '@tempusxr/sdk-tracker-world';
const container = document.getElementById('ar');
const ar = create({ container, camera: new WebXRProvider({ domOverlay: container }) });
const world = await ar.use('world', { anchors: [{ id: 'spot', placement: 'tap' }] });
ar.attach(world.anchors[0], box); // the box appears when the anchor is placed
ar.attach(world.reticle, ring); // the ring follows the surface in front of the camera
button.onclick = () => ar.start(); // from a tap
The buttons of the overlay keep working in AR: the container is the DOM overlay of the AR session.
In a scene file
{ "tracker": { "kind": "world", "anchors": [{ "id": "spot", "placement": "tap" }] } }
A node says "anchor": "spot" as it does for an image. found fires when the anchor is placed, lost when tracking is lost, so the behaviors you already know work. loadScene draws the ring and shows a hint, and the Viewer opens such a scene. On a phone without AR, loadScene fails with the code unsupported and the Viewer says to open the link on an Android phone.
Walls
An anchor says which surface it wants: "surface": "floor" (the default), "wall" or "any". The ring shows only on the right kind of surface. On a wall, the content faces out of the wall and its top stays up, like a picture hung on it. Try a picture on the wall and a 3D component on the wall.
{ "tracker": { "kind": "world", "anchors": [{ "id": "wall", "placement": "tap", "surface": "wall" }] } }
A plain painted wall gives the phone almost nothing to lock onto, and Chrome on Android may report no vertical planes at all. So a wall is looked for in this order:
- The hit test, which also answers from feature points.
- The vertical planes the phone found.
- The depth sensor, on a phone that has one (
depth-sensing).loadSceneasks for it when a scene has a wall. - After about 4 seconds without a wall, a fallback: the hint becomes "Aim at the wall and tap to place it here", the ring floats in front of the camera, and two buttons move it closer or further. A tap places the content there, upright and facing you. The phone's tracking keeps it in place, but it is only as accurate as the distance you chose.
WorldTracker has wallFallback: false and depth: false to turn the last two off, and surfaceSource ('hit-test', 'plane', 'depth', 'manual' or 'none'), distance and setDistance(meters) to read and move the fallback ring. The Test console shows the source in its surface line and the sensor in its depth line.
Product viewer: viewer, hotspots and buttons
Add a viewer to the tracker and the person first sees the model in a 3D viewer (turn with a finger, zoom with two), with a View in AR button. A phone without AR keeps the viewer and shows a short note. Try it.
{
"tracker": { "kind": "world", "anchors": [{ "id": "spot" }], "viewer": { "background": "#e3e1e5" } },
"assets": [{ "id": "bike", "type": "model", "src": "bike.glb", "compression": ["draco"] }],
"nodes": [{
"id": "bike-node", "asset": "bike", "anchor": "spot", "size": 1.7,
"animation": { "clip": "Explosion View", "autoplay": false, "loop": false },
"hotspots": [{ "id": "brake", "position": [-0.36, 0.41, 0.1], "title": "Disc brake", "text": "200 mm" }]
}],
"controls": [{ "id": "explode", "type": "button", "label": "Explode" }],
"behaviors": [{ "on": "press", "control": "explode", "do": "toggle", "node": "bike-node" }]
}
sizeis the longest side of a model in meters, so it lands at real size whatever the units of the file.- Hotspots are numbered points with a title and a free text. A tap opens the label, a tap elsewhere closes it, and a point on the far side of the model hides. The position is in the space of the node, in meters when
sizeis set. They stay at their point: they do not follow a part that moves in an animation. - Buttons (
controls) sit above the camera. Apressbehavior runs when one is pressed, andtoggleplays an animation forward, then in reverse on the next press: the Explode button. - Models with Draco geometry say
"compression": ["draco"], and the page givesdecoders.dracoPath. - Hotspots also work on an image: try it with
poster.png.
While the phone looks for a surface
A phone sweeping over the floor shows how to move it, until a surface is found. Then a grid of LED dots spreads around the ring until something is placed. Give your own animation (a GIF or an animated WebP) with the scanHint option of loadScene.
Limits
- iPhone: in test, through Variant Launch. Safari has no WebXR, so a world page on an iPhone loads the launcher script, which opens it in an App Clip with ARKit behind the same WebXR calls. Only pages for world tracking do this (
examples/launch-ar.js); image tracking stays in Safari. The launcher lists hit tests, anchors and the DOM overlay, but not plane or depth detection, so a wall relies on the tap fallback, and photos and videos have no camera picture there. - Photo and video: in AR the browser draws the camera picture itself and the page cannot read it. When the phone grants WebXR camera access (Chrome on Android asks the person once), photos and videos hold the camera picture and the 3D together, read at 1280 pixels at most. If the phone refuses, they hold the 3D content only (a transparent photo). The reading costs speed: check the frame rate on your phone.
- Taps on content (the
tapbehavior) work in AR once everything is placed. Until then, the tap places the anchor. Hotspots and buttons never place it. - Tests: the browser tests use an emulated AR phone (IWER), the real phone test is yours.