New OSM2World command line

OSM2World’s 0.5.0 release will include a major overhaul of its command line interface (CLI).

Despite the ability to use OSM2World as a graphical application, the CLI remains one of the most powerful ways to access its functionality and a popular choice among advanced users. Because OSM2World’s feature set, and therefore the number of available options, has grown significantly over the years, the new CLI will present a command-style interface alongside several related improvements.

Subcommands

The most noticeable change is the introduction of subcommands. Command-style interfaces appear increasingly popular with CLI tools. Git may be the most prominent user of the paradigm, but there are several other examples such as Go and Nominatim as well.

Command-style organization reflects the fact that there are a few distinct modes of using OSM2World, and while there are a few parameters which make sense for more than one of these modes, many are specific to just one.

As is customary, OSM2World’s CLI includes a help command which lets you learn about new options or remember rarely-used ones without having to leave the command line. Each subcommand comes with its own help message, which is formatted with ANSI colors and styles to make it a little easier to read. For example, this is an excerpt from the help page for the convert command – likely the most common way of using OSM2World from the command line, and the one with the largest number of available options:

Smart defaults

Besides the introduction of subcommands, working on the command line interface has also been an opportunity to make it smarter and more convenient to use. Wherever it makes sense, parameters are now optional and use sensible defaults.

This means that a simple command such as

convert -i in.osm -o out.png

will result in a PNG rendering with a suitable camera perspective and resolution:

This is possible because OSM2World assumes certain defaults and conventions. For example, it assumes that we want a PNG image because of the output file name, that the image should show the entire bounding box of the input file, that we want North to be at the top of the image, that we’re using OSM2World’s standard map style, and that we want a viewing angle and aspect ratio that provides a nice “isometric” 3D effect.

Of course, it is possible to overwrite all of these assumptions if you want. With extra parameters, the same input file could produce a very different visual result.

Autocompletion

To make OSM2World’s command line interface even more convenient, you can use command line completion in Bash or Zsh Unix shells. With this feature enabled, you only need to type the first few letters of a subcommand or option and hitting the TAB key will do the rest. This autocompletion is aware of all the available parameters and which values (such as file names or constants) makes sense for them.

Using this feature requires setting up an alias and sourcing the autocompletion script. Like the other improvements, implementation of this feature was a enabled by the picoci library.

Release schedule and backwards compatibility

The new CLI will be part of the 0.5.0 release – and you can already test it using the latest build available on the download page! However, old command lines will continue to work for a while. If you call OSM2World without a subcommand, it will fall back to the legacy CLI.