Command line interface

📘

Cross-platform support

UgCS Mapper is a true cross-platform application: all its features are available under all supported platforms. Both Mapper CLI and GUI are equally supported on MS Windows, Ubuntu Linux, and Apple macOS in the same way.

🚧

CLI mode on Windows

To work in CLI mode under MS Windows use "mapper-cli.bat" instead of "mapper.bat".

A full list of commands and options is displayed when running the mapper executable without arguments.

Most of the commands operate on a workspace that stores all the processing states. The workspace is allocated in a filesystem directory which location is defined by the workspace_dir entry in the mapper configuration file (see comments in the default configuration file for details) and workspace ID. Workspace ID is an integer identifier that is either selected by a user or automatically allocated when creating a new workspace.

Alternatively, the workspace can be specified by a full filesystem path to its directory using -p (or --workspace-path) option. In the examples below -w can be replaced by -p everywhere.

--conf-path option can be used to specify a custom configuration file. By default used the one located in the default application data directory (somewhere in a user home directory, OS-dependent). On the first run, initial values are fetched from the file located in the installation directory.

One command should always be specified in the command line arguments among common and command-specific options. An order does not matter, options can precede or follow the command, or be interleaved.

Any fatal error causes the program to terminate with a non-zero exit code. Zero exit code indicates that the command was completed successfully, however it does not guarantee good quality of the result. Usually, commands have an option for saving extended processing statistics in a JSON file for a more detailed inspection of the resulting quality (--stats-file option).

Workflow example commands

📘

Image stitching

Basic image stitching workflow:
mapper dummy-workflow -d <input_directory> -o <output_directory> [--save-debug]

Input directory should contain images to process. The result will be generated in the specified output directory. Additional troubleshooting information is stored there if --save-debug option is specified.

Other commands

mapper create -w 1 --name test-wsp

Create a new workspace with the specified ID and name.

mapper import-images -w 1 -d /some/path/to/images

Import images from the local filesystem directory.

mapper assign-cameras -w 1

Assign camera profiles to all unbound images. The profiles are either taken from the built-in cameras DB or synthesized in a best-effort manner based on EXIF tags in the input images.

mapper detect-features -w 1

Detect features on all unprocessed images in the workspace.

mapper match-features -w 1

Match features for all unmatched images in the workspace.

mapper create-tracks -w 1

Create tracks from all matched features in the workspace.

mapper reconstruct -w 1

Reconstruct scene for all shots and tracks in the workspace.

mapper transform-images -w 1 --ect HISTOGRAM_EQUALIZATION

Apply images transformations (distortion correction and color transformations) to all aligned shots. --ect option specifies the exposure correction algorithm type.

mapper render-tiles -w 1

Render map tiles for all reconstructions in the workspace. All involved shots should have transformed images available.

mapper render-tiles -w 1 --tile-space terrain

Render terrain tiles for all reconstructions in the workspace.

mapper update-pyramid -w 1

Update a map tiles pyramid for all tiles in the workspace. Only outdated tiles are updated (the ones dependent on the tiles rewritten by a new render).

mapper update-pyramid -w 1 --tile-space terrain

Update a terrain tiles pyramid in the same way as for map tiles.

mapper export-mbtiles -w 1 -o /path/to/output/file.mbtiles

Export current map tiles pyramid into an MBTiles file.

mapper export-geotiff -w 1 -o /path/to/output/file.tiff

An export base level of the rendered map tiles pyramid into a GeoTIFF file.

mapper export-geotiff -w 1 -o /path/to/output/file.tiff --tile-space terrain

An export base level of the rendered terrain tiles pyramid into a GeoTIFF file.

See built-in command line help text for a description of all commands and options.