README

NAME
  maptiles - converts an image to map tiles

SYNOPSIS
  ./maptiles <input_image> [<options>] <output_directory>

DESCRIPTION
  Converts an image to map tiles to be used in Google Maps, Leaflet and other
  map rendering software.

  Version:   v4.0.1
  Homepage:  https://github.com/jahed/maptiles
  Donate:    https://jahed.dev/donate

OPTIONS
  <input_image>
    Image to convert into tiles. Must exist. Must be square, otherwise
    see --square option.

  <output_directory>
    Output directory. Must NOT exist, to avoid polluting existing directories.

  -f, --format <format>
    Tile format (e.g. 'png'). Defaults to <input_image> file extension.

  -b, --background <background>
    Can be any ImageMagick-compatible colour. Defaults to 'none' (transparent).
    See: https://imagemagick.org/script/color.php

  -o, --optimise (lossy|lossless)
    Optimises tiles depending on the <format>.
    * png uses pngquant (lossy) or optipng (lossless)
    * jpg uses jpegtran (lossless)
    Lossy optimisations may cause a size increase depending on each tile's
    complexity. Only use it for maps which store a lot of detail per tile.

  -s, --square
    Converts a non-square <input_image> into a square one, using whichever
    dimension is largest and centering the image.

  -j, --json <base>
    Creates a TileJSON v2.2.0 file. <base> is used to create the tiles URL:
      <base><output_directory>/{z}/{x}/{y}.<format>
    Use a placeholder such as '{b}' or '' to complete the URL later.
    See: https://github.com/mapbox/tilejson-spec/tree/master/2.2.0

  -h, --help
    Prints this help message.

  --version
    Prints the name and version.

OUTPUT
  Tiles in the <output_directory> will take the format of:
    <output_directory>/{z}/{x}/{y}.<format>

  {z} will start at 0 and go up to the maximum zoom possible for the
  <input_image> rounding up to the next zoom level. An <input_image> with
  dimensions 2048x2048 will go up to 4 whereas an image with 3000x3000 will go
  up to 5. This is done to make the most out of the level of detail in the image
  without enlargening too much.

  Each tile has a dimension of 256x256 and each {z} goes up in
  dimensions of 2 to the power of {z} (i.e. 1x1, 2x2, 4x4, 8x8, etc.).
  So overall, for each zoom level, the resulting map resolution will be 256x256,
  512x512, 1024x1024, 2048x2048 and so on.

  If you're using Leaflet, I suggest you set this maximum zoom as your
  map.maxNativeZoom so you can have higher zoom levels without the need to
  download larger, low quality, upscaled tiles. Alternatively, use the TileJSON.

EXAMPLES
  Take a detailed image and create optimised tiles to save space.
    ./maptiles detailed_map.png --optimise lossy ./tiles

  Take an image, square it with a red background and output it as JPG tiles.
    ./maptiles map.png --square --format jpg --background #ff0000 ./tiles

DEPENDENCIES
  Required
    ImageMagick  https://www.imagemagick.org
    Bash         https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29

  Optional
    pngquant    https://pngquant.org/
    optipng     http://optipng.sourceforge.net/
    jpegtran    https://jpegclub.org/jpegtran/

COPYRIGHT
  Copyright (C) 2024 Jahed Ahmed

  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU Affero General Public License as published by
  the Free Software Foundation, either version 3 of the License, or any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU Affero General Public License for more details.

  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.