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