Image Tracking

Image tracking can detect and track a flat image in 3D space. This is great for building content that's augmented onto business cards, posters, magazine pages, etc.

Before setting up image tracking, you must first add or replace any existing camera you have in your scene. Find out more here.

To track content from a flat image in the camera view, use the zappar-image component:

<a-entity zappar-image="#target-file">
  <!-- PLACE CONTENT TO APPEAR ON THE IMAGE HERE -->
</a-entity>

The group provides a coordinate system that has its origin at the center of the image, with positive X axis to the right, the positive Y axis towards the top and the positive Z axis coming up out of the plane of the image. The scale of the coordinate system is such that a Y value of +1 corresponds to the top of the image, and a Y value of -1 corresponds to the bottom of the image. The X axis positions of the left and right edges of the target image therefore depend on the aspect ratio of the image.

Target File

ImageTrackers use a special 'target file' that's been generated from the source image you'd like to track.

You can generate them using the ZapWorks command-line utility like this:

zapworks train myImage.png

The resulting file can be loaded into an A-Frame as an asset and its ID passed as the parameter of the zappar-image component:

<a-assets>
    <a-asset-item id="target-file" src="myTarget.zpt"/>
</a-assets>
<a-entity zappar-image="#target-file">
  <!-- PLACE CONTENT TO APPEAR ON THE IMAGE HERE -->
</a-entity>

Events

The zappar-image component will emit the following events on the element it's attached to:

  • zappar-visible: emitted when the image appears in the camera view
  • zappar-notvisible: emitted when the image is no longer visible in the camera view

Here's an example of using these events:

<a-assets>
    <a-asset-item id="target-file" src="myTarget.zpt"/>
</a-assets>
<a-entity zappar-image="#target-file" id="my-image-tracker">
  <!-- PLACE CONTENT TO APPEAR ON THE IMAGE HERE -->
</a-entity>

<script>

let myImageTracker = document.getElementById("my-image-tracker");

myImageTracker.addEventListener("zappar-visible", () => {
  console.log("Image has become visible");
});

myImageTracker.addEventListener("zappar-notvisible", () => {
  console.log("Image is no longer visible");
});

</script>
zapcode branded_zapcode i