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
  • Serve the contents of a directory on your computer to let you preview on your computer or a device on your local network initialize new projects with templates for a variety of tools and technologies
  • Upload and publish 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

Once installed you can use the CLI on your command line like so:

zapworks ...


Usage

Training Image Files

Zappar's set of Universal 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.


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


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.

zapcode branded_zapcode i