diff --git a/README.rst b/README.rst index bf19166..2247de1 100644 --- a/README.rst +++ b/README.rst @@ -10,9 +10,9 @@ Quick links (functional on github. Elsewhere possibly not): :User manual: ``_ :Changelog: ``_ :Building: ``_ -:Github: ``_ -:Submitting bugs: ``_ -:Binary downloads: ``_ +:Github: ``_ +:Submitting bugs: ``_ +:Binary downloads: ``_ :Generating colors.txt: ``_ Features (short list) @@ -53,16 +53,16 @@ Windows ------- Check the download page to obtain a compiled version: -``_ +``_ Or check the building instructions for compiling using MSVC: -``_. +``_. Install Dependencies -------------------- Make sure development versions of the following packages are installed. -For more detailed instructions, see ``_. +For more detailed instructions, see ``_. **Libraries:** @@ -145,6 +145,6 @@ Manual ====== For more elaborate compilation and installation documentation, please consult -the build manual: ``_. +the build manual: ``_. -For more elaborate usage instruction, please consult the user manual: ``_. +For more elaborate usage instruction, please consult the user manual: ``_. diff --git a/docs/build-instructions.rst b/docs/build-instructions.rst new file mode 100644 index 0000000..affa4b3 --- /dev/null +++ b/docs/build-instructions.rst @@ -0,0 +1,400 @@ +Minetest Mapper Build Instructions +################################## + +Minetestmapper can be built on posix (Linux, \*BSD, ...), OSX and Windows +platforms. + +Not all platforms receive the same amount of testing: + +* Gcc and clang builds on Linux are frequently tested. +* The BSD family should also give little trouble. It is not tested that I know of. +* MSVC on Windows is tested. +* Windows building using MinGW is tested intermittently and should work. +* Building on OSX has not been tested recently and may not work. + +Please let me know how you fared on your platform (when you encounter problems, +but also when you're successful - so I can update this text with the latest +information). + +.. Contents:: :depth: 2 + +Requirements +============ + +Libraries +--------- + +* zlib +* libgd +* sqlite3 (optional - enabled by default, set ENABLE_SQLITE3=0 in CMake to disable) +* postgresql (optional, set ENABLE_POSTGRESQL=1 in CMake to enable postgresql support) +* leveldb (optional, set ENABLE_LEVELDB=1 in CMake to enable leveldb support) +* hiredis (optional, set ENABLE_REDIS=1 in CMake to enable redis support) + +At least one of ``sqlite3``, ``postgresql``, ``leveldb`` and ``hiredis`` is required. +Check the minetest worlds that will be mapped to know which ones should be included. + +Not all database backend libraries may be obtainable for all platforms (in particular +for Windows). + +The current build scripts for MSVC on windows support the SQLite3 and LevelDB backends out +of the box. Compiling with Redis or PostgreSQL support will require some extra work. + +Build Environment +----------------- + +* C++ compiler suite (clang or gcc (including mingw); msvc on Windows) +* cmake (not for msvc) +* make (not for msvc) + +Documentation +------------- + +If converting the documentation to HTML, or another format is desired: + +* python-docutils + +Packaging +--------- + +If creation of installation packages is desired: + +* fakeroot (for a deb package) +* rpm-build (for an rpm package) + +Install Dependencies +==================== + +Debian and Derivatives +---------------------- + +Install a compiler if not yet installed. Either gcc/g++: + +:: + + apt-get install make cmake cmake-curses-gui g++ + +Or clang: + +:: + + apt-get install make cmake cmake-curses-gui clang + +To convert the manual to HTML (if desired), install ``python-docutils`` + +:: + + apt-get install python-docutils + +In order to make a ``.deb`` package (if desired), install the required tools: + +:: + + apt-get install fakeroot + +Finally install the minetestmapper dependencies. At least one of ``libsqlite3-dev``, +``libpq-dev``, ``libleveldb-dev`` and ``libhiredis-dev`` is required. + +:: + + apt-get install zlib1g-dev libgd-dev libsqlite3-dev libpq-dev libleveldb-dev libhiredis-dev + +Fedora and Derivatives +---------------------- + +Install a compiler if not yet installed. Either gcc/g++: + +:: + + yum install make cmake gcc-c++ + +Or clang: + +:: + + yum install make cmake clang + +To convert the manual to HTML (if desired), install ``python-docutils`` + +:: + + yum install python-docutils + +In order to make an ``.rpm`` package (if desired), install the required tools: + +:: + + yum install rpm-build + +Finally install the minetestmapper dependencies. At least one of ``libsqlite3x-devel``, +``postgresql-devel``, ``leveldb-devel`` and ``hiredis-devel`` is required. + +:: + + yum install zlib-devel gd-devel libsqlite3x-devel postgresql-devel leveldb-devel hiredis-devel + +Ubuntu +------ +See `Debian and Derivatives`_ + +Linux Mint +---------- +See `Debian and Derivatives`_ + +Windows (MinGW) +--------------- + +You're probably in for a lot of work, downloading software, and +probably compiling at least some of the direct and indirect dependencies. +At the moment, regrettably, detailed instructions are not available. + +Windows (MSVC) +-------------- + +The following must be installed to successfully compile minetestmapper using MSVC: + +* Visual Studio 2015 or 2013 (lower may not work). VS Community can be obtained here: + https://www.visualstudio.com/ +* A precompiled version of the gd library. A suitable version can be downloaded from + https://github.com/Rogier-5/minetest-mapper-cpp/wiki/Downloads#the-gd-library-for-compiling-minetestmapper-with-msvc + + Alternatively, the gd sources can be downloaded from https://github.com/libgd/libgd. + They must be compiled using the same version of zlib that will be used when compiling + minetestmapper. + + Version 2.2.1 of gd is verified to work, but any version 2.2.x should also work. + And presumably any version 2.x later than 2.2 should work as well. + +All other required dependencies will be downloaded automatically by MSVC. + + +Other +----- + +At this moment, no specific instructions are available for other platforms. +Feel free to contribute... + +Compilation +=========== + +Linux / BSD / ... +----------------- + +Plain: + +:: + + cmake . + make + +With levelDB and Redis support: + +:: + + cmake -DENABLE_LEVELDB=true -DENABLE_REDIS=true . + make + +Create native installation package(s): + +:: + + cmake -DCMAKE_INSTALL_PREFIX=/usr -DCREATE_FLAT_PACKAGE=False + cpack + +See `CMake Variables`_ for more CMake options. + +Windows (MinGW) +--------------- + +Unfortunately, at the moment no instructions are available for Windows building using MinGW. + +Windows (MSVC) +-------------- + +Setting up the IDE +.................. + +1. Open ``minetestmapper.sln`` or ``MSVC\mintestmapper.vcxproj`` with Visual Studio. +2. Configure the gd libary: + 1. Open projectsettings `ALT+F7`. + 2. Select `All Configurations` and `All Platforms`. + 3. Click `C/C++` -> `additional include directories` and enter the path to the include directory of libGD. + 4. Click `Apply` + 5. Select a configuration (``Debug|Release``) and a platform (``x86|x64``) + 6. Click `Linker` --> `additional libary directories` Enter the path to libgd that fits to your configuration and platform. + + Do this step for all configurations and platforms you want to use. + + WARNING: You will get a linker error if you select a version of libgd that does not fit to your configuration and platform. + +Building Minetestmapper +....................... + +With everything set up, Minetestmapper can be built. + +Debugging Minetestmapper +........................ + +1. In projectsettings (`ALT+F7`) click `Debugging`. +2. Specify the Arguments in `Command arguments`. +3. Every time you launch the debugger, minetstmapper will be executed with those arguments. + +OSX +--- + +Probably quite similar to Linux, BSD, etc. Unfortunately no detailed instructions +are available. + +CMake Variables +--------------- + +ENABLE_SQLITE3: + Whether to enable sqlite3 backend support (on by default) + +ENABLE_POSTGRESQL: + Whether to enable postresql backend support (off by default) + +ENABLE_LEVELDB: + Whether to enable leveldb backend support (off by default) + +ENABLE_REDIS: + Whether to enable redis backend support (off by default) + +ENABLE_ALL_DATABASES: + Whether to enable support for all backends (off by default) + +CMAKE_BUILD_TYPE: + Type of build: 'Release' or 'Debug'. Defaults to 'Release'. + +CREATE_FLAT_PACKAGE: + Whether to create a .tar.gz package suitable for installation in a user's private + directory. + The archive will unpack into a single directory, with the mapper's files inside + (this is the default). + + If off, ``.tar.gz``, ``.deb`` and/or ``.rpm`` packages suitable for system-wide installation + will be created if possible. The ``tar.gz`` package will unpack into a directory hierarchy. + + For creation of ``.deb`` and ``.rpm packages``, CMAKE_INSTALL_PREFIX must be '/usr'. + + For ``.deb`` package creation, dpkg and fakeroot are required. + + For ``.rpm`` package creation, rpmbuild is required. + +PACKAGING_VERSION: + The version number of the packaging itself. It is appended to the software version + number when packaging. + + This number should normally be set to '1', but it should be increased when + a package has been installed or distributed, and a newer package is created from + from the same sources (i.e. from the same git commit). + + This can happen for instance, if a problem was caused by the packaging itself, + or if a bug in a library was fixed, and minetestmapper needs to be recompiled + to incorporate that fix. + +CMAKE_INSTALL_PREFIX: + The install location. Should probably be ``/usr`` or ``/usr/local`` on Linux and BSD variants. + +ARCHIVE_PACKAGE_NAME: + Name of the ``.zip`` or ``.tar.gz`` package (without extension). This will also be + the name of the directory into which the archive unpacks. + + Defaults to ``minetestmapper--`` + + The names of ``.deb`` and ``.rpm`` packages are *not* affected by this variable. + +REQUIRE_HTML_DOCUMENTATION: + Whether HTML documentation must be generated. If enabled, and python-docutils is not + installed, building will fail. + + By default, HTML documentation will be generated if python-docutils is found, else + it will not be generated. + + See also the note below. + +DISABLE_HTML_DOCUMENTATION: + Whether to skip generation of HTML documentation, even if python-docutils could be + found. + + Note that if HTML documentation is not generated at build time, it will also not + be included in the packages, even if python-docutils is in fact installed and + even if the converted documentation is available (e.g. because it was generated + manually). + + See also the note below. + +HTML Documentation note: + If both REQUIRE_HTML_DOCUMENTATION and DISABLE_HTML_DOCUMENTATION are disabled, + then the question of whether HTML documentation will be generated depends on + whether python-docutils is installed. If installed, then henceforth HTML + documentation will be generated. If not installed, then it will not be generated. + + As long as REQUIRE_HTML_DOCUMENTATION and DISABLE_HTML_DOCUMENTATION are both + disabled then, for consistency, once python-docutils has been found to be installed + and the decision has been made to generate HTML documentation, this decision persists. + If subsequently python-docutils is deinstalled, or can no longer be found, later + builds will fail, until the situation has been fixed. This can be done in several + ways: + + - (Obviously:) Reinstalling python-docutils, or making sure it can be found. + + - Enabling both REQUIRE_HTML_DOCUMENTATION and DISABLE_HTML_DOCUMENTATION. As this + is not a sensible combination, the build system will disable both, and it will + then also reevaluate the persistent decision to generate HTML documentation. + + - Setting DISABLE_HTML_DOCUMENTATION to True to permanently disable generation of + HTML documentation. + + - Setting DISABLE_HTML_DOCUMENTATION to True, running cmake, and then setting it + back to false. This will disable HTML generation until python-docutils is + available again. + +Converting the Documentation +============================ + +Using python-docutils, the manual can be converted to a variety of formats. + +HTML +---- + +By default, documentation is converted to HTML when building minetestmapper, provided +python-docutils is installed. + +If automatic documentation conversion at build time is disabled, but python-docutils +is installed, non-automatic conversion is still possible. Either using make: + +:: + + make hmtldoc + +Or by manually invoking ``rst2html`` + +:: + + cd doc + rst2html manual.rst > manual.html + +Unix manpage +------------ + +Conversion to unix man format has acceptable, but not perfect results: + +:: + + cd doc + rst2man manual.rst > minetestmapper.1 + +PDF +--- + +The results of using ``rst2pdf`` (which, as an aside, is not part of python-docutils, +and needs to be obtained separately) to convert to PDF directly are not good: random +images are scaled down, some even to almost invisibly small. If PDF is desired, a +good option is to open the HTML file in a webbrowser, and print it to PDF. + +Other +----- + +Other conversions are possible using python-docutils. If you tried any, and +they warrant specific instructions, feel free to contribute. diff --git a/docs/features.rst b/docs/features.rst new file mode 100644 index 0000000..a4f8006 --- /dev/null +++ b/docs/features.rst @@ -0,0 +1,121 @@ +Minetest Mapper Features +######################## + +Minetestmapper generates maps of minetest and freeminer worlds. + +Major Features +============== +* Support for both minetest and freeminer +* Support for sqlite3, postgresql, leveldb and redis map databases +* Generate a subsection of the map, or a full map + (but the size of generated images is limited - see + 'Known Problems' below) +* Generate regular maps or height-maps +* All colors for regular or height maps are configurable +* Draw player positions +* Draw different geometric figures, or text on the map +* Draw the map at a reduced scale. E.g. 1:4 (max: 1:16). +* Draw a scale on the left and/or top side of the map, + and/or a height scale (for height maps) on the bottom. +* Optionally draw some nodes transparently (e.g. water) +* Includes a user manual + +Build Features +============== +* Supports both the gcc and clang compiler suites +* Supports MSVC building on Windows (with SQLite3 and LevelDB) + + * With automatic downloading of all but one of the required libraries. + +* Build rpm, deb and/or tar.gz installation + packages. Or simply type 'make install'. + +Minor Features +============== +* Specify a number colors symbolically ('red', ...) +* Draw a grid on the map +* Show a progress indicator +* Draw shades to accentuate height differences (on by default) +* Report actual world dimensions in all directions, as + well which part of it will be in the map. +* optionally, avoid reading the block list from the database + (may be more efficient when mapping small parts of the *existing* world) + +Differences From Stock Minetestmapper +===================================== +* Support for the new freeminer database format +* Support for the unofficial postgresql backend. +* Ability to draw height-maps +* Different methods for drawing transparent blocks + (more than transparency on and off) +* Different colors can be specified for nodes, in the + same colors file, depending on whether transparency + is enabled or not. +* Abiliy to draw different geometric figures, or text on the map +* Map dimensions can be specified in different ways: + + - using two corners + - using a corner and the size + - using the center and the size + +* Pixel or block granularity for the dimensions + (stock minetestmapper always uses block granularity: it rounds + all dimensions to the next multiple of 16). +* Colors files are automatically searched for in the world + directory, or in system directories +* Colors files can include others, so that just a few colors can + be redefined, and the system colors file used for the others. +* The map can be drawn at a reduced scale (1:1 - 1:16). + This means that a full world map can now be generated. +* A grid can be drawn on the map. +* A number of symbolic colors ('red', ...) are available on the + command-line. +* The scale can be enabled on the left and top side individually +* Major and minor (tick) intervals are configurable for the scale +* Block numbers are shown on the scale as well +* Optionally, avoid reading the block list from the database + (dramatically speeds up generating maps of small parts of large worlds) +* Compiles using MSVC on windows. + +In addition a number bugs have been fixed. As bugs are also getting +fixed in the stock version of minetestmapper, no accurate list +can be given. + +Known Problems +============== + +* It is currently not possible to generate huge maps. + + On 32-bit systems, the map size is limited by the maximum amount of memory + (or really: the size of the address space). + this means in practise that maps larger than about 24100x24100 (determined + experimentally - YMMV) can't be generated. Note, that even if a larger + /could/ be generated, most 32-bit applications would still not be able to + display it for the same reason. + + On 64-bit systems, the libgd image library unfortunately limits the map + size to approximately 2147483648 pixels, e.g. approximately 46300x46300. + + If a full map is required for a world that is too large, there are currently + two options: + + - Generate the map in sections, and use another application to paste them + together. + - Generate a 1:2 or 1:4 scaled version of the map, if the reduced level of + detail is acceptable. + + A third alternative, is of course to support the libgd project in removing + the current restrictions on image size. + +* On scaled maps, the colors of some pixels may be imperceptibly different on + different systems. + + The difference would be at most 1/256 per color. + (e.g., a pixel with color ``#4c92a1`` on one system, might have color + ``#4x91a1`` on another system) + + The cause of this difference has not been determined yet. + +* The drawing library supports ISO8859-2 fonts only. Characters in text and + player names that cannot be converted to the ISO8859-2 character set will + not be rendered correctly. diff --git a/docs/images/alpha-average.png b/docs/images/alpha-average.png new file mode 100644 index 0000000..856e106 Binary files /dev/null and b/docs/images/alpha-average.png differ diff --git a/docs/images/alpha-cumulative-darken.png b/docs/images/alpha-cumulative-darken.png new file mode 100644 index 0000000..3b3418b Binary files /dev/null and b/docs/images/alpha-cumulative-darken.png differ diff --git a/docs/images/alpha-cumulative.png b/docs/images/alpha-cumulative.png new file mode 100644 index 0000000..f8b78d8 Binary files /dev/null and b/docs/images/alpha-cumulative.png differ diff --git a/docs/images/background-blueish.png b/docs/images/background-blueish.png new file mode 100644 index 0000000..d5e9b33 Binary files /dev/null and b/docs/images/background-blueish.png differ diff --git a/docs/images/background-white.png b/docs/images/background-white.png new file mode 100644 index 0000000..763b268 Binary files /dev/null and b/docs/images/background-white.png differ diff --git a/docs/images/blockcolor-yellowish.png b/docs/images/blockcolor-yellowish.png new file mode 100644 index 0000000..4139ded Binary files /dev/null and b/docs/images/blockcolor-yellowish.png differ diff --git a/docs/images/default-0.0.png b/docs/images/default-0.0.png new file mode 100644 index 0000000..6d401a6 Binary files /dev/null and b/docs/images/default-0.0.png differ diff --git a/docs/images/drawair-detail-0.png b/docs/images/drawair-detail-0.png new file mode 100644 index 0000000..43f4b7d Binary files /dev/null and b/docs/images/drawair-detail-0.png differ diff --git a/docs/images/drawair-detail.png b/docs/images/drawair-detail.png new file mode 100644 index 0000000..35b9651 Binary files /dev/null and b/docs/images/drawair-detail.png differ diff --git a/docs/images/drawair.png b/docs/images/drawair.png new file mode 100644 index 0000000..16f0c6c Binary files /dev/null and b/docs/images/drawair.png differ diff --git a/docs/images/drawarrow.png b/docs/images/drawarrow.png new file mode 100644 index 0000000..4f60478 Binary files /dev/null and b/docs/images/drawarrow.png differ diff --git a/docs/images/drawcircle.png b/docs/images/drawcircle.png new file mode 100644 index 0000000..1192047 Binary files /dev/null and b/docs/images/drawcircle.png differ diff --git a/docs/images/drawline.png b/docs/images/drawline.png new file mode 100644 index 0000000..ae7801e Binary files /dev/null and b/docs/images/drawline.png differ diff --git a/docs/images/draworigin.png b/docs/images/draworigin.png new file mode 100644 index 0000000..0aa6a3d Binary files /dev/null and b/docs/images/draworigin.png differ diff --git a/docs/images/drawpoint.png b/docs/images/drawpoint.png new file mode 100644 index 0000000..9240c68 Binary files /dev/null and b/docs/images/drawpoint.png differ diff --git a/docs/images/drawrectangle.png b/docs/images/drawrectangle.png new file mode 100644 index 0000000..691868b Binary files /dev/null and b/docs/images/drawrectangle.png differ diff --git a/docs/images/drawscale-both.png b/docs/images/drawscale-both.png new file mode 100644 index 0000000..cd333c4 Binary files /dev/null and b/docs/images/drawscale-both.png differ diff --git a/docs/images/drawscale-left.png b/docs/images/drawscale-left.png new file mode 100644 index 0000000..5a133b1 Binary files /dev/null and b/docs/images/drawscale-left.png differ diff --git a/docs/images/drawscale-top.png b/docs/images/drawscale-top.png new file mode 100644 index 0000000..7a330dc Binary files /dev/null and b/docs/images/drawscale-top.png differ diff --git a/docs/images/drawtext.png b/docs/images/drawtext.png new file mode 100644 index 0000000..39f8139 Binary files /dev/null and b/docs/images/drawtext.png differ diff --git a/docs/images/geometrymode-block.png b/docs/images/geometrymode-block.png new file mode 100644 index 0000000..fcebda7 Binary files /dev/null and b/docs/images/geometrymode-block.png differ diff --git a/docs/images/geometrymode-shrink.png b/docs/images/geometrymode-shrink.png new file mode 100644 index 0000000..bba6eb1 Binary files /dev/null and b/docs/images/geometrymode-shrink.png differ diff --git a/docs/images/geometrymode.png b/docs/images/geometrymode.png new file mode 100644 index 0000000..88a6b3a Binary files /dev/null and b/docs/images/geometrymode.png differ diff --git a/docs/images/gui-1.png b/docs/images/gui-1.png new file mode 100644 index 0000000..d1f3a6e Binary files /dev/null and b/docs/images/gui-1.png differ diff --git a/docs/images/gui-2.png b/docs/images/gui-2.png new file mode 100644 index 0000000..a1f8b7f Binary files /dev/null and b/docs/images/gui-2.png differ diff --git a/docs/images/heightmap-color.png b/docs/images/heightmap-color.png new file mode 100644 index 0000000..b20a41f Binary files /dev/null and b/docs/images/heightmap-color.png differ diff --git a/docs/images/heightmap-grey.png b/docs/images/heightmap-grey.png new file mode 100644 index 0000000..f1ed2b8 Binary files /dev/null and b/docs/images/heightmap-grey.png differ diff --git a/docs/images/heightmap-scale-interval.png b/docs/images/heightmap-scale-interval.png new file mode 100644 index 0000000..8ccfd8f Binary files /dev/null and b/docs/images/heightmap-scale-interval.png differ diff --git a/docs/images/heightmap-scale.png b/docs/images/heightmap-scale.png new file mode 100644 index 0000000..1e10cb8 Binary files /dev/null and b/docs/images/heightmap-scale.png differ diff --git a/docs/images/heightmap-yscale.png b/docs/images/heightmap-yscale.png new file mode 100644 index 0000000..aace48b Binary files /dev/null and b/docs/images/heightmap-yscale.png differ diff --git a/docs/images/noshading.png b/docs/images/noshading.png new file mode 100644 index 0000000..a6ced5e Binary files /dev/null and b/docs/images/noshading.png differ diff --git a/docs/images/players.png b/docs/images/players.png new file mode 100644 index 0000000..340a89b Binary files /dev/null and b/docs/images/players.png differ diff --git a/docs/images/scalefactor-2.png b/docs/images/scalefactor-2.png new file mode 100644 index 0000000..9760728 Binary files /dev/null and b/docs/images/scalefactor-2.png differ diff --git a/docs/images/scalefactor-4.png b/docs/images/scalefactor-4.png new file mode 100644 index 0000000..e47b2ba Binary files /dev/null and b/docs/images/scalefactor-4.png differ diff --git a/docs/images/sidescale-interval.png b/docs/images/sidescale-interval.png new file mode 100644 index 0000000..053753f Binary files /dev/null and b/docs/images/sidescale-interval.png differ diff --git a/docs/images/tiles-16-centered.png b/docs/images/tiles-16-centered.png new file mode 100644 index 0000000..e7a7ab3 Binary files /dev/null and b/docs/images/tiles-16-centered.png differ diff --git a/docs/images/tiles-16.png b/docs/images/tiles-16.png new file mode 100644 index 0000000..d455553 Binary files /dev/null and b/docs/images/tiles-16.png differ diff --git a/docs/images/tiles-20-centered.png b/docs/images/tiles-20-centered.png new file mode 100644 index 0000000..5633a8a Binary files /dev/null and b/docs/images/tiles-20-centered.png differ diff --git a/docs/manual.rst b/docs/manual.rst new file mode 100644 index 0000000..21067da --- /dev/null +++ b/docs/manual.rst @@ -0,0 +1,2132 @@ +Minetest Mapper Manual +###################### + +A tool to generate maps of minetest and freeminer worlds. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. NOTE:: Note to readers reading this from the github repository: + Github mangles the internal links in this document, so unfortunately + many of them don't work. + +.. Contents:: :depth: 2 + +Invocation +========== + +Basic Usage (Linux / BSD / ...) +------------------------------- + +.. NOTE:: + For readability, example commands below are spread over multiple lines, using '``\``' as + a continuation character: '``\``' as the last character on a line indicates that the command + continues on the next line. Most shells will also interpret '``\``' in that way, and execute + the entire command only after the first line that does not end in '``\``'. + + Alternatively, all parts of the command-line can be typed on a single line, without the '``\``' + characters. + + +After installation, minetestmapper is started as follows:: + + minetestmapper \ + --input \ + --output + +If the world is not too large, and if minetestmapper is installed in +a system directory, it will most likely work as expected. + +Possibly, minetestmapper will not be able to find a colors.txt file. If that happens, +the colors.txt file can be specified on the command-line:: + + minetestmapper \ + --input \ + --output \ + --colors + +Or copy the colors.txt to a location where minetestmapper will automatically find it. +A colors.txt file (named ``colors.txt``, in lowercase) in the world's directory will certainly +be found. Depending on the system and the configuration, a number of other locations are +searched as well. Use the following command to find out which:: + + minetestmapper \ + --input \ + --output \ + --verbose-search-colors=2 + +See also: `Colors Files Search Locations`_. + +From this basis, add any number of other options that are documented below, according +to to personal needs and taste. + +Basic Usage (Windows) +--------------------- + +.. NOTE:: + For readability, example commands below are spread over multiple lines, using '``^``' as + a continuation character: '``^``' as the last character on a line indicates that the command + continues on the next line. The regular windows command prompt will also interpret '``^``' + as such, and excute the entire command only after the first line that does not end in '``^``'. + + So there are two options: + + * Type the commands exactly as shown, making sure '``^``' is the last character on each line + before typing return. + + * Type all parts of the command one after another, omitting the '``^``' characters and + type return only after typing the line that does not end in '``^``'. + +.. NOTE:: + The following commands assume that minetestmapper is installed in ``c:\games\minetestmapper``, and that + minetestmapper.exe is in ``c:\games\minetestmapper\bin``. If it installed elsewhere, use the actual + installation path instead. + +From the Command-line +..................... + +After installation, minetestmapper is started as follows from the command-line:: + + c:\games\minetestmapper\bin\minetestmapper.exe ^ + --input ^ + --output + +Possibly, minetestmapper will not be able to find the colors.txt file. If that happens, either +specify its location on the command-line:: + + c:\games\minetestmapper\bin\minetestmapper.exe ^ + --input ^ + --output ^ + --colors + +Or copy the colors.txt to a location where minetestmapper will automatically find it. +A colors.txt file (named ``colors.txt``, in lowercase) in the world's directory will certainly +be found. Depending on the system and the configuration, a number of other locations are +searched as well. Use the following command to find out which:: + + c:\games\minetestmapper\bin\minetestmapper ^ + --input ^ + --output ^ + --verbose-search-colors=2 + +See also: `Colors Files Search Locations`_. + +From this basis, add any number of other options that are documented below, according +to personal needs and taste. + +Using a Batch File +.................. + +A batch file is an easy way to prepare a minetestmapper command for later execution. While +batch files have many interesting features, only a simple example is given here. + +The basics of batch files can be easily found on internet. Search for '*writing a +batch file*' if the description below is too succint. + +Using notepad, create a file ``mapper.bat``, which contains the command-line, exactly like it +would be typed at the prompt. For example:: + + c:\games\minetestmapper\bin\minetestmapper ^ + --input c:\games\minetest\worlds\myworld ^ + --output c:\games\minetest\worlds\myworld\map.png ^ + --colors c:\games\colors.txt + +save the file (for example as ``c:\users\John\mapper.bat``), and execute it at the command-prompt:: + + c:\> c:\users\John\mapper.bat + +And the minetestmapper command-line from the batch file will be executed. + +Graphical Interface +------------------- + +A nice graphical interface is also available for minetestmapper. It can be obtained +from ``_. It runs both on Windows and +on Linux. + + .. image:: images/gui-1.png + .. image:: images/gui-2.png + +Mapping while Minetest is Running +--------------------------------- + +Depending on the backend, it is possible to run minetestmapper while minetest +is also running (and most probably accessing and modifying the database). + ++---------------+---------------------------------------------------------------+ +|Backend |Support for online mapping | ++===============+===============================================================+ +|SQLite3 |Works perfectly since 30 dec 2015, or minetest version | +| |0.4.14 and later. | +| | | +| |Minetest versions before 30 dec 2015 (or: version 0.4.13 and | +| |earlier) probably can't handle concurrent mapping, and | +| |may almost certainly crash with error 'database is locked'. | +| |(but different systems may still behave differently...) | +| | | +| |Minetest versions since 30 dec 2015 (or version 0.4.14 and | +| |later), may still be affected by locking delays, and even | +| |rare crashes. Use `--sqlite3-limit-prescan-query-size`_ if | +| |necessary. | ++---------------+---------------------------------------------------------------+ +|PostgreSQL |Works perfectly. | ++---------------+---------------------------------------------------------------+ +|LevelDB |Not possible. The database can't be accessed by multiple | +| |clients concurrently. | ++---------------+---------------------------------------------------------------+ +|Redis |Works perfectly. May affect minetest lag ? | ++---------------+---------------------------------------------------------------+ + +When using an SQLite3 database and a minetest version from before 30 dec 2015, +mapping may be possible while minetest is running, provided no players are online +and there are no forceloaded blocks (i.e. provided minetest is not accessing the +database while minetestmapper is running). The older versions of minetest will +only crash if they find the database temporarily locked when writing (due to +minetestmapper accessing it). Try at your own risk. + +Newer versions of may be affected by delays (i.e. lag). If the database is very large, +and the prescan query keeps it locked for too long a time, minetest may still bail out. + +Command-line Options Summary +---------------------------- + + For a more detailed description of the options, see `Detailed Description of Options`_ + below. + +Option Syntax +............. + +The options below use the following syntax: + + :some-text: Plain text should be typed as shown. + + :: This is a placeholder. The entire text (including '``<``' and '``>``') must + be replaced with whatever it designates. + + E.g. ```` might become ``100`` + + :[optional]: Anything between '``[``' and '``]``' is optional. It may be specified + (without ``[`` and ``]``), or left out (for a different result). + + :one|or|the|other: The '``|``' character signifies that one of the possibilities should + be typed. + + :list,of,options: A comma-separated list is a list of possible options. Use one or more + of them, separated by commas. + + :: Specify a geometry. See `Geometry Syntax`_ + + :: Specify a color. See `Color Syntax`_ + +Basic options: +.............. + + * ``--help`` : Print an option summary + * ``--version`` : Print version ID of minetestmapper + * ``--input `` : Specify the world directory (mandatory) + * ``--output `` : Specify the map file name (mandatory) + * ``--colors `` : Specify the colors file location and/or name. + * ``--heightmap[=]`` : Generate a height map instead of a regular map + * ``--heightmap-nodes `` : Specify the nodes list for the height map + * ``--heightmap-colors `` : Specify the color definition file for the height map + * ``--geometry `` : Specify the desired map dimensions + * ``--scalefactor `` : Specify the scaling factor for the map + * ``--progress`` : Print progress information while generating the map + * ``--verbose[=]`` : Report statistics about the world and the generated map + + +Area options: +............. + + * ``--scalefactor `` : Specify the scaling factor for the map + * ``--geometry `` : Specify the desired map dimensions + * ``--cornergeometry `` : Suggest interpretation as a corner + dimensions + * ``--centergeometry `` : Suggest interpretation as center + dimensions + * ``--min-y `` : Specify the minumum depth of nodes to be included + * ``--max-y `` : Specify the maximum height of nodes to be included + * ``--geometrymode pixel,block,fixed,shrink`` : Specify granularity and whether to shrink the map if possible + +Height map related options: +........................... + + * ``--heightmap[=]`` : Generate a height map instead of a regular map + * ``--heightmap-nodes `` : Specify the nodes list for the height map + * ``--heightmap-colors `` : Specify the color definition file for the height map + * ``--heightmap-yscale `` : Scale the vertical dimensions by a factor + * ``--height-level-0 `` : Set the '0' level differently for determining height map colors + * ``--drawheightscale`` : Draw a height scale at the bottom of the map + * ``--heightscale-interval [,|:]`` : Use custom major and minor intervals in the height scale. + +Colors for specific areas or parts of the map: +.............................................. + + * ``--bgcolor `` : Specify the background color for the image + * ``--blockcolor `` : Specify the color for empty mapblocks + * ``--scalecolor `` : Specify the color for text in the scales on the side + * ``--origincolor `` : Specify the color for drawing the map origin (0,0) + * ``--playercolor `` : Specify the color for drawing player locations + * ``--tilebordercolor `` : Specify the color for drawing tile borders + +Map features: +............. + + * ``--drawscale[=top,left]`` : Draw a scale on the left and/or top edge + * ``--drawheightscale`` : Draw a height scale at the bottom of the map + * ``--sidescale-interval [,|:]`` : Use custom major and minor intervals in the scale. + * ``--heightscale-interval [,|:]`` : Use custom major and minor intervals in the height scale. + * ``--draworigin`` : Draw a circle at the origin (0,0) on the map + * ``--drawplayers`` : Draw circles at player positions on the map + * ``--drawalpha[=cumulative|cumulative-darken|average|none]`` : Enable drawing transparency for some nodes (e.g. water) + * ``--drawair`` : Draw air nodes (read the warnings first!) + * ``--drawnodes [no-]air,[no-]ignore`` : Draw (or ignore) types of nodes (read the warnings first!) + * ``--ignorenodes [no-]air,[no-]ignore`` : Ignore (or draw) types of nodes (read the warnings first!) + * ``--noshading`` : Disable shading that accentuates height differences + +Tiles: +...... + + * ``--tiles [+]|block|chunk`` : Draw a grid of the specified size on the map + * ``--tileorigin ,|world|map`` : Specify the coordinates of one tile's origin (lower-left corner) + * ``--tilecenter ,|world|map`` : Specify the coordinates of one tile's center + * ``--tilebordercolor `` : Specify the color for drawing tile borders + * ``--chunksize `` : Specify or override the chunk size (usually 5 blocks) + +Drawing figures on the map +.......................... + + Using world coordinates: + + * ``--drawpoint ", "`` : Draw a point (single pixel) on the map + * ``--drawline " "`` : Draw a line on the map + * ``--drawarrow " "`` : Draw an arrow on the map + * ``--drawcircle " "`` : Draw a circle on the map + * ``--drawellipse " "`` : Draw an ellipse on the map + * ``--drawrectangle " "`` : Draw a rectangle on the map + * ``--drawtext ", "`` : Write some text on the map + + Same figures using map/image coordinates (0,0 is the top-left corner of the map) + + * ``--drawmappoint ", "`` : Draw a point (single pixel) on the map + * ``--drawmapline " "`` : Draw a line on the map + * ``--drawmaparrow " "`` : Draw an arrow on the map + * ``--drawmapcircle " "`` : Draw a circle on the map + * ``--drawmapellipse " "`` : Draw an ellipse on the map + * ``--drawmaprectangle " "`` : Draw a rectangle on the map + * ``--drawmaptext ", "`` : Write some text on the map + +Feedback / information options: +............................... + + * ``--help`` : Print an option summary + * ``--version`` : Print version ID of minetestmapper + * ``--verbose[=]`` : Report world and map statistics (size, dimensions, number of blocks) + * ``--verbose-search-colors[=n]`` : Report which colors files are used and/or which locations are searched + * ``--silence-suggestions `` : Do not bother doing suggestions + * ``--progress`` : Show a progress indicator while generating the map + +Miscellaneous options +..................... + + * ``--backend auto|sqlite3|postgresql|leveldb|redis`` : Specify or override the database backend to use + * ``--disable-blocklist-prefetch`` : Do not prefetch a block list - faster when mapping small parts of large worlds. + * ``--database-format minetest-i64|freeminer-axyz|mixed|query`` : Specify the format of the database (needed with --disable-blocklist-prefetch and a LevelDB backend). + * ``--prescan-world=full|auto|disabled`` : Specify whether to prescan the world (compute a list of all blocks in the world). + * ``--sqlite3-limit-prescan-query-size[=]`` : Limit the size of individual block list queries during a world prescan. + + +Detailed Description of Options +------------------------------- + + A number of options have shorthand equivalent options. For instance + ``--help`` and ``-h`` are synonyms. The following are notable: + + * ``-h`` = ``--help`` + * ``-V`` = ``--version`` + * ``-o`` = ``--output`` + * ``-i`` = ``--input`` + + For the others, please consult the source code. Note that support + for other short options than mentioned above might be removed in + the future. + + **Available options**: + +.. Contents:: :local: + + +``--backend auto|sqlite3|postgresql|leveldb|redis`` +................................................... + Set or override the database backend to use. + + By default (``auto``), the database is obtained from the world configuration, + and there is no need to set it, + + For backward compatibility, besides supporting the official implementation, + minetestmapper still supports two previous unofficial implementations of + postgresql support for minetest. These are ShadowNinja's, and johnnyjoy's. + Support for these two versions will be removed in a future version of + minetestmapper. + +``--bgcolor `` +..................... + Specify the background color for the image. See `Color Syntax`_ below. + + Two maps with different background: + + .. image:: images/background-white.png + .. image:: images/background-blueish.png + +``--blockcolor `` +........................ + Specify the color for empty mapblocks. See `Color Syntax`_ below. + + An empty mapblock exists in the database, but contains only *air* or *ignore* + nodes. It is normally not visible, even if no other mapblocks exist above + or below it. This color makes such blocks visible if no nodes other than + air or ignore are above or below it. + + To see the difference between empty blocks and absent blocks, generate a map + that is larger than the world size by at least 2 map blocks. + + Two maps, the second with blockcolor enabled: + + .. image:: images/background-white.png + .. image:: images/blockcolor-yellowish.png + + +``--centergeometry `` +............................... + Suggest interpreting a geometry as center coordinates and dimensions. If possible. + + See also `--geometry`_ + +``--chunksize `` +...................... + Set or override the chunk size. + + The chunk size is the unit of map generation in minetest. Minetest never generates + a single block at a time, it always generates a chunk at a time. + + The chunk size may be used by the `--tiles`_ option. It is obtained from + the world by default. It is usually, but not necessarily, 5 (i.e. 5x5x5 blocks). + +``--colors `` +................... + Specify the location and name of the 'colors.txt' file to use. + + See `Colors and Nodes Files`_ and `Colors.txt Syntax`_. + + By default, minetestmapper will attempt to automatically find a suitable + colors.txt file. See `Colors Files Search Locations`_. + +``--cornergeometry `` +............................... + Suggest interpreting a geometry as corner coordinates and dimensions. If + possible. + + See also `--geometry`_ + +``--database-format minetest-i64|freeminer-axyz|mixed|query`` +.................................................................. + Specify the coordinate format minetest uses in the LevelDB database. + + This option is only needed, and has only effect, when + `--disable-blocklist-prefetch`_ is used, *and* when the database backend + is 'leveldb'. Users of other backends can ignore this option. + + **Background** + + A freeminer LevelDB database has two possible coordinate formats. Normally, + minetestmapper detects which one is used for which block when prefetching + a block coordinate list. With ``--disable-blocklist-prefetch``, minetestmapper + will not start by reading a list of all blocks in the database. It therefore + won't be able to detect what format is actually used for the coordinates of + every block (which might differ per block). + + Without knowing the format used for a block, the only way to be sure that it + is not in the database, is to use two queries, one for each format. Specifying + the format allows minetestmapper to avoid the second query, with the risk of + overseeing blocks if they do happen to use the other format. + + **Values** + + :``mixed``: (default) This works in all cases, as both queries are + performed if needed (at the very least for all blocks that are + not in the database), but it is less efficient. + + Use this on older freeminer worlds, and on worlds that were + migrated from minetest (if such worlds exist ?). + + :``minetest-i64``: + The ``i64`` format used by minetest. Specify this for minetest + worlds, as it is, and has always been, the only format used. + + :``freeminer-axyz``: + The ``axyz`` format used by freeminer since april 2014. Specify + this for freeminer worlds that are known not to contain ``i64`` + blocks. This includes all worlds created by a freeminer version + that dates from after april 2014. + + :``query``: Directs minetestmapper to detect and report the coordinate + format(s) used in the database. This requires that full block list + be fetched from the database, so ``--disable-blocklist-prefetch`` + must be not be set, and ``--prescan-world`` must not be ``disabled``. + + Once the actual coordinate format(s) are known, the most appropriate + value can be selected. + + + Specifying ``minetest-i64`` or ``freeminer-axyz`` incorrectly results in all + blocks that use the other format not being mapped. + +``--disable-blocklist-prefetch`` +...................................... + Do not prefetch a list of block coordinates from the database before commencing + map generation. + + This is synonymous with `--prescan-world=disabled`_. + + This option will probably improve mapping speed when mapping a smaller part + of a very large world. In other cases it may actually reduce mapping speed. + It is incompatible with, and disables, the 'shrinking' mode of `--geometrymode`_. + It also significantly reduces the amount of information the `--verbose`_ option + can report. + + When used with a LevelDB backend, the option `--database-format`_ should preferably + be used as well. + + **Background** + + Normally, minetestmapper will read a full list of coordinates (not the contents) + of existing blocks from the database before starting map generation. This option + disables such a query, and instead, causes and all blocks that are in the mapped + space to be requested individually, whether or not they are in the database. + + Querying the database for a block coordinate list beforehand is time-consuming + on large databases. If just a small part of a large world is being mapped, the + time for this step quickly dominates the map generation time. + + On the other hand, querying the database for large numbers of non-existing blocks + while mapping (possibly several orders of magniture more than there are existing + blocks!) is also quite inefficient. If a large part of the blocks queried are not + in the database, the cost of those extra queries will quickly dominate map generation + time. + + The tradeoff between those two approaches depends on the volume being mapped, the + speed of the disk (or SSD), the database backend being used, the number of blocks + in the database, etc. + + The worst-case behavior of this option is probably quite bad, even though it will + refuse to continue if the requested space is excessive: exceeding 1G (2^30) blocks. + Please use this option with consideration, and use `--progress`_ to monitor its + actual behavior. + +``--draw[map]
" []"`` +..................................................... + Draw a figure on the map, with the given geometry and color. + + Possible figures are: + + * circle + * ellipse (which is a synonym for circle) + * line + * arrow + * point (which uses simple coordinates (x,y) instead of a geometry) + * rectangle + * text (which uses simple coordinates (x,y) instead of a geometry) + + If ``--draw
`` is used, the geometry specifies world coordinates; + if ``--drawmap
`` is used, the geometry specifies map (i.e. image) + coordinates, where 0,0 is the top-left corner of the map-part of + the image, and coordinates increase to the right and down. Any points + in the left and top scale area (if present) have negative coordinates. + + Note that the combination of geometry and color (and text if applicable) + must be a single argument. This means that they *must* be enclosed + in quotes together on the command-line, else they will be misinterpreted + as two or more command-line arguments. + + Example:: + + minetestmapper --drawcircle "10,10:6x6 red" + + For the color of figures, an alpha value can be specified. Note that + due to a bug in the drawing library, this has not the expected effect + when drawing circles and ellipses. + + See also `Geometry Syntax`_ and `Color Syntax`_. + + **Interaction of figure geometry and map scaling** + + If the map is scaled, figures could either keep the same size in pixels, + or the same size relative to the world, which would make them appear + smaller like the entire map. Whether they scale of not depends on how + they are drawn: + + * Figures which are drawn using map (i.e. image) coordinates are never scaled. + It is assumed that it was the intention to draw them on the image to + begin with, and not in the world. + + At the moment, figures which are drawn using world coordinates may or + may not scale with the world. + + * If the geometry of a figure is specified using 2 corners, then the distance + between the coordinates obviously scales with the world, and the resulting + figure will be visually smaller as well. + + * If the geometry of a figure is specified using a corner or the center + and dimensions, then the corner or center is obviously also interpreted + as world-coordinates, but the dimensions will be interpreted relative + to the image. I.e. they won't scale with the map. + + * If the geometry is specified using an angle and length, and if the + length is specified in nodes (e.g. '20n'), the size will scale. If + the length is specified in pixels (e.g. '20p') or if no unit is + specified, then the size will not scale. + + In practise this means that two identically-sized figures in a full-scale + map, may have different sizes after scaling, depending on how their + geometry was specified. The jury is still out as to whether this is + a bug or a feature. + +``--draw[map]circle " "`` +.......................................... + Draw a circle on the map, with the given geometry and color. + + If the geometry does not specify equal horizontal and vertical + dimensions, then an ellipse will be drawn. + + See `--draw[map]
`_ for details. + + An example circle: + + .. image:: images/drawcircle.png + +``--draw[map]ellipse " "`` +........................................... + Draw an ellipse on the map. This is a synonym for ``--draw[map]circle``. + + See `--draw[map]
`_ for details. + +``--draw[map]line " "`` +........................................ + Draw a line on the map, with the given geometry and color. + + See `--draw[map]
`_ for details. + + An example line: + + .. image:: images/drawline.png + +``--draw[map]arrow " "`` +......................................... + Draw an arrow on the map, with the given geometry and color. + + See `--draw[map]
`_ for details. + + An example arrow: + + .. image:: images/drawarrow.png + +``--draw[map]point ", "`` +...................................... + Draw a point on the map, at the given location, using the given color. + + See `--draw[map]
`_ for details. + + An example point (red, in te white area): + + .. image:: images/drawpoint.png + +``--draw[map]rectangle " "`` +............................................. + Draw a reactangle on the map, with the given geometry and color. + + See `--draw[map]
`_ for details. + + An example rectangle: + + .. image:: images/drawrectangle.png + + +``--draw[map]text ", "`` +............................................ + Write text on the map, at the specified location, using the given color. + + The text can consist of any number of words. Be careful when using + characters that the command shell may interpret, like '``"``', + '``$``', etc. On unix-like systems, use single quotes to avoid + interpretation of most characters (except for ``'`` itself). + + Due to a limitation of the drawing library, currently only text that + can be represented in (i.e. converted to) the ISO8859-2 character set is + supported. Text that uses non-compatible characters will not be rendered + correctly. + + Note that the combination of geometry, color and text should be a + single argument. This means that they must be enclosed in quotes + together on the command-line, else they will be misinterpreted as three + command-line arguments. + + Example:: + + minetestmapper --drawtext "20,-10 red This text will be on the map" + + See also `--draw[map]
`_ for more details. + + Example text: + + .. image:: images/drawtext.png + +``--drawair`` +............. + Draw air nodes, as if they were regular nodes. + + This option is synonymous with `--drawnodes air`_. + +``--drawalpha[=cumulative|cumulative-darken|average|none]`` +........................................................... + Specify how to render the transparency (defined by the alpha value) of nodes. + + :none: don't render transparency. This is the same as + omitting this option. + + :average: average the entire stack of transparent nodes + before combining the resulting color with the color of the + first opaque node below the stack. Water will remain transparent + indefinitely. + + :cumulative: make lower nodes progressively more opaque. + The effect is for instance, that water becomes opaque below + a certain depth - only height differences will 'shine' through, + if shading is not disabled (`--noshading`_) + + :cumulative-darken: Same as *cumulative*, except that + after the color has become opaque, it is progressively + darkened to visually simulate greater depth. This is looks great + for deeper waters that are not too deep. + The downside is that very deep water will eventually become black + when using this option. + + If this option is used without a method argument, the + default is 'average'. + + For backward compatibility, 'nodarken' is still recognised as alias + for 'cumulative'; 'darken' is still recognised as alias for + 'cumulative-darken'. They are otherwise undocumented. Please don't + use them, they may disappear in the future. + + Note that each of the different modes has a different color definition + for transparent blocks that looks best. For instance, for water, the following + are suggested: + + :(disabled): ``39 66 106`` [``192 224`` - optional: alpha value will be ignored] + + :cumulative: ``78 132 255 64 224`` + + :cumulative-darken: ``78 132 255 64 224`` (same colors as cumulative) + + :average: ``49 82 132 192 224`` (also looks good with alpha disabled) + + Custom colors files are provided for these alternatives: colors-average-alpha.txt + and colors-cumulative-alpha.txt. If desired, these must be manually selected. + + The following images show average alpha mode, cumulative mode and cumulative-darken + mode. In each case, the matching custom color file was selected: + + .. image:: images/alpha-average.png + .. image:: images/alpha-cumulative.png + .. image:: images/alpha-cumulative-darken.png + + +``--drawheightscale`` +..................... + If drawing a height map (`--heightmap`_), draw a height scale below the image. + + A height map with scale: + + .. image:: images/heightmap-scale.png + +``--drawnodes [no-]air,[no-]ignore`` +.................................... + Draw air-type or ignore-type nodes, as if they were regular nodes. + By default they are not drawn. + + A prefix of '``no-``' inverts the effect, so that the nodes are ignored + instead. + + Air-type nodes are the node named '``air``', and any node that has the + `air` flag in the colors file. + Ignore-type nodes are the node named '``ignore``', and any node that has the + `ignore` flag in the colors file. + See `Colors.txt Syntax`_. + + If a node has both the `air` flag and the `ignore` flag, the `ignore` flag + takes precedence. I.e. the `air` flag will be ignored. + + If drawing `air` and/or `ignore` nodes, they must obviously have an entry + in the colors file. + + WARNING 1: + The color of air-type and ignore-type nodes should most probably have an + alpha value of 0, so that they are fully transparent. The effect will be, + that they nodes are only visible if nothing else is below them. + + Setting alpha to anything other than 0, will most probably cause + all non-air / non-ignore nodes to be obscured by all of the air/ignore + nodes that are above them. + + WARNING 2: + Drawing '``air``' or '``ignore``' nodes instead of ignoring them will have a + significant performance impact (unless they happen to be defined as opaque). + Use this with consideration. + + Instead of enabling the drawing of '``air``' or '``ignore``' nodes, it may be + possible to achieve a similar result, with a negligible performance impact, + by using the option `--blockcolor`_. + + This option is the inverse of `--ignorenodes`_. + + Two images, one with air drawn, the other without. Look inside the rectangle: + + .. image:: images/background-white.png + .. image:: images/drawair.png + .. image:: images/drawair-detail-0.png + .. image:: images/drawair-detail.png + +``--draworigin`` +................ + Draw a circle at the world origin (coordinates 0,0) + + The color can be set with `--origincolor`_. + + An image with world origin drawn: + + .. image:: images/draworigin.png + +``--drawplayers`` +................. + Draw circles and player names at the positions of players + + The color can be set with `--origincolor`_. + + Just like for text drawn with `--draw[map]text`_, characters that cannot be converted + to the ISO8859-2 character set will not be rendered correctly. + + An image with a few players: + + .. image:: images/players.png + +``--drawscale[=left,top]`` +.......................... + Draw scales at the left and/or top of the map. + + If neither 'left' nor 'top' is specified, draw them on both sides. + + The color of the lines and numbers can be set with `--scalecolor`_. + + The major and minor interval can be configured using + `--sidescale-interval`_. + + Images of scales on the top, left and on both sides: + + .. image:: images/drawscale-left.png + .. image:: images/drawscale-top.png + .. image:: images/drawscale-both.png + +``--geometry `` +......................... + Specify the map geometry (i.e. which part of the world to draw). + + See `Geometry Syntax`_ for how the geometry can be specified. + + By default, the entire visible world is drawn. + +``--geometrymode pixel,block,fixed,shrink`` +........................................... + Specify explicitly how the geometry should be interpreted. + + One or more of the flags may be used, separated by commas or + spaces. In case of conflicts, the last flag takes precedence. + + See also `Geometry Syntax`_ + + The geometry can have pixel or block granularity: + + :pixel: Interpret the coordinates with pixel granularity. + + A map of exactly the requested size is generated (after + adjustments due to the 'shrink' flag, or possible adjustments + required by the scale factor). + + :block: Round the coordinates to a multiple of 16. + + The requested geometry will be extended so that the map does + not contain partial map blocks (of 16x16 nodes each). + At *least* all pixels covered by the geometry will be in the + map, but there may be up to 15 more in every direction. + + The geometry can be fixed as requested, or the map can be shrunk: + + :shrink: Generate a map of at most the requested geometry. + Shrink it to the smallest possible size that still includes the + same information. + + Currently, shrinking is done with block granularity, and + based on which blocks are in the database. As the database + always contains a row or and column of empty, or partially + empty blocks at the map edges, there will still be empty + pixels at the edges of the map. Use `--blockcolor`_ to visualize + these empty blocks. + + :fixed: Don't reduce the map size. What ever is specified + using a geometry option, is what will be drawn, even if partly + or fully empty. + + **NOTE**: If this flag is used, and no actual geometry is + specified, this would result in a maximum-size map (65536 + x 65536), which is currently not possible, and will fail, + due to a bug in the drawing library. + + The default is normally 'pixel' and 'fixed', if a geometry + option was specified. See `Legacy Geometry Format`_ for one + exception. + + Default image in the center, block mode enabled to the left and + shrink mode enabled to the right: + + .. image:: images/geometrymode-block.png + .. image:: images/geometrymode.png + .. image:: images/geometrymode-shrink.png + +``--heightmap-colors[=]`` +............................... + Use the specified file as the heightmap colors file. + + See `Colors and Nodes Files`_ and `Heightmap-colors.txt Syntax`_. + + By default, minetestmapper will attempt to automatically find a + suitable heightmap-colors.txt file. See `Colors Files Search Locations`_. + +``--heightmap-nodes `` +............................ + Use the specified file as the heightmap nodes file. + + See `Colors and Nodes Files`_ and `Heightmap-nodes.txt Syntax`_. + + By default, Minetestmapper will attempt to automatically find a suitable + heightmap-nodes.txt file. See `Colors Files Search Locations`_. + +``--heightmap-yscale `` +............................... + Scale the heights of the map before computing the height map colors. + + This is useful when there are very large, or only very small, height + differences in the world, and too much of the map is drawn in a + single, or similar, colors. + + Using this option improves the spread of colors in the height map. + The option `--height-level-0`_ may also be of use. + + 'Factor' is a decimal number. A value of 1 means no change; a larger + value stretches the color range, a smaller value (but larger than 0) + condenses the color range. + + Note that the water level will probably not be rendered correctly for + scale factors smaller than 1, nor for small non-integer scale factors. + A suitable choice of ``--height-level-0`` may lessen this effect somewhat. + + For the same effect, a modified colors file could be used. + ``--heightmap-yscale`` is easier and quicker. + + Two images with a different y-scale: + + .. image:: images/heightmap-scale.png + .. image:: images/heightmap-yscale.png + +``--heightmap[=]`` +......................... + Generate a height map instead of a regular map. + + If a color is given, a monochrome map is generated in shades of that + color, ranging from black at depth -128 to the given color at height 127. + + See also `Color Syntax`_. + + Three colors are treated specially: + + :white: The entire map will be white. Any visible structure will + result from the rendering of height differences. + :black: The entire map will be black. Any visible structure will + result from the rendering of height differences. This actually looks + pretty good + :grey: The map will be drawn in shades of grey, ranging from black + at level -128 to white at level 127 + + If no color is specified, minetestmapper will use a colors file to + determine which colors to use at which height level. See + `Colors and Nodes Files`_ and `Heightmap-colors.txt Syntax`_. + + In any case, minetestmapper also needs a nodes file. See + `Heightmap-nodes.txt Syntax`_ for details. + + A regular map, a greyscale height map and a colored height map: + + .. image:: images/scalefactor-2.png + .. image:: images/heightmap-grey.png + .. image:: images/heightmap-color.png + +``--heightscale-interval [,|:]`` +............................................... + When drawing a height scale at the bottom of the map, use the specified + subdivisions. + + 'major' specifies the interval for major marks, which are accompanied + by a number indicating the height. + + When specified as 'major,minor', 'minor' specifies the interval for + minor tick marks + + When specified as 'major:minor', 'minor' specifies the number of subdivisions + of the major interval. In that case, major should be divisible by minor. + E.g.: ``10:2`` is OK (equivalent to ``10,5``), ``10:3`` is not OK. + + By default, the major interval is calculated based on the available space + and the range of heights in the map. + The default minor interval is 0 (i.e. no minor ticks) + + The default height scale interval and a custom interval: + + .. image:: images/heightmap-scale.png + .. image:: images/heightmap-scale-interval.png + +``--height-level-0 `` +............................ + Specify the zero height level of the map to use for height maps. + + This is the world height that will be drawn using the color that the + colors file specifies for level 0. + This is useful when the average level of the world is lower + or higher than the colors file caters for. It may also be of some use + for height maps when the world has a non-standard sea level. + + The option `--heightmap-yscale`_ may also be of use if this option + is used. + + For the same effect, a modified colors file could be used. + ``--height-level-0`` is easier and quicker. + +``--help`` +.......... + Print the option summary. + +``--ignorenodes [no-]air,[no-]ignore`` +...................................... + Ignore air-type or ignore-type nodes, so that they are not drawn at all. + + A prefix of '``no-``' inverts the effect, so that the nodes are drawn + like regular nodes. + + This option is the inverse of `--drawnodes`_. E.g.:: + + --ignorenodes no-air,ignore + + is equivalent to:: + + --drawnodes air,no-ignore + + See `--drawnodes`_ for more information. + +``--input `` +........................ + Specify the world to map. + + This option is mandatory. + +``--max-y `` +............... + Specify the upper height limit for the map + + Nodes higher than this level will not be drawn. This can be used + to avoid floating islands or floating artefacts from obscuring the + world below. + +``--min-y `` +............... + Specify the lower height limit for the map + + Any nodes below this level will not be drawn. + +``--noshading`` +............... + Disable shading. + + Shading accentuates height differences by drawing artifical shade + (i.e. making nodes lighter or darker depending on the height difference + with adjacent nodes). + + A map with and without shading: + + .. image:: images/default-0.0.png + .. image:: images/noshading.png + +``--origincolor `` +......................... + Specify the color to use for drawing the origin. + + An alpha value can be specified, but due to a bug in the + drawing library, it will not have the desired effect. + + Use `--draworigin`_ to enable drawing the origin. + + See also `Color Syntax`_ + +``--output `` +............................... + Specify the name of the image to be generated. + + This parameter is mandatory. + + Note that minetestmapper generates images in png format, regardless of + the extension of this file. + +``--playercolor `` +......................... + Specify the color to use for drawing player locations + + An alpha value can be specified, but due to a bug in the + drawing library, it will not have the desired effect for + the circles. + + Use `--drawplayers`_ to enable drawing players. + + See also `Color Syntax`_ + +``--prescan-world=full|auto|disabled`` +........................................ + Specify whether to prescan the world, i.e. whether to compute + a list of which blocks inside the area to be mapped are actually + in the database before mapping. + + When ``disabled``, minetestmapper will not compute such a list at + all. While mapping, it will just attempt to load every possible + block in the section of world determined by geometry and min-y and + max-y. This is synonymous with ``--disable-blocklist-prefetch``. + See `--disable-blocklist-prefetch`_ for a discussion, caveats and + other important notes. + + When set to ``full``, minetestmapper will always query the database + for the complete list of blocks which exist in the entire world. Even + if a smaller area could be queried for because of the map geometry, + min-y or max-y. + This allows the actual world dimensions to be reported, but at the + cost of additional processing time, especially if the mapped part + of the world is small compared to the existing world size. + + When set to the default value: ``auto``, if possible and sensible, + minetestmapper will query the database for just a list of the blocks + in the part of the world of interested, depending on geometry, + min-y and max-y. If it does, the actual world dimensions cannot + be reported. + + Unfortunately, most database backends do not support querying for a + partial block-list, or if they do, it is much less efficient than + querying for a full list. Only the PostgreSQL backend supports it + efficiently. So for all databases except PostgreSQL, ``auto`` is + equivalent to ``full``. + +``--progress`` +.............. + Show a progress indicator while generating the map. + +``--scalecolor `` +........................ + Specify the color to use for drawing the text and lines of the scales + (both the side scales and the height map scale). + + Use `--drawscale`_ to enable drawing side scales. + + Use `--drawheightscale`_ to enable drawing the height scale. + + See also `Color Syntax`_ + +``--scalefactor 1:`` +....................... + Generate the map in a reduced size. + + Basically, the image is be reduced in size while it is generated, + by averaging a square region of pixels into one new pixel. + + This has several uses: + + * to generate overview maps of large worlds + * if the image is otherwise too large to be practical + * if the map image would be too large to be generated + (see `Known Problems`_). + + Another advantage of generating scaled maps directly, instead of using + an external application, is that minetestmapper does not scale all + parts of the image, just the world-area. The scales on the side for instance + are not scaled, and neither is the thickness of lines (e.g. tile borders, + figures, player names, etc.). + + The following scale factors are supported: + + :1\:1: no scaling. This value has no effect. + :1\:2: reduce the map size by a factor 2 + :1\:4: reduce the map size by a factor 4 + :1\:8: reduce the map size by a factor 8 + :1\:16: reduce the map size by a factor 16 + + .. Note to readers of the text version: the factors above are + .. slightly mangled due to markup. The non-markup scale factors + .. are: 1:1, 1:2, 1:4, 1:8 and 1:16. + + In addition, scaling needs to follow map block boundaries. That + means that when scaling the map, regardless of the geometry, + the same pixels will be averaged. E.g. if the scale factor is ``1:16``, + then entire map blocks will be averaged, so therefore the map + geometry can only include full map-blocks. + + If the requested geometry of the map is not suited to the + requested scale factor, the map will be enlarged by as many nodes as + needed. The number of added nodes depends on the scale factor. E.g. + if the scale factor is ``1:8``, then at most 7 nodes may be added to on + each of the four sides of the map. + + Original map, and the same map, scaled to ``1:2`` and ``1:4``. The geometry is + increased to keep the images the same size: + + .. image:: images/default-0.0.png + .. image:: images/scalefactor-2.png + .. image:: images/scalefactor-4.png + +``--sidescale-interval [,|:]`` +............................................. + When drawing a side scale at the top or left of the map, use the specified + subdivisions. + + 'major' specifies the interval for major marks, which are accompanied + by a number indicating the coordinate. + + When specified as 'major,minor', 'minor' specifies the interval for + minor tick marks + + When specified as 'major:minor', 'minor' specifies the number of subdivisions + of the major interval. In that case, major should be divisible by minor. + E.g.: ``100:20`` is OK (equivalent to ``100,5``), ``100:33`` is not OK. + + By default, the major interval is 64 for a ``1:1`` map, 128 for a ``1:2`` map etc. + The default minor interval is 0 (i.e. no minor ticks) + + The default side scale interval, and a custom interval: + + .. image:: images/drawscale-both.png + .. image:: images/sidescale-interval.png + +``--silence-suggestions `` +...................................... + Do not print usage suggestions of the specified types. + + If applicable, minetestmapper may suggest using or adjusting certain options + if that may be advantageous. This option disables such messages. + + :all: Silence all existing (and future) suggestions there may be. + :prefetch: Do not make suggestions a about the use of `--disable-blocklist-prefetch`_, + and adjustment of --min-y and --max-y when using --disable-blocklist-prefetch. + :sqlite3-lock: Do not suggest using `--sqlite3-limit-prescan-query-size`_. + + This warning will be given if the database was kept locked for 1 second or + more while fetching the block list `and` if the database was modified during + that time. + +``--sqlite-cacheworldrow`` +.......................... + This option is no longer supported, as minetestmapper performed + consistently worse with it than without it, as tested on a few + large worlds. + + It is still recognised for compatibility with existing scripts, + but it has no effect. + +``--sqlite3-limit-prescan-query-size[=]`` +................................................. + Limit the size of block list queries during a world prescan + (see `--prescan-world`_). + + Use this if mapping while minetest is running causes minetest to + report warnings like: + + SQLite3 database has been locked for + + If minetestmapper locks the database for too long, minetest may even + bail out eventually (i.e. crash). + + If `--sqlite3-limit-prescan-query-size` is used, instead of doing a single + prescan query, minetestmapper will perform multiple queries, each for a + limited number of blocks, thus limiting the duration of the database lock. + + To avoid blocks being skipped, which could happen if minetest has inserted new + blocks into the database, every query will overlap with the previous query. + + Sample overlap sizes: + + ============ ========== ========== + Blocks Overlap Fraction + ============ ========== ========== + 2000 1000 50% + 10000 1000 10% + 100000 10000 10% + 250000 11750 4.7% + 1000000 20000 2% + ============ ========== ========== + + The default value of `blocks` is 250000, the minimum value is 2000. The + minimum overlap is 1000. + + E.g. with `blocks` = 100000 the overlap will be 10000, and minetestmapper will + perform the following block list prescan queries: + + ========= ========== ========== + Query nr. From To + ========= ========== ========== + 1 0 110000 + 2 100000 210000 + 3 200000 310000 + 4 300000 410000 + etc. etc. + ========= ========== ========== + + When using small values of `blocks` on fast machines, while minetest is + busy generating new parts of the world, the overlap may not be sufficient. + It is recommended (and much more efficient) to use a value of at least + 100000. + +``--tilebordercolor `` +............................. + Specify the color to use for drawing tile borders. + + Use `--tiles`_ to enable drawing tiles. + + See also `Color Syntax`_ + +``--tilecenter ,|world|map`` +.................................. + Arrange the tiles so that one tile has, or would have, its center + at map coordinates x,y. + + If the value 'world' is used, arrange for one tile to have its center + at the center of the world instead. This is the default. + + If the value 'map' is used, arrange for one tile to have its center + at the center of the map instead. + + (see also `--tileorigin`_) + +``--tileorigin ,|world|map`` +.................................. + Arrange the tiles so that one tile has, or would have, its bottom-left + (i.e. south-west) corner at map coordinates x,y. + + If the value 'world' is used, arrange for one tile to have its lower-left + corner the origin of the world (0,0) instead. + + If the value 'map' is used, arrange for one tile to have its upper-left + corner at map coordinate 0,0 (which is the upper-left pixel of the + map-part of the image) + + (see also `--tilecenter`_) + +``--tiles [+]|block|chunk`` +............................................. + Divide the map in square tiles of the requested size. A border of the + requested width (or width 1, of not specfied) is drawn between the tiles. + In order to preserve all map pixels (to prevent overwriting them with + borders), extra pixel rows and columns for the borders are inserted into + the map. + + The special values 'block' and 'chunk' draw tiles that correspond to map + blocks (16x16 nodes) or to chunks (the unit of map generation: 5x5 blocks + for a world with default settings). + + In order to allow partial world maps to be combined into larger maps, tile + borders at the edge of the map are always drawn on the same side (left or top). + Other map edges are always border-less. + + NOTE: As a consequence of preserving all map pixels: + + * tiled maps (in particular slanted straight lines) may look slightly + skewed, due to the inserted borders. + + * scale markers never align with tile borders, as the borders are + logically *between* pixels, so they have no actual coordinates. + + * On scaled maps, only tile sizes and tile offsets that are a multiple + of the inverse scale (e.g. '8' for scale 1:8) are supported. + + See the options `--tileorigin`_ and `--tilecenter`_ for specifying the + positioning of tiles. By default, tiles are arranged so that one tile + has, or would have, its center at the world origin (0,0). + + Tiled maps. On the left, 16x16 tiles with corner at the world origin. In + the middle, 16x16 tiles with center at the world origin. To the right, + 20x20 tiles with center at the world origin: + + .. image:: images/tiles-16.png + .. image:: images/tiles-16-centered.png + .. image:: images/tiles-20-centered.png + + +``--verbose-search-colors[=]`` +................................. + report the location of the colors file(s) that are being used. + + With ``--verbose-search-colors=2``, report all search locations + that are being considered as well. + +``--verbose[=]`` +................... + report some useful / interesting information: + + * maximum coordinates of the world. + With a PostgreSQL backend, these are only reported if + `--prescan-world`_ is set to ``full``. + * world coordinates included the map being generated. + * number of blocks: in the world, and in the map area. + * `--database-format`_ setting if `--disable-blocklist-prefetch`_ is used. + + Using `--verbose=2`, report some more statistics, including: + + * database access statistics. + + Using `--verbose=3`, report statistics about block formats found in the database + (currently only applicable to LevelDB) + + Description of possible reported coordinates. Only the values that are + applicable and available are printed. + + :Command-line Geometry: The geometry specified on the command-line, before + aligning to map-blocks. + If none, then the maximum possible geometry. + :Requested Geometry: The effective geometry requested on the command-line + (i.e. after aligninment to map-blocks due to the + requested or implicit granularity). + If none, then the maximum possible geometry. + :Adjusted Geometry: The geometry after adjustment required by scaling. + :Block-aligned Geometry: The geometry of the area to be loaded from the database + (i.e. extended to map-block boundaries). + :World Geometry: The geometry of the entire existing world found in + the database. + :Minimal Map Geometry: The minimal possible geometry that shows the same + information as the requested geometry. + :Map Vertical Limits: Vertical limits of the world in the area being mapped. + :Map Output Geometry: The Geometry of the map that will be generated. + :Mapped Vertical Range: The actual vertical limits of the blocks that were mapped. + (I.e. excluding air and underground blocks that are not + visible) + This range is currently reported with block granularity. + +``--version`` +............. + Report the version of this instance of minetestmapper. + + This is great information to include in a bug report. + + +Color Syntax +============ + + For a number of command-line parameters, a color argument is needed. Such + colors are specified as follows: + +Color Codes +----------- + + Colors can be specified using hexadecimal color codes:: + + #[] + + where every component is a hexadecimal (base 16) number between hexadecimal + 0 and ff (i.e. between 0 and 255). + The components must all be 1 digit wide or all 2 digits wide. + E.g.: ``#ff34c1``, ``#8123`` + + The alpha component is optional in some cases, and not allowed in others. It + defaults to opaque (``ff``). + + If the color components are specified using a single digit per color, that + digit is duplicated to obtain the full value. E.g.: + + ``#4c2`` --> ``#44cc22`` + + ``#8123`` --> ``#88112233`` + +Symbolic Colors +--------------- + + In addition to the color codes, a few named colors are also available: + + :white: ``#ffffff`` + :black: ``#000000`` + :gray: ``#7f7f7f`` - (same as grey) + :grey: ``#7f7f7f`` - (same as gray) + :red: ``#ff0000`` + :green: ``#00ff00`` + :blue: ``#0000ff`` + :yellow: ``#ffff00`` + :magenta: ``#ff00ff`` - (same as fuchsia) + :fuchsia: ``#ff00ff`` - (same as magenta) + :cyan: ``#00ffff`` - (sama as aqua) + :aqua: ``#00ffff`` - (sama as cyan) + :orange: ``#ff7f00`` + :chartreuse: ``#7fff00`` + :pink: ``#ff007f`` + :violet: ``#7f00ff`` + :springgreen: ``#00ff7f`` + :azure: ``#007fff`` + :brown: ``#7f3f00`` + +Advanced usage: Lighter or Darker Colors +---------------------------------------- + + As an additional feature, any color can lightened or darkened, or in general, + be mixed with a basic color using the following syntax:: + + [+-][wkrgbcmy] + + Where '+' mixes in, and '-' mixes out. one of the colors white (w), black (k), red (r), green (g), blue (b), + cyan (c), magenta (m), yellow (y). The value specifies the amount, ranging from 0 (mix in/out no color) to + 1 (mix in/out as much of the color as possible). E.g.: + + ``red+w0.25``: add 25% white: light red (``#ff3f3f``) + + ``red+k0.50``: add 50% black: dark red (``#7f0000``) + + ``red-w0.50``: remove 50% white: dark red as well (``#7f0000``) + + ``white-b1``: remove 100% blue: yellow (``#ffff00``) + +Geometry Syntax +=============== + + For a number of options, like the 'geometry' options, but also + the drawing options for instance, a geometry parameter must + be specified. It can specify the dimensions in a few different + ways: + + * As the corners of the area + * As the lower-left corner, and the area's dimensions + * As the center of the are, and the area's dimensions + * As a corner and an angle and distance to the second corner + * Using legacy format (compatible with standard minetestmapper) + + **Granularity** + + By default, the specified geometry has node granularity, in contrast + with block (16x16) granularity. + + Using block granularity, all coordinates are rounded to the + next multiple of 16. Node granularity keeps the sub-block + coordinates as they are. + + Use `--geometrymode`_ if non-default behavior is desired. + + **Map Shrinking** + + By default, a map of exactly the requested size is generated + (after any granularity adjustment, or adjustments that are + required by scaling). + + Alternatively, the map size can be automatically reduced to + remove empty blocks at its edges. This is the behavior of + the standard version of minetestmapper. + + Use `--geometrymode`_ if non-default behavior is desired. + + **Coordinate Direction** + + The world coordinates 0,0 are the very center of the world. Coordinates + decrease towards the lower-left (south-west) corner of the map, + and they increase towards the upper-right (north-east) corner of the map. + + Note that this differs from the image coordinates, which are 0,0 + in the top-left corner of the map-part of the image, and increase towards + the bottom-right. Image coordinates in the left and top scale areas of + the image are negative. + +Geometry Using Two Corners +-------------------------- + + A geometry using two corners of the area is specified as follows:: + + ,:, + + where ``xcorner1,ycorner1`` are the coordinates of + one corner, and ``xcorner2,ycorner2`` are the coordinates + of the opposite corner of the area. + + The coordinates are interpreted as inclusive: both + the first and the second coordinate will be in the map. + + Example:: + + --geometry -200,-100:200,200 + +Geometry Using Corner and Dimensions +------------------------------------ + + A geometry using a corner of the area and its dimensions is + specified as follows:: + + ,++ + + where ``xoffset,yoffset`` are the coordinates of the + lower-left corner of the area, and ``width`` and ``height`` + are the dimensions of the map. + + Note that ``width`` and/or ``height`` can be negative, making + ``xoffset,yoffset`` another corner of the image. For ease + of using in scripting, the sign of a dimension does not need + to replace the '+'. E.g. the following are valid and equivalent:: + + --geometry -10,-10+11+11 + --geometry -10,10+11-11 + --geometry -10,10+11+-11 + --geometry 10,10-11+-11 + --geometry -10,-10:10,10 + + The following alternate syntax is also supported:: + + x[<+|-xoffset><+|-yoffset>] + + where ``xoffset,yoffset`` are the coordinates of the lower-left + corner of the area. In this case, the offsets can be omitted, + resulting in a map of the requested dimensions, centered at 0,0. + + Examples:: + + --geometry 1000x1200 + --geometry 1000x1200-500+500 + + **Compatibility** + + For backward compatibility, if the ``--centergeometry`` + option is used with a corner-style geometry, then that geometry is + interpreted as a center geometry instead. + +Geometry Using Center and Dimensions +------------------------------------ + + A geometry using the center of the area and its dimensions + is specified as follows:: + + ,:x + + where ``xcenter,ycenter`` are the coordinates of the center + of the area, and ``width`` and ``height`` are its dimensions. + + Example:: + + --geometry 100,100:300x150 + + **Compatibility** + + For backward compatibility, if the ``--cornergeometry`` + option is used with a center-style geometry, then that geometry is + interpreted as a corner geometry instead. + +Geometry using Corner and Angle with Length +------------------------------------------- + + A geometry using one corner (or endpoint of the line) and an + angle with a line length is specified as follows:: + + --drawline ,@+[np] + + This syntax is only supported for 2-dimensional geometries + (e.g. when drawing figures on the map). + + where ``xcorner,ycorner`` are the coordinates of one corner, + ``angle`` is the angle, or compass direction, in degrees of the + line or second corner, and ``length`` is the length of the + line, or the distance to the second corner. + + An angle of 0° is north, 90° is east, 180° is south and 270° is + west. Negative values are accepted as well: -90° is also west, + for instance. + + When the map is scaled, the length may or may not need to be + scaled. Where scaling is possible, a suffix 'n' specifies + that the length is in nodes, and so it scales. A suffix 'p' + specifies a length in pixels, which do not scale. + + Scaling is not possible for figures that are drawn on the map, + e.g. using '--drawmapline'. Use '--drawline' instead if + a figure must scale with the map. + + Example:: + + --drawline 100,100@20+100p + + +Legacy Geometry Format +----------------------- + + The legacy format, compatible with standard version of + minetestmapper is also still supported:: + + :++ + + where ``xoffset,yoffset`` are the coordinates of the lower-left + corner of the area, and ``width`` and ``height`` specify its + dimensions. + + **Compatibility mode** + + This format has a compatibility mode with the standard version of + minetestmapper. + + If the very first geometry option on the command-line is ``--geometry``, + *and* uses this syntax, then block granularity and map shrinking + are enabled, just like standard minetestmapper would. If this is not + desired, then use a different geometry format, or use the option + ``--geometrymode`` to change the behavior. + + Block granularity is also enabled when the obsolete (and otherwise + undocumented) option ``--forcegeometry`` is found first on the command-line. + +Advanced coordinate specification +--------------------------------- + + Coordinates are normally specified as node coordinates. E.g.:: + + --geometry -100,-100:100,100 + + Minetestmapper also supports another way to specify coordinate values: + specifying the minetest block number, and a node. Blocks are 16x16 nodes. + There are two variants: + + The first variant specifies the block number, and a node within that block. + The node must be a value between 0 and 15:: + + # + + E.g.: + + + ``0#2``: node 2 in block 0, i.e. coordinate 2 + + ``1#2``: node 2 in block 1, i.e. coordinate 16+2 = 18 + + ``-10#6``: node 6 in block -10, i.e. coordinate -160+6 = -154 + + ``-3#11``: node 11 in block -3, i.e. coordinate -48+11 = -37 + + The second variant specifies a block and a node offset in the + same direction. I.e. for negative block numbers, the offset is + in the negative direction as well:: + + . + + E.g.: + + ``0.5``: the 5th node from block 0, i.e. coordinate 5 + + ``4.11``: the 11th node from block 4, i.e. coordinate 64+11 = 75 + + ``-0.1``: the 1st node in negative direction from block 0, i.e. coordinate -1 + + ``1.9``: the 9th node in positive direction from block 1, i.e. coordinate 16+9 = 25 + + ``-1.9``: the 9th node in negative direction from block -1, i.e. coordinate -16-9 = -25 + + ``-5.0``: the 0th node in negative direction from block -5, i.e. coordinate -80-0 = -80 + +Colors and Nodes Files +====================== + + In order to know how to render a map, minetestmapper needs a colors and/or + a nodes file. This section documents their format. + + * If a regular map is generated, a 'colors.txt' file is required. + * If a height map is generated, a 'heightmap-nodes.txt' file is required, and + optionally, a 'heightmap-colors.txt' file. + + All three types of files have some commonalities with respect to where minetest + looks form them by default, and with respect to comments and file inclusion. These are + documented in separate paragraphs below: `Colors Files Common Syntax`_, + `Colors Files Search Locations`_ + +Colors.txt Syntax +----------------- + + The colors.txt file contains a list of minetest node names and associated + colors. A minetest world node is converted to at most one pixel on the map, + with a color as specified in the colors.txt file. + + Lines in the colors.txt file have the following syntax:: + + [ []] [flags] + + Where ``red``, ``green``, ``blue``, ``alpha`` and ``t`` are numbers from 0 to 255. + + Examples:: + + default:apple 50 0 0 + default:sandstonebrick 160 144 108 + default:copperblock 110 86 60 + default:water_flowing 49 82 132 192 224 + + **Alpha** + + If a node has an alpha (opacity) value *and* if the value is not 255, + then it will be drawn transparently when `--drawalpha`_ is enabled. The effect + is that the colors of nodes below it shine through. + + Water for instance, is defined as transparent. With transparency enabled, + nodes under water will be visible, but they will acquire a more or + less blueish color from the water. See `--drawalpha`_ for details about + the different ways of computing transparency. + + if a node has an alpha of 0 (fully transparent), then it should normally + never be visible on the map, regardless of its specified color. If there + are any other (types of) nodes below it, then that is what will happen. + If there are not, then that node *will* however be made visible. See + the option `--drawair`_ for a use for this feature. + + **Flags** + + Nodes defined in the colors.txt file can have additional flags, which may + allow them to be treated specially. Flags are specified as a comma-separated + list without spaces. E.g.:: + + example:flags_node 220 255 255 0 air,ignore + + Currently, two flags are defined: + + :air: The `air` flag causes the node to be treated like '``air``' nodes: + by default, such nodes are ignored. The options `--drawair`_ + and `--drawnodes air`_ allow them to be drawn instead. + + :ignore: The `ignore` flag causes the node to be treated like '``ignore``' nodes: + by default, such nodes are ignored. The option `--drawnodes ignore`_ + allows them to be drawn instead. + + Examples:: + + # Default color for air + air 220 220 255 0 + + # Special air variants + specialmod:air 220 220 255 0 air + specialmod:red_air 255 220 220 0 air + specialmod:green_air 220 255 220 0 air + specialmod:blue_air 200 200 255 0 air + + # Nodes to be ignored altogether + default:water_source 39 66 106 224 ignore + default:water_flowing 39 66 106 224 ignore + + **Duplicate Entries** + + If the colors file contains duplicate entries for the same node, in general + the later entry overrides the former. + + There is one exception to this rule: if one color is opaque (no alpha, or + alpha = 255), and one is transparent (alpha < 255), the former will be selected when + ``--drawalpha`` is disabled, and the latter will be selected when ``--drawalpha`` + is enabled:: + + # Entry that will be used without 'drawalpha': + default:water_source 39 66 106 + + # Entry that will be used with 'drawalpha': + default:water_source 78 132 212 64 224 + + This is useful, as colors that look nice in a map without transparency + don't always look nice in a map with transparency. + + **Default** + + A default colors.txt is included with minetestmapper, which includes + the default nodes from minetest_game, as well as nodes from several + popular mods. + + Two variants of the colors.txt are also included: + + ``colors-average-alpha.txt``: + This version is recommended to be used in combination with + ``--drawalpha=average`` + + ``colors-cumulative-alpha.txt``: + This version is recommended to be used in combination with + ``--drawalpha=cumulative`` or ``--drawalpha=cumulative-darken`` + +Heightmap-nodes.txt Syntax +-------------------------- + + The heightmap-nodes.txt file contains a list of minetest node names that + are used to determine the ground height for a height map. + + The highest node of any of the types in this file determines the height at + that point. Any nodes that should be ignored when determining the height, + like obviously air, but probably also default:water_source, and + default:grass_1, or default:torch, should not be in this file. + + As a general directive, plants, trees and any special nodes should not + be included in the file. Stone, sand, gravel, minerals, etc. are the + kinds of nodes that should be included. Normally, water nodes should + probably not be included either. + + This file *can* have the same syntax as the colors.txt file, but the + actual colors will be ignored. Alternatively, a simple list of node + names also suffices:: + + + + [...] + + Examples:: + + default:sandstonebrick + default:copperblock + + **Default** + + A default heightmap-nodes.txt is included with minetestmapper, and + is searched for in the default locations. Alternatively, the file to use + can be specified on the command line with ``--heightmap-nodes `` + +Heightmap-colors.txt Syntax +--------------------------- + + When generating a height map, either a single-color map can be + generated, with colors ranging from black to one specific color, + or a multi-color map can be generated. + + For a multi-color map, a heightmap-colors.txt is needed, which + describes which colors to use. It has lines with the following syntax:: + + + + Where the heights are a number, or the special values ``-oo`` or ``oo`` (for + negative and positive infinity). + + For example:: + + -50 50 255 0 0 0 255 0 + 50 100 0 255 0 0 0 255 + + Which signifies that between height -50 to 50, the color of the nodes will + slowly change from red to green, and between 50 and 100, the color will slowly + change from green to blue. + + It is possible to specify overlapping ranges. The colors they specify will + be averaged:: + + -50 50 255 0 0 0 255 0 + -50 50 0 255 0 0 0 255 + + Between the heights -50 and 50, the colors will change from ``#7f7f00`` to ``#007f7f``. + (and *not* ``#ffff00`` to ``#00ffff``: the colors are *averaged*) + + **Default** + + A default heightmap-colors.txt is included with minetestmapper, and + is searched for in the default locations. An attempt was made to make + a standard minetest world look reasonably good, while at the same time + providing colors for a large height range. + + A second file that is included, called heightmap-colors-rainbow.txt, defines rainbow + colors instead. + + The file to use can also be specified on the command line with + ``--heightmap-colors `` + +Colors Files Common Syntax +-------------------------- + + All three types of colors files (colors.txt, heightmap-nodes.txt and heightmap-colors.txt) + have some syntax elements in common: + + * Any text starting from the first '#' on a line is considered a comment, and is ignored. + * Any empty lines (afer ignoring comments), or lines containing only whitespace are ignored. + + In addition, a colors file may include another colors file using ``@include`` on a line. Any + color definitions from the included file override earlier definitions; any color definitions + after the inclusion point override the colors from the included file. For example in the + following colors.txt file:: + + # Defining default:stone here is useless, as the color from the system + # colors file will override this. + default:stone 71 68 67 + + # Get all colors from the system colors file + # (your system colors file may be located elsewhere!) + @include /usr/share/minetestmapper/colors.txt + + # Use own color for default:dirt_with_grass, overriding the + # one from the system file + default:dirt_with_grass 82 117 54 + + The colors.txt file also supports undefining colors (so that minetestmapper will complain + about unknown nodes). This is achieved by specifying '-' instead of a color:: + + # Get all colors from the system colors file + # (your system colors file may be located elsewhere!) + @include /usr/share/minetestmapper/colors.txt + + # Water is undefined. Minetestmapper will complain + # that there are undefined nodes, and not draw water nodes. + default:water_source - + default:water_flowing - + + # A similar effect might be achieved by defining water + # to have an alpha of 0. Minetest will not complain. + #default:water_source 78 132 212 0 + #default:water_flowing 78 132 212 0 + + # A different, more efficient, alternative may be to flag the + # nodes as 'ignore-type' nodes. Minetest will not complain either. + #default:water_source 78 132 212 225 ignore + #default:water_flowing 78 132 212 225 ignore + +Colors Files Search Locations +----------------------------- + + When minetestmapper needs a colors file (colors.txt, heightmap-nodes.txt and + heightmap-colors.txt), it will search for it in a few predefined locations, which + depend on the system it was built for, and the way minetestmapper was built. + In general, the locations specified below can be searched (ordered from most preferred + to least preferred): + + In order to find out exactly where a specific copy of minetestmapper did look + for its files, use the option ``--verbose-search-colors=2``. + + * The file specified on the command line. If a colors file of the appropriate type + was specified on the command-line, that file is used and no further locations + are searched, even if the file does not exist, or cannot be found. + + * The directory of the world being mapped + + * The directory two levels up from the directory of the world being mapped + (which would be the minetest configuration directory), provided that that directory + contains a file 'minetest.conf' + + * The user's private minetest directory (``$HOME/.minetest``) - if the environment + variable ``$HOME`` exists. (it would probably be called ``%HOME%`` on Windows). + +.. NOTE:: on Windows, it would be more sensible to use ``%USERPROFILE%``, and search + another subdirectory than ``.minetest``. Please advise me about a suitable directory + to search - if at all (I am not a Windows user - I don't even own a copy of Windows...). +.. + + * On Windows only: if minetestmapper can determine its own location, which is + expected to have one of the following formats:: + + \bin\minetestmapper.exe + \minetestmapper.exe + + It searches the following directories: + + * The directory ``\colors\`` + + * The directory ``\`` + + I.e.: if the last directory is '``bin``' (or '``BIN``', etc.), then that part + is removed from the path, and then the resulting path, with and without + '``colors``' appended, is searched. + + * The system directory corresponding to the location where minetestmapper + is installed. Usually, this would be ``/usr/share/games/minetestmapper/`` + or ``/usr/local/share/games/minetestmapper/``. This location was configured + at *compile time*: moving minetestmapper around will not affect the search location. + + * For compatibility: in the current directory as a last resort. + This causes a warning message to be printed. + +Generating colors.txt files +--------------------------- + +While the colors.txt file provided with minetestmapper contains color definitions for a +large number of nodes of different popular mods, it is not, and cannot ever be complete. + +For users on linux and unix(-like) systems (probably including OSX), a few scripts are +provided to aid in the creation of a colors.txt file based on the actual mods the user +is using. Unfortunately, these scripts are still a bit unpolished. They may run without +any problem, and they may generate a perfect colors.txt file on first run. However, it +may also require some effort to get them to produce a good colors.txt file, and the +resulting file may very well need some manual modifications of some colors to make them +look better. + +Please consult `<../dumpnodes/README.dumpnodes>`_ for more information on how to use +the scripts. + +The scripts are not supported on Windows. While it is probably possible to get them +to work, be prepared to do some research on the subject of getting bash scripts to run +on windows, and be prepared to invest some time... Alternatively, be prepared to +rewrite at least the bash script in another scripting language. + +More Information +================ + +More information is available: + +* A feature summary: ``_ (HTML version, if available: ``_) +* Building instructions: ``_ (HTML version, if available: ``_) +* Github repository: ``_ +* Reporting bugs: ``_ + + +.. ----------------- END OF MANUAL ---------------------------- + +.. Shorthands for some links + +.. _known problems: features.rst#known-problems + +.. _--backend: `--backend auto\|sqlite3\|postgresql\|leveldb\|redis`_ +.. _--bgcolor: `--bgcolor `_ +.. _--blockcolor: `--blockcolor `_ +.. _--centergeometry: `--centergeometry `_ +.. _--chunksize: `--chunksize `_ +.. _--colors: `--colors `_ +.. _--cornergeometry: `--cornergeometry `_ +.. _--database-format: `--database-format minetest-i64\|freeminer-axyz\|mixed\|query`_ +.. _--drawnodes: `--drawnodes [no-]air,[no-]ignore`_ +.. _--ignorenodes: `--ignorenodes [no-]air,[no-]ignore`_ +.. _--drawnodes air: `--drawnodes [no-]air,[no-]ignore`_ +.. _--drawnodes ignore: `--drawnodes [no-]air,[no-]ignore`_ +.. _--draw[map]
: `--draw[map]
" []"`_ +.. _--draw[map]circle: `--draw[map]circle " "`_ +.. _--draw[map]ellipse: `--draw[map]ellipse " "`_ +.. _--draw[map]line: `--draw[map]line " "`_ +.. _--draw[map]point: `--draw[map]point ", "`_ +.. _--draw[map]rectangle: `--draw[map]rectangle " "`_ +.. _--draw[map]text: `--draw[map]text ", "`_ +.. _--drawalpha: `--drawalpha[=cumulative\|cumulative-darken\|average\|none]`_ +.. _--drawscale: `--drawscale[=left,top]`_ +.. _--geometry: `--geometry `_ +.. _--geometrymode: `--geometrymode pixel,block,fixed,shrink`_ +.. _--heightmap-colors: `--heightmap-colors[=]`_ +.. _--heightmap-nodes: `--heightmap-nodes `_ +.. _--heightmap-yscale: `--heightmap-yscale `_ +.. _--heightmap: `--heightmap[=]`_ +.. _--heightscale-interval: `--heightscale-interval [,\|:]`_ +.. _--input: `--input `_ +.. _--max-y: `--max-y `_ +.. _--min-y: `--min-y `_ +.. _--origincolor: `--origincolor `_ +.. _--output: `--output `_ +.. _--playercolor: `--playercolor `_ +.. _--prescan-world: `--prescan-world=full\|auto\|disabled`_ +.. _--prescan-world=disabled: `--prescan-world=full\|auto\|disabled`_ +.. _--silence-suggestions: `--silence-suggestions `_ +.. _--sqlite3-limit-prescan-query-size: `--sqlite3-limit-prescan-query-size[=]`_ +.. _--scalecolor: `--scalecolor `_ +.. _--scalefactor: `--scalefactor 1:`_ +.. _--height-level-0: `--height-level-0 `_ +.. _--sidescale-interval: `--sidescale-interval [,\|:]`_ +.. _--tilebordercolor: `--tilebordercolor `_ +.. _--tilecenter: `--tilecenter ,\|world\|map`_ +.. _--tileorigin: `--tileorigin ,\|world\|map`_ +.. _--tiles: `--tiles [+]\|block\|chunk`_ +.. _--verbose-search-colors: `--verbose-search-colors[=]`_ +.. _--verbose: `--verbose[=]`_