From 314debe4fb9719dd2d63393327489ccb2bbc72d2 Mon Sep 17 00:00:00 2001 From: sfan5 Date: Mon, 7 Apr 2025 22:58:58 +0200 Subject: [PATCH] Make options documentation consistent also resolve confusion between Y axis on image vs. in-game --- README.rst | 41 ++++++++++++++++++++++++++--------------- minetestmapper.6 | 39 ++++++++++++++++++++------------------- src/mapper.cpp | 18 ++++++++++++------ 3 files changed, 58 insertions(+), 40 deletions(-) diff --git a/README.rst b/README.rst index f9d045e..a85081f 100644 --- a/README.rst +++ b/README.rst @@ -4,16 +4,18 @@ Minetest Mapper C++ .. image:: https://github.com/minetest/minetestmapper/workflows/build/badge.svg :target: https://github.com/minetest/minetestmapper/actions/workflows/build.yml -Minetestmapper generates an overview image from a Luanti map. +Minetestmapper generates a top-down overview image from a Luanti map. A port of minetestmapper.py to C++ from `the obsolete Python script `_. This version is both faster and provides more features. -Minetestmapper ships with a colors.txt file for Minetest Game, if you use a different game or have -many mods installed you should generate a matching colors.txt for better results. +Minetestmapper ships with a colors.txt file suitable for Minetest Game, +if you use a different game or have mods installed you should generate a +matching colors.txt for better results (colors will be missing otherwise). The `generate_colorstxt.py script -<./util/generate_colorstxt.py>`_ in the util folder exists for this purpose, detailed instructions can be found within. +<./util/generate_colorstxt.py>`_ in the util folder exists for this purpose, +detailed instructions can be found within. Requirements ------------ @@ -41,7 +43,8 @@ Minetestmapper for Windows can be downloaded `from the Releases section `_. After extracting the archive, it can be invoked from cmd.exe or PowerShell: -:: + +.. code-block:: dos cd C:\Users\yourname\Desktop\example\path minetestmapper.exe --help @@ -49,7 +52,7 @@ After extracting the archive, it can be invoked from cmd.exe or PowerShell: Compilation ----------- -:: +.. code-block:: bash cmake . -DENABLE_LEVELDB=1 make -j$(nproc) @@ -57,8 +60,8 @@ Compilation Usage ----- -`minetestmapper` has two mandatory paremeters, `-i` (input world path) -and `-o` (output image path). +``minetestmapper`` has two mandatory paremeters, ``-i`` (input world path) +and ``-o`` (output image path). :: @@ -90,7 +93,7 @@ draworigin: Draw origin indicator, ``--draworigin`` drawalpha: - Allow nodes to be drawn with transparency (e.g. water), ``--drawalpha`` + Allow nodes to be drawn with transparency (such as water), ``--drawalpha`` extent: Don't output any imagery, just print the extent of the full map, ``--extent`` @@ -101,11 +104,14 @@ noshading: noemptyimage: Don't output anything when the image would be empty, ``--noemptyimage`` +verbose: + Enable verbose log putput, ``--verbose`` + min-y: - Don't draw nodes below this y value, e.g. ``--min-y -25`` + Don't draw nodes below this Y value, e.g. ``--min-y -25`` max-y: - Don't draw nodes above this y value, e.g. ``--max-y 75`` + Don't draw nodes above this Y value, e.g. ``--max-y 75`` backend: Override auto-detected map backend; supported: *sqlite3*, *leveldb*, *redis*, *postgresql*, e.g. ``--backend leveldb`` @@ -113,8 +119,10 @@ backend: geometry: Limit area to specific geometry (*x:z+w+h* where x and z specify the lower left corner), e.g. ``--geometry -800:-800+1600+1600`` + The coordinates are specified with the same axes as in-game. The Z axis becomes Y when projected on the image. + zoom: - Apply zoom to drawn nodes by enlarging them to n*n squares, e.g. ``--zoom 4`` + Zoom the image by using more than one pixel per node, e.g. ``--zoom 4`` colors: Override auto-detected path to colors.txt, e.g. ``--colors ../world/mycolors.txt`` @@ -123,6 +131,9 @@ scales: Draw scales on specified image edges (letters *t b l r* meaning top, bottom, left and right), e.g. ``--scales tbr`` exhaustive: - | Select if database should be traversed exhaustively or using range queries, available: *never*, *y*, *full*, *auto* - | Defaults to *auto*. You shouldn't need to change this, but doing so can improve rendering times on large maps. - | For these optimizations to work it is important that you set ``min-y`` and ``max-y`` when you don't care about the world below e.g. -60 and above 1000 nodes. + Select if database should be traversed exhaustively or using range queries, available: *never*, *y*, *full*, *auto* + + Defaults to *auto*. You shouldn't need to change this, as minetestmapper tries to automatically picks the best option. + +dumpblock: + Instead of rendering anything try to load the block at the given position (*x,y,z*) and print its raw data as hexadecimal. diff --git a/minetestmapper.6 b/minetestmapper.6 index 0da5fb4..0e2cadc 100644 --- a/minetestmapper.6 +++ b/minetestmapper.6 @@ -9,9 +9,13 @@ minetestmapper \- generate an overview image of a Luanti map See additional optional parameters below. .SH DESCRIPTION .B minetestmapper -generates an overview image of a Luanti map. This is a port of -the original minetestmapper.py to C++, that is both faster and -provides more functionality than the obsolete Python script. +generates a top-down overview image of a Luanti map. +This is a port of the obsolete minetestmapper.py script to C++, +that is both faster and provides more features. + +Minetestmapper ships with a colors.txt file suitable for Minetest Game, +if you use a different game or have mods installed you should generate a +matching colors.txt for better results (colors will be missing otherwise). .SH MANDATORY PARAMETERS .TP @@ -28,7 +32,7 @@ Background color of image, e.g. "--bgcolor #ffffff" .TP .BR \-\-scalecolor " " \fIcolor\fR -Color of scale, e.g. "--scalecolor #000000" +Color of scale marks and text, e.g. "--scalecolor #000000" .TP .BR \-\-playercolor " " \fIcolor\fR @@ -40,11 +44,11 @@ Color of origin indicator, e.g. "--origincolor #ff0000" .TP .BR \-\-drawscale -Draw tick marks +Draw scale(s) with tick marks and numbers .TP .BR \-\-drawplayers -Draw player indicators +Draw player indicators with name .TP .BR \-\-draworigin @@ -52,7 +56,7 @@ Draw origin indicator .TP .BR \-\-drawalpha -Allow nodes to be drawn with transparency +Allow nodes to be drawn with transparency (such as water) .TP .BR \-\-noshading @@ -60,7 +64,7 @@ Don't draw shading on nodes .TP .BR \-\-noemptyimage -Don't output anything when the image would be empty. +Don't output anything when the image would be empty .TP .BR \-\-verbose @@ -68,19 +72,21 @@ Enable verbose log output. .TP .BR \-\-min-y " " \fInumber\fR -Don't draw nodes below this y value, e.g. "--min-y -25" +Don't draw nodes below this Y value, e.g. "--min-y -25" .TP .BR \-\-max-y " " \fInumber\fR -Don't draw nodes above this y value, e.g. "--max-y 75" +Don't draw nodes above this Y value, e.g. "--max-y 75" .TP .BR \-\-backend " " \fIbackend\fR -Use specific map backend; supported: \fIsqlite3\fP, \fIleveldb\fP, \fIredis\fP, \fIpostgresql\fP, e.g. "--backend leveldb" +Override auto-detected map backend; supported: \fIsqlite3\fP, \fIleveldb\fP, \fIredis\fP, \fIpostgresql\fP, e.g. "--backend leveldb" .TP .BR \-\-geometry " " \fIgeometry\fR -Limit area to specific geometry (\fIx:y+w+h\fP where x and y specify the lower left corner), e.g. "--geometry -800:-800+1600+1600" +Limit area to specific geometry (\fIx:z+w+h\fP where x and z specify the lower left corner), e.g. "--geometry -800:-800+1600+1600" + +The coordinates are specified with the same axes as in-game. The Z axis becomes Y when projected on the image. .TP .BR \-\-extent @@ -92,7 +98,7 @@ Zoom the image by using more than one pixel per node, e.g. "--zoom 4" .TP .BR \-\-colors " " \fIpath\fR -Forcefully set path to colors.txt file (autodetected otherwise), e.g. "--colors ../world/mycolors.txt" +Override auto-detected path to colors.txt, e.g. "--colors ../world/mycolors.txt" .TP .BR \-\-scales " " \fIedges\fR @@ -102,12 +108,7 @@ Draw scales on specified image edges (letters \fIt b l r\fP meaning top, bottom, .BR \-\-exhaustive " " \fImode\fR Select if database should be traversed exhaustively or using range queries, available: \fInever\fP, \fIy\fP, \fIfull\fP, \fIauto\fP -Defaults to \fIauto\fP. You shouldn't need to change this, but doing so can improve rendering times on large maps. -For these optimizations to work it is important that you set -.B min-y -and -.B max-y -when you don't care about the world below e.g. -60 and above 1000 nodes. +Defaults to \fIauto\fP. You shouldn't need to change this, as minetestmapper tries to automatically picks the best option. .TP .BR \-\-dumpblock " " \fIpos\fR diff --git a/src/mapper.cpp b/src/mapper.cpp index b3116a9..5d81337 100644 --- a/src/mapper.cpp +++ b/src/mapper.cpp @@ -15,9 +15,9 @@ static void usage() { - const std::pair options[] = { - {"-i/--input", ""}, - {"-o/--output", ""}, + static const std::pair options[] = { + {"-i/--input", ""}, + {"-o/--output", ""}, {"--bgcolor", ""}, {"--scalecolor", ""}, {"--playercolor", ""}, @@ -28,13 +28,14 @@ static void usage() {"--drawalpha", ""}, {"--noshading", ""}, {"--noemptyimage", ""}, + {"-v/--verbose", ""}, {"--min-y", ""}, {"--max-y", ""}, {"--backend", ""}, - {"--geometry", "x:y+w+h"}, + {"--geometry", "x:z+w+h"}, {"--extent", ""}, - {"--zoom", ""}, - {"--colors", ""}, + {"--zoom", ""}, + {"--colors", ""}, {"--scales", "[t][b][l][r]"}, {"--exhaustive", "never|y|full|auto"}, {"--dumpblock", "x,y,z"}, @@ -57,6 +58,11 @@ static void usage() for (auto s : backends) printf("%s ", s.c_str()); printf("\n"); +#ifdef _WIN32 + printf("See also the full documentation in README.rst\n"); +#else + printf("See also the full documentation in minetestmapper(6) or README.rst\n"); +#endif } static inline bool file_exists(const std::string &path)