@zappar/zapworks-cli

ZapWorks CLI

This is 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 just 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 with thusly:

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. You can sent the output to a different location if you like:

zapworks train myImage.png -o myFolder/target.zpt

Cylindrical targets

You may train images for cylindrical targets. To do so, provide the radius of the cylinder:

zapworks train myImage.png --radius 55mm
zapworks train myImage.png --radius 500px --dpi 110

The following units are accepted: target, mm, cm, m, in, px.

To wrap the image all the way around, simply pass in --curved when training:

zapworks train myImage.png --curved

You might like to check out the following ZapWorks Docs article: What Makes a Good Tracking Image?

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

That will start a server and give you URL that you can use to access the current folder over HTTPS. If you'd like to serve a different folder, that's easy too:

zapworks serve myDistFolder/

If you'd like 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 may like to scan on a mobile device to get up and running quickly.

Note - 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.