`core` module¶

class squaremap_combine.core.Combiner(tiles_dir: str | ~pathlib.Path, *, grid_step: int | None = None, style: ~squaremap_combine.core.CombinerStyle = CombinerStyle(bg_color=Color<#00000000>(0, 0, 0, 0), grid_line_color=Color<#000000ff>(0, 0, 0, 255), grid_line_size=1, grid_text_font=PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/squaremap-combine/envs/latest/lib/python3.12/site-packages/squaremap_combine/asset/FiraCode-SemiBold.ttf'), grid_text_pt=32, grid_text_stroke_size=6, grid_text_stroke_color=Color<#000000ff>(0, 0, 0, 255), grid_text_fill_color=Color<#ffffffff>(255, 255, 255, 255), grid_coords_format=''), confirm_fn: ~collections.abc.Callable[[str], bool] | None = None, progress_bar: bool = False)¶

Takes a squaremap tiles directory path and can export stitched map images.

__init__(tiles_dir: str | ~pathlib.Path, *, grid_step: int | None = None, style: ~squaremap_combine.core.CombinerStyle = CombinerStyle(bg_color=Color<#00000000>(0, 0, 0, 0), grid_line_color=Color<#000000ff>(0, 0, 0, 255), grid_line_size=1, grid_text_font=PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/squaremap-combine/envs/latest/lib/python3.12/site-packages/squaremap_combine/asset/FiraCode-SemiBold.ttf'), grid_text_pt=32, grid_text_stroke_size=6, grid_text_stroke_color=Color<#000000ff>(0, 0, 0, 255), grid_text_fill_color=Color<#ffffffff>(255, 255, 255, 255), grid_coords_format=''), confirm_fn: ~collections.abc.Callable[[str], bool] | None = None, progress_bar: bool = False) → None¶

Parameters:

tiles_dir –

A path to a directory in the same format as what squaremap automatically generates. Example:

tiles (<- what this path should point to)
├───minecraft_overworld
|   ├───0
|   ├───1
|   ├───2
|   └───3
├───minecraft_the_nether
|   ├───0
|   ├───1
|   ├───2
|   └───3
└───minecraft_the_end
    ├───0
    ├───1
    ├───2
    └───3

grid_step – The interval that should be used for things like drawing grid lines or coordinates onto the finished image. Will be treated as an interval of blocks, not pixels on the image.
style – CombinerStyle instance to define styling rules with.
confirm_fn – A Callable to use in cases where any Combiner functions wish to ask for confirmation before continuing, which must return True to continue.
progress_bar – Whether to show a progress bar for any functions that support it.

combine(world: str | ~pathlib.Path, *, zoom: int, area: ~squaremap_combine.geo.Rect | tuple[int, int, int, int] | None = None, crop: tuple[int, int] | ~typing.Literal['auto'] | None = None, tile_ext: str = '*', grid_step: int | None = None, style: ~squaremap_combine.core.CombinerStyle | dict[str, ~typing.Any] | None = None, grid_progress_interval_secs: float = 1.0, draw_grid_fn: ~collections.abc.Callable[[~PIL.Image.Image, ~squaremap_combine.geo.Grid, ~squaremap_combine.geo.Grid, ~squaremap_combine.core.CombinerStyle, float], None] = <staticmethod(<function Combiner._draw_grid_overlay>)>) → Image¶

Combine the given world (dimension) tile images into one large map.

Parameters:

world – Name of the world to use the tiles of, as a subdirectory of the instance’s tiles_dir attribute. Alternatively, if given as a Path object, the path will be used as-is and will ignore tiles_dir for this run.
zoom – The zoom level to use, from 0 (lowest detail, 8x8 blocks per pixel) to 3 (highest detail 1 block per pixel).
area – Specifies an area of the world to export. If None, all tiles available are used.
crop –
A size to crop the final image to, centering on the center of area; or, 'auto' can be given to trim excess empty space around the map’s borders, and crop it to the resulting visible area. In this case, the image is no longer guaranteed to be centered on area.

Note

Only tiles within area will be used, regardless of this value—if crop is larger than the rendered area (and by extension, not 'auto'), blank space will be left surrounding the map.
tile_ext – The file extension used for the tile images. By default, combine() will attempt to use all existing files under the relevant tiles directory that have any file suffix, and are not directories.
grid_step – A grid step value to use instead of the Combiner instance’s .step value, if not None.
style – A CombinerStyle instance to use instead of the Combiner instance’s style instance, if not None. Can also be a dict of key-value pairs, in which case only the specified keys’ values are overridden, and the Combiner instance’s style is use as a fallback.
grid_progress_interval_secs – At what interval to log grid overlay drawing updates. Set to 0 or lower to disable.
draw_grid_fn –
A function to call which will handle drawing the grid overlay on top of the map image being created. Will receive these arguments: - PIL.Image.Image: The map image object to be drawn onto. - Grid: The “world grid”, representing the coordinates of the Minecraft

world.
- Grid: The “canvas grid” for the image, a rectangle of 0, 0 to the
  size of the image.
- CombinerStyle: The style object to use, that being this Combiner
  instance’s .style attribute after being updated with or replaced by the style parameter of the combine method.
- float: In the default drawing function
  (_draw_grid_overlay()), this is used as an interval of seconds at which to log updates on the drawing progress.

Returns image:

The final stitched image, a PIL.Image.Image object.

Raises:

NotADirectoryError – Raised if world is not a directory or does not exist.

grid_step: int¶: Interval of blocks to use for the grid overlay. Grid overlay is disabled if set to 0.

tiles_dir: Path¶: The squaremap tiles directory to source tile images from.

Defines styling rules for Combiner-generated map images.

Parameters:

bg_color – Background color to use for empty areas of the map. Default: #00000000 (clear)
grid_line_color – Color for grid overlay lines. Default: #000000ff (black)
grid_line_size – Thickness of grid overlay lines. Default: 1
grid_text_font – Font to use for grid overlay coordinate text. Default: Fira Code (included with package)
grid_text_pt – Point size to use for grid overlay coordinate text. Default: 32
grid_text_stroke_size – Stroke (outline) size to use for grid overlay coordinate text. Default: 20% (rounded down) of grid_text_pt
grid_text_stroke_color – Stroke (outline) color to use for grid overlay coordinate text. Default: #000000ff (black)
grid_text_fill_color – Color to use for grid overlay coordinate text. Default: #ffffffff (white)
grid_coords_format – String to use for coordinate text, which expects {x} and {y} specifiers to format. Default: ''

core module¶

`core` module¶