@zappar/imagetraining

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.

Installation

Standalone Download

Download the bundle from: https://libs.zappar.com/zappar-imagetraining/4.0.6/zappar-imagetraining.zip

Unzip into your web project and reference from your HTML like this:

<script src="zappar-imagetraining.js"></script>

CDN

Reference the zappar-imagetraining.js library from your HTML like this:

<script src="https://libs.zappar.com/zappar-imagetraining/4.0.6/zappar-imagetraining.js"></script>

The export is ZapparImageTraining.

NPM

Run the following NPM command inside your project directory:

npm install --save @zappar/imagetraining

Usage

Node Import

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

Browser Import

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

Training

Call the function to convert an input PNG or JPEG into a target file:

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

Note that 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, ArrayBuffer 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 optional second parameter can be used to specify additional options (see below).

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

Options

Option	Description	default
excludePreview	The resulting target file has an embedded JPEG version of the original file for preview purposes. It's low-resolution, and highly compressed and so typically only increases the target file size by ~5kb. Pass true for this option to avoid embedding the preview image.	false
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.	500
radius	The radius of the target, in target units (-1 to 1), this option should only be used for cylindrical targets.	0
topRadius and bottomRadius	The top and bottom radius of the target, only used if the target has non-matching top and bottom radii.	if provided, radius otherwise 0
sideLength	The side length of the target, in target units (-1 to 1).	0

Example

Node

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);
}

Browser

This example imports a PNG's url using webpack, trains it and downloads the resulting target file.

import { train } from "@zappar/imagetraining/web";
import myFile from "./myFile.png";

train(myFile).then((zpt) => {
  const a = document.createElement("a");
  a.href = URL.createObjectURL(new Blob([zpt], { type: "application/octet-stream" }));
  a.download = "target.zpt";
  document.body.appendChild(a);
  a.click();
});