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:

``sh
npm i -g @zappar/zapworks-cli
`

Please note that the ZapWorks CLI is designed to work with Node.js version 18 or higher.

`sh
zapworks ...
`

Usage

$3

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:

`sh
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:

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

$3

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

`sh
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:

`sh
zapworks train myImage.png --curved
`

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

$3

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:

`sh
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:

`sh
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:

`sh
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:

`js
module.exports = {
//...
devServer: {
...
host: '0.0.0.0',
https: true
}
};
`

$3

You may clean .zpp files using:

`sh
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.