Anchors

Anchors are references to real-world features (like surfaces, points, or objects) detected by an AR/MR system. These anchors act as reference points that allow virtual objects to be placed and maintained in the 3D world relative to real-world coordinates. In AR/MR, objects need to stay in place even as the user moves around or changes perspective. Anchors ensure that virtual content remains fixed in relation to real-world surfaces or points, allowing it to stay in the correct position, scale, and orientation.

Once you enabled the anchor feature in Babylon.js, there are two ways to add an anchor:

addAnchorPointUsingHitTestResultAsync - it allows to add an anchor at hit-test position
addAnchorAtPositionAndRotationAsync - it allows to add an anchor in any position and rotation in the scene.

In this example, the first method is used to add the anchor(s). It begins with the Hit Test example, with the key difference being that we now track the hit test result. The loadAssetContainerAsync method loads the 3D model and stores it in a variable for later use. When a user perform a pinch gesture (or a click using the controller), the hit test result is passed to the addAnchorPointUsingHitTestResultAsync method, which handles setting the anchor. The onAnchorAddedObservable and onAnchorRemovedObservable are then responsible for attaching the 3D model to the anchor and managing its removal or disposal.

🥽📱

To experience the following example, an XR headset or a mobile with AR capabilities is required. Additionally, if you are using an XR headset, you may need to configure your environment (for instance, for Oculus Quest 3, refer to this guide for instructions on setting up your space).

const scene = useScene();
const xrExperience = useXrExperience();
const torusRef = useRef<Mesh>(null);
const cheetahRef = useRef<Mesh>(null);
 
useEffect(() => {
    let hitTest: IWebXRHitResult = undefined;
    const featuresManager = xrExperience.baseExperience.featuresManager;
    const xtTest = featuresManager.enableFeature(WebXRHitTest, 'latest') as WebXRHitTest;
    const xrAnchors = featuresManager.enableFeature(WebXRAnchorSystem, 'latest') as WebXRAnchorSystem;
 
    loadAssetContainerAsync('/meshes/cheetah/cheetah.obj', scene).then(container => {
        const cheetah = container.meshes[0] as Mesh;
        cheetah.rotation.y = Tools.ToRadians(140);
        cheetahRef.current = cheetah;
    });
 
    xtTest.onHitTestResultObservable.add(result => {
        const torus = torusRef.current!;
        if (result.length) {
            torus.isVisible = true;
            hitTest = result[0];
            result[0].transformationMatrix.decompose(torus.scaling, torus.rotationQuaternion as Quaternion, torus.position);
        } else {
            torus.isVisible = false;
            hitTest = undefined;
        }
    });
    xrAnchors.onAnchorAddedObservable.add(anchor => {
        const cheetah = cheetahRef.current!.clone(`cheetah-${anchor.id}`);
        const transformNode = new TransformNode('cheetah-parent');
        cheetah.parent = transformNode;
        anchor.attachedNode = transformNode;
    });
    xrAnchors.onAnchorRemovedObservable.add(anchor => {
        if (anchor.attachedNode) {
            anchor.attachedNode.dispose();
        }
    });
 
    scene.onPointerDown = () => {
        if (xtTest && hitTest && xrAnchors && cheetahRef.current && xrExperience.baseExperience.state === WebXRState.IN_XR) {
            xrAnchors.addAnchorPointUsingHitTestResultAsync(hitTest);
        }
    };
}, []);
 
// ...
<>
    <torus ref={torusRef} name='torus' options={{ diameter: 0.15, thickness: 0.05 }} isVisible={torusRef.current?.isVisible} rotationQuaternion={new Quaternion()}>
        <standardMaterial name='material' diffuseColor={Color3.FromHexString('#1e90ff')} />
    </torus>
</>

Video captured with Oculus Quest 3.

Learn More

For advanced use cases and customizations, please refer to Babylon.js documentation: https://doc.babylonjs.com/features/featuresDeepDive/webXR/webXRARFeatures/#anchors.

Hit Test Plane Detection