Usage¶

py-squaremap-combiner ¶

Python script written to combine the images generated by the squaremap Minecraft plugin. Not affiliated with squaremap or its authors.

The seed used for the world the sample images were created from is -2590089827693666277.

Contents ¶

Features
Installing
Logging
Basic CLI Usage
CLI Options
- Zoom/Detail Levels
- CLI Grid Options

Features¶

Stitch all squaremap-generated images for a given world into a single large map
Export an image of only a specified area of the Minecraft world, by its in-game coordinates
Grid overlay for maps, representing in-game coordinates
- Grid lines and coordinate text can be toggled individually, and styled to a given color, font, and font size

Installing¶

Install the package with pip:

pip install git+https://github.com/svioletg/py-squaremap-combiner.git`

Then, either use it as a command via squaremap-combine…

squaremap-combine run my-tiles overworld --zoom=2 -o worldmap_z2.png

…or import it and use as an API.

from squaremap_combine.combine_core import Combiner

combiner = Combiner('my-tiles')
map_image = combiner.combine('minecraft_overworld', zoom=2) # Returns a PIL.Image.Image object
map_image.save('output.jpg')

Logging¶

This project uses loguru for its logging. Logging is disabled by default for API usage, but enabled at the INFO level when run as a command.

Log files are saved to your user data directory (e.g. C:\Users\<user>\AppData or ~/.local/share) in its logs directory. Run squaremap-combine logs to print its path.

Basic CLI Usage¶

The squaremap-combine run command will stitch together images from a given world/dimension directory into a single map. This directory will be located in your server’s plugins directory, under squaremap/web/tiles/<world>. For example, if your current working directory is where your server JAR is located, the most basic example may look like this:

squaremap-combine run -i plugins/squaremap/web/tiles/minecraft_overworld -o overworld.png

You can alternatively use the sqmapcom command in place of squaremap-combine as a shortcut:

sqmapcom run -i plugins/squaremap/web/tiles/minecraft_overworld -o overworld.png

CLI Options¶

[!NOTE] “List” option types All “[xyz] list” options expect values to be given separated by comma as a single option, e.g. --grid=32,32 or --area=-100,-100,100,100.

Option	Type	Default	Description
`-h/--help`	Flag	N/A	Displays information about every argument / option and their parameters.
`-i/--world`	Directory path	N/A	Path to a world folder subdirectory under squaremap’s “tiles” directory. This is required when using the `run` command.
`-z/--zoom`	Integer	3	The zoom/detail level of tiles to use. Defaults to the highest level of 3, which is 1 block per pixel.
`-o/--out FILEPATH`	File path	`world.png`	Where to save the combined map image. Defaults to the current directory and named after the world folder name.
`--overwite`	Flag	`False`	Allows the script to overwrite an existing file with the same target name if it already exists. By default, if an image with the same path already exists, a numbered suffix is added.
`-a/--area X1,Z1,X2,Z2`	Integer list (4)	Entire rendered map area	A rectangle area of the world to export an image of, separated by commas.
`-c/--crop`	Integer list(2) OR `auto`	`False`	A size in pixels to crop the final image to. If “auto”, trims empty (fully transparent) space surrounding the completed image.
`-g/--grid`	Integer list (2)	`512,512`	Defines the grid interval, which adds grid lines to the image based on Minecraft’s coordinates. Grid overlay can be further customized with the `--grid-*` options below.
`-y/--yes-to-all`	Flag	`False`	Automatically accepts and bypasses all confirmation prompts
`-P/--no-progress-bar`	Flag	`False`	Disables the progress bar, instead logging individual messages per update, useful when running the script as an automated job or similar.

Zoom/Detail Levels¶

Detail	Description
3	1 block per pixel
2	2x2 block area per pixel
1	4x4 block area per pixel
0	8x8 block area per pixel

CLI Grid Options¶

[!NOTE] All options below prefixed with grid- are only used if the --grid option is used; otherwise, they do nothing. Color values can be either a hex code (must be preceded by #) or one of 16 color names defined in the HTML 4.01 spec, with the addition of “clear” for full transparency.

Option	Type	Default	Description
`--grid-lines`	String	`'black 1'`	The color and thickness in pixels to use for grid lines, separated by space.
`--grid-coords`	String	(None)	The string format to use for overlaying grid coordinates, replacing `{x}` and `{z}` with the respective coordinate values, e.g. `"X: {x}, Z: {z}"`. By default, coordinates are not added to the image at all. Note that drawing coordinate text will make creating the image significantly slower, especially with large grids and small grid steps.
`--grid-font`	String/File path, Integer, Color	(None)	The name or file path for a font to use for grid coordinate text, as well as the “point” size to use, separated by comma. If left blank (default), Fira Code SemiBold, which is included in `squaremap_combine`’s installation directory, is used at 32pt in black. Example values include: `'Arial, 64, white'`, `'Consolas, 32, red'`, `'Times New Roman, 48, #ff00ff'`