Implement command line interface for OpenOrienteering Mapper

[mfbehrens]

Fixes #2345

I am glad to receive some feedback.
Its been some time that I worked on QT projects 😅

Tiny Documentation

Documentation yet to come but this is a overview:

# Invoke cli using
Mapper --cli

# Export (pdf, image)
Mapper --cli export -i mymap.omap -o mymap.pdf
Mapper --cli export -i mymap.omap -o mymap.png
Mapper --cli export -i mymap.omap -o mymap.jpg

# You can also do cursed things (pdf with .jpg extension)
Mapper --cli export -i mymap.omap -o mymap.jpg --output-format pdf

# Export full map extend
Mapper --cli export -i mymap.omap -o mymap.pdf --full-map
Mapper --cli export -i mymap.omap -o mymap.png --full-map
Mapper --cli export -i mymap.omap -o mymap.jpg --full-map

# Convert between file formats
Mapper --cli convert -i mymap.omap -o mymap.xmap
Mapper --cli convert -i mymap.omap -o mymap.ocd --output-format OCD8
Mapper --cli convert -i mymap.omap -o mymap.gpx

> Mapper --cli --help
Usage: Mapper --cli <subcommand> [options]

Available subcommands:
  export   Export map to printable and image formats
  convert  Convert between orienteering map formats
  help     Show this help

> Mapper --cli export --help
Usage: Mapper --cli export [options]
Export map to printable and GIS formats

Options:
  -i, --input <path>    Input map file.
  -o, --output <path>   Output file path.
  --output-format <id>  Output format ID (e.g. pdf, png, OGR-export-DXF).
  --full-map            Export the full map extent instead of the saved print
                        area.
  --dpi <dpi>           Output resolution in DPI (default: 300).
  -h, --help            Displays help on commandline options.
  --help-all            Displays help including Qt specific options.

> Mapper --cli convert --help
Usage: Mapper --cli convert [options]
Convert between orienteering map formats

Options:
  -i, --input <path>    Input map file.
  -o, --output <path>   Output file path.
  --output-format <id>  Output format ID (e.g. XML, OCD, OCD12).
  -h, --help            Displays help on commandline options.
  --help-all            Displays help including Qt specific options.

Early documentation: OpenOrienteering/mapper-manual#79

Other cli designs

I was thinking about using another propsed format

Mapper mymap.omap --cli export -o mymap.pdf

This approach is ugly to handle.
What happens if the user provides multiple inputs at once?
What if you have a command does not receive an input file?
Or what if it needs to receive two?
What kind of backwards compatibility does this give you? (none because there is no previous cli)
Also a very unusual cli design in general, when you compare it to any other clis (at least on gnu/linux)

In the end it does not really change anything except for you not beeing able to open a file called --cli (however, I am not really sure if this was possible before and you should probably give your file a better name)

Known issues

• .omap and .xmap are currently not an output format but it is simply decided by their file extension what happens to the output
• I am not sure if anybody gets the difference between export and convert
  • probably something that has to be explained in the docs
  • Basicly export is printing and convert is save as
• missing documentation for output-format
• I am not happy how the command system is implemented
  • there is no help yet that lists the commands
• Mapper --cli convert --help displays wrong application name
• --cli has to be placed as first argument -> qt args like -platform cannot be set

Please squash merge this

[mfbehrens]

I also created a Docker/Podman Container for executing the mapper CLI.

It is just the Containerfile and the .containerignore so the two files could also be moved into the mapper repo if this is wanted.

Edit: fixed link

[dl3sdo]

@mfbehrens: the link to your repo at codeberg is not accessible, I assume due to missing access rights.

[mfbehrens]

Thank you. I fixed it. No I was apparently not able to copy a link 😆

[dg0yt]

From a cursory review, it looks very good to me.

With regard to #795, I would like to ensure that the default for PDF takes the graphics/printing path.

The initial post lists OGR-export-DXF, so there could be <prefix>PDF in order to choose the other path. (We should avoid the term OGR because it is somewhat obsolete in modern GDAL.)

I also wonder if CLI and GUI should really be one binary in Windows. We should at least test that it works sufficiently.

[Abbe98]

Any chance one can take this opportunity to make the Mapper binary lowercase by default?

[dg0yt]

Any chance one can take this opportunity to make the Mapper binary lowercase by default?

Documentation aside, this is an orthogonal concern and shouldn't be handled in this PR.

[mfbehrens]

With regard to #795, I would like to ensure that the default for PDF takes the graphics/printing path.

The initial post lists OGR-export-DXF, so there could be PDF in order to choose the other path. (We should avoid the term OGR because it is somewhat obsolete in modern GDAL.)

This is ensured by export and convert beeing two different commands.
Export properly prints out the map using QPrinter while convert tries to find and exporter using FileFormats.findFormat / FileFormats.findFormatForFilename.

I would consider any changes/bugs in these format_ids/FileTypeRegistry seperate from this pr.
Or did I not get your point?
As far as I understand you say that the FileTypes have to be modernized now that they are exposed closer to the user right?

I implemented a listFileFormats to better debug the formats and also for the users to have a source of documentation

I also wonder if CLI and GUI should really be one binary in Windows. We should at least test that it works sufficiently.

I think we can definitively disable the cli on android.

I just managed to download the ci build artefact and install them on my Windows 11 vm.
On Windows the cli itself works.
Unfortunately, the output text in the console does not get shown on Windows.
Does anybody know what the issue can be here?
Can anybody with a working Windows buildchain support me on this?

The reason I put the cli into the main binary is that there are no shared objects on Linux and macOS.
Thus, I triggered the cli from the main binary and that's the case on Windows as well to keep it consistent accros OSes.
Since the cli is just a wrapper around the core it shouldn't add that much to the main binary anyway or am I wrong about this?

Any chance one can take this opportunity to make the Mapper binary lowercase by default?

I think this would be a good thing (except for backwards compatibility).
However, when touching the name I would also suggest prepending an openorienteering-.
The binary sits right in my /usr/bin/ folder and mapper is imho a too generic name.

However, if this is a controversial change (renaming has never been controversion lol), please discuss it in a seperate issue.

[Abbe98]

Any chance one can take this opportunity to make the Mapper binary lowercase by default?

Documentation aside, this is an orthogonal concern and shouldn't be handled in this PR.

The reason I think it's relevant here is that making a switch like this is probably much harder once there is an established CLI.

[dg0yt]

This is ensured by export and convert beeing two different commands.

Sorry, I missed that 🤦

On Windows the cli itself works.
Unfortunately, the output text in the console does not get shown on Windows.
Does anybody know what the issue can be here?

This is what I expected. A windows executable is either a GUI app or a console program. The Mapper executable is a GUI app. This the WIN32 keyword in CMake's add_executable.