From the Command-line

After installation, minetestmapper is started as follows from the command-line:

c:\games\minetestmapper\bin\minetestmapper.exe ^
    --input <world-directory> ^
    --output <image-file-name.png>

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 <world-directory> ^
    --output <image-file-name.png> ^
    --colors <filename>

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 <world-directory> ^
    --output <image-file-name.png> ^
    --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.

Option Syntax

The options below use the following syntax:

some-text:	Plain text should be typed as shown.
<placeholder>:	This is a placeholder. The entire text (including '<' and '>') must be replaced with whatever it designates. E.g. <height> 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.
<geometry>:	Specify a geometry. See Geometry Syntax
<color>:	Specify a color. See Color Syntax

Basic options:

• --help : Print an option summary
• --version : Print version ID of minetestmapper
• --input <world-dir> : Specify the world directory (mandatory)
• --output <image filename> : Specify the map file name (mandatory)
• --colors <filename> : Specify the colors file location and/or name.
• --heightmap[=<color>] : Generate a height map instead of a regular map
• --heightmap-nodes <filename> : Specify the nodes list for the height map
• --heightmap-colors <filename> : Specify the color definition file for the height map
• --geometry <geometry> : Specify the desired map dimensions
• --scalefactor <factor> : Specify the scaling factor for the map
• --progress : Print progress information while generating the map
• --verbose[=<n>] : Report statistics about the world and the generated map

Area options:

• --scalefactor <factor> : Specify the scaling factor for the map
• --geometry <geometry> : Specify the desired map dimensions
• --cornergeometry <geometry> : Suggest interpretation as a corner + dimensions
• --centergeometry <geometry> : Suggest interpretation as center + dimensions
• --min-y <y> : Specify the minumum depth of nodes to be included
• --max-y <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[=<color>] : Generate a height map instead of a regular map
• --heightmap-nodes <filename> : Specify the nodes list for the height map
• --heightmap-colors <filename> : Specify the color definition file for the height map
• --heightmap-yscale <factor> : Scale the vertical dimensions by a factor
• --height-level-0 <height> : Set the '0' level differently for determining height map colors
• --drawheightscale : Draw a height scale at the bottom of the map
• --heightscale-interval <major>[,|:<minor>] : Use custom major and minor intervals in the height scale.

Colors for specific areas or parts of the map:

• --bgcolor <color> : Specify the background color for the image
• --blockcolor <color> : Specify the color for empty mapblocks
• --scalecolor <color> : Specify the color for text in the scales on the side
• --origincolor <color> : Specify the color for drawing the map origin (0,0)
• --playercolor <color> : Specify the color for drawing player locations
• --tilebordercolor <color> : 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 <major>[,|:<minor>] : Use custom major and minor intervals in the scale.
• --heightscale-interval <major>[,|:<minor>] : 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 <tilesize>[+<border>]|block|chunk : Draw a grid of the specified size on the map
• --tileorigin <x>,<y>|world|map : Specify the coordinates of one tile's origin (lower-left corner)
• --tilecenter <x>,<y>|world|map : Specify the coordinates of one tile's center
• --tilebordercolor <color> : Specify the color for drawing tile borders
• --chunksize <size> : Specify or override the chunk size (usually 5 blocks)

Drawing figures on the map

Using world coordinates:

• --drawpoint "<x>,<y> <color>" : Draw a point (single pixel) on the map
• --drawline "<geometry> <color>" : Draw a line on the map
• --drawarrow "<geometry> <color>" : Draw an arrow on the map
• --drawcircle "<geometry> <color>" : Draw a circle on the map
• --drawellipse "<geometry> <color>" : Draw an ellipse on the map
• --drawrectangle "<geometry> <color>" : Draw a rectangle on the map
• --drawtext "<x>,<y> <color> <text>" : Write some text on the map

Same figures using map/image coordinates (0,0 is the top-left corner of the map)

• --drawmappoint "<x>,<y> <color>" : Draw a point (single pixel) on the map
• --drawmapline "<geometry> <color>" : Draw a line on the map
• --drawmaparrow "<geometry> <color>" : Draw an arrow on the map
• --drawmapcircle "<geometry> <color>" : Draw a circle on the map
• --drawmapellipse "<geometry> <color>" : Draw an ellipse on the map
• --drawmaprectangle "<geometry> <color>" : Draw a rectangle on the map
• --drawmaptext "<x>,<y> <color> <text>" : Write some text on the map

Feedback / information options:

• --help : Print an option summary
• --version : Print version ID of minetestmapper
• --verbose[=<n>] : 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 <types> : 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[=<blocks>] : Limit the size of individual block list queries during a world prescan.

--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 <color>

Specify the background color for the image. See Color Syntax below.

Two maps with different background:

--blockcolor <color>

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:

--centergeometry <geometry>

Suggest interpreting a geometry as center coordinates and dimensions. If possible.

See also --geometry

--chunksize <size>

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 <file>

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 <geometry>

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]<figure> "<geometry> <color> [<text>]"

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<figure> is used, the geometry specifies world coordinates; if --drawmap<figure> 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 "<geometry> <color>"

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]<figure> for details.

An example circle:

--draw[map]ellipse "<geometry> <color>"

Draw an ellipse on the map. This is a synonym for --draw[map]circle.

See --draw[map]<figure> for details.

--draw[map]line "<geometry> <color>"

Draw a line on the map, with the given geometry and color.

See --draw[map]<figure> for details.

An example line:

--draw[map]arrow "<geometry> <color>"

Draw an arrow on the map, with the given geometry and color.

See --draw[map]<figure> for details.

An example arrow:

--draw[map]point "<x>,<y> <color>"

Draw a point on the map, at the given location, using the given color.

See --draw[map]<figure> for details.

An example point (red, in te white area):

--draw[map]rectangle "<geometry> <color>"

Draw a reactangle on the map, with the given geometry and color.

See --draw[map]<figure> for details.

An example rectangle:

--draw[map]text "<x>,<y> <color> <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]<figure> for more details.

Example text:

--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:

--drawheightscale

If drawing a height map (--heightmap), draw a height scale below the image.

A height map with scale:

--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:

--draworigin

Draw a circle at the world origin (coordinates 0,0)

The color can be set with --origincolor.

An image with world origin drawn:

--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:

--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:

--geometry <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:

--heightmap-colors[=<file>]

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 <file>

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 <factor>

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:

--heightmap[=<color>]

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:

--heightscale-interval <major>[,|:<minor>]

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:

--height-level-0 <level>

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 <world_path>

Specify the world to map.

This option is mandatory.

--max-y <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 <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:

--origincolor <color>

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 <output_image.png>

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 <color>

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 <color>

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:<n>

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

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:

--sidescale-interval <major>[,|:<minor>]

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:

--silence-suggestions <types>

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[=<blocks>]

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 <duration>

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 <color>

Specify the color to use for drawing tile borders.

Use --tiles to enable drawing tiles.

See also Color Syntax

--tilecenter <x>,<y>|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 <x>,<y>|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 <tilesize>[+<border>]|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:

--verbose-search-colors[=<n>]

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[=<n>]

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.