ZapWorks CLI
Zapworks provides a command line utility that helps you perform a range of augmented reality tasks, including:
- Training images for use as image targets with Zappar's Universal AR SDKs
- Serving the contents of a directory on your computer to let you preview on your computer or a device on your local network
- Initializing new projects with templates for a variety of tools and technologies
- Uploading and publishing web-based Universal AR projects through Zapworks.
Getting Started
To install and use the Zapworks CLI, first make sure you have Node.js installed, then run the following command in a terminal on your computer:
npm i -g @zappar/zapworks-cli
We also expose a beta version of this package that contains recent tweaks and updates. To install, run the following NPM command inside your project directory:
npm i -g @zappar/zapworks-cli@beta
The beta package will override the stable Zapworks CLI. Unless you require a specific command that is deployed to the beta version, we recommend using the stable Zapworks CLI to reduce any issues that might occur.
Once installed, you can use the CLI (both stable and beta version) on your command line like so:
zapworks ...
Training Image Targets
Flat image targets
Zappar's set of Universal AR SDKs let you track and attach content to images in 3D space. To do so, the SDKs need a file that contains an optimized description of the image, called a target file. To generate a target file from an image, use the CLI's train command:
zapworks train myImage.png
The CLI can train PNG or JPEG images, and they should be at least 300px in each dimension to be effective. The command will output a new file, in this case myImage.zpt, in the current directory. Alternatively, you can set a destination manually:
zapworks train myImage.png -o myFolder/target.zpt
For more information on creating effective tracking images, please refer to this article.
Curved image targets
In order for the image training algorithm to understand the curvature of your object, please specify exactly one of:
–radius=Xcm
–circumference=Xcm
For the algorithm to understand the real-world size of your target, specify exactly one of:
–input-height=Xcm
–input-width=Xcm
–dpi=X
For example:
zapworks train myImage.png --circumference=23cm --input-height=50cm
When one of input-height
, input-width
or dpi
are specified during training, the coordinate system of your anchor will be in units of meters. If no physical size is provided, the coordinate system will be +1 Y at the top of the image and -1 Y at the bottom of the image as usual.
Serving Directories
Due to browser restrictions, web pages that use the camera must be served over HTTPS. To help with local development of your web-based AR experiences, the CLI includes a tool that will serve a directory of your choice for access from your computer, or from a device on your local network.
To serve your current folder from a terminal, run the following command:
zapworks serve
This will start a server and provide a URL that you can use to access the current folder over HTTPS. To serve a different folder, you can run the following:
zapworks serve myDistFolder/
To access the site from other devices on your local network, e.g. your mobile phone, pass the --lan
parameter:
zapworks serve --lan
With this parameter, the CLI will output a link that should work for devices on your local network, and a QR code containing the same URL that you can scan on a mobile device to get up and running quickly.
If you're using webpack to bundle your project (which we do recommend), you may not need this tool. The webpack-dev-server
package can serve your content on your local network over HTTPS if you set the following options in your webpack configuration:
module.exports = {
//...
devServer: {
...
host: '0.0.0.0',
https: true
}
};
Iniatilizing a Bootstrap Project
The Zapworks CLI Tool allows you to quickly and easily create Bootstrap examples from your desktop. To begin, create a project folder and open a terminal within it . Then enter the following command to quickly create a bootstrap project for any of our tracking types within your SDK of choice:
zapworks init
Once you have entered and submitted the command, you will be asked to choose a 3D framework from a list of our web-based Universal AR SDKs. Use the arrow keys to navigate to a framework and press enter to select it.
Choose a 3D framework: (Use arrow keys)
ThreeJS
AFrame
BabylonJS
React-Three-Fiber
After selecting a framework, you will be asked if you would like to use a bundler. Use the arrow keys to navigate to a project type and press enter to select it.
Choose a bundler: (Use arrow keys)
Webpack
Standalone HTML
Although the Zapworks CLI currently provides Webpack as a bundler option, we also have examples of the Parcel bundler on our official GitHub page.
Once you have selected a bundler, you will be asked which tracking type you would like your project to be. Use the arrow keys to navigate to a tracking type and press enter to select it.
Choose a tracking type: (Use arrow keys)
Face Tracking
Image Tracking
Instant Tracking
When you have chosen a tracking type, you will be asked which language you would like to use. Use the arrow keys to navigate to a language and press enter to select it.
Choose a language: (Use arrow keys)
JavaScript
TypeScript
After following the above prompts, the Zapworks CLI will automatically create a bootstrap project of your choice inside your project folder.
Clean Zapworks Studio Symbols
You may clean .zpp
files using:
$ zapworks zppclean mySymbol.zpp
This command takes a ZPP
file (the file format of Zapworks Studio) and produces a new file without unnecessary or redundant data.