Tempusxr Français
Menu
  1. Docs
  2. 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:

  1. The hit test, which also answers from feature points.
  2. The vertical planes the phone found.
  3. The depth sensor, on a phone that has one (depth-sensing). loadScene asks for it when a scene has a wall.
  4. 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" }]
}

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