Image Training

Zappar's image tracking augmented reality technology lets you attach 3D content to known images in a camera view. This library provides an API that takes a source image, e.g. a PNG or JPEG, and produces a 'target file' that can be used for tracking with Zappar's Universal AR SDKs.

If you'd like to train images as part of your day-to-day workflow, you might like to use our ZapWorks command line tool which provides this functionality out-of-the-box.

Starting Development

First step is to grab the package from NPM:

npm i @zappar/imagetraining

Next is to import it into your JavaScript or TypeScript files:

import { train } from "@zappar/imagetraining";

Finally, call the function to convert an input PNG or JPEG into a target file:

train(myFile, options).then(res => {
  // res is a Buffer containing the target file data
});

The training process is relatively intensive, so expect that it may take twenty or thirty seconds to complete.

The first argument is a node Buffer or a filesystem path of a PNG or JPEG file. The training process works best on images between around 200px and 500px in width and height. If an image larger than 500px (in either width or height) is provided, the function will automatically resize the image to fit 500px x 500px (or the maxWidth and maxHeight options).

Images smaller than 128px in either dimensions will not be processed, and the function will reject the returned promise.

The function returns a promise that resolves to a Buffer object, or is rejected if there's been an error processing the image.

The optional second parameter can be used to specify additional options:

Option	Description
`excludePreview`	The resulting target file has an embedded JPEG version of the original file for preview purposes. It is low-resolution and highly compressed, so typically only increases the target file size by ~5kb. Pass `true` for this option to avoid embedding the preview image.
`maxWidth and maxHeight`	The dimensions, in pixels, of the largest image size that will be processed by the function. If a larger image is provided, it will be resized to fit these values.

Example

This example loads a PNG file from the filesystem, trains it, then saves resulting target file. The example uses async/await.

import { train } from "@zappar/imagetraining";
import { promises as fs } from "fs";

async function perform() {
  let png = await fs.readFile("myfile.png");
  let target = await train(png);
  await fs.writeFile("myfile.zpt", target);
}