gdal2tiles - Man Page

gdal2tiles [--help] [--help-general]
              [-p <profile>] [-r resampling] [-s <srs>] [-z <zoom>]
              [-e] [-a nodata] [-v] [-q] [-h] [-k] [-n] [-u <url>]
              [-w <webviewer>] [-t <title>] [-c <copyright>]
              [--processes=<NB_PROCESSES>] [--mpi] [--xyz]
              [--tilesize=<PIXELS>] --tiledriver=<DRIVER> [--tmscompatible]
              [--excluded-values=<EXCLUDED_VALUES>]
              [--excluded-values-pct-threshold=<EXCLUDED_VALUES_PCT_THRESHOLD>]
              [--nodata-values-pct-threshold=<NODATA_VALUES_PCT_THRESHOLD>]
              [-g <googlekey] [-b <bingkey>] <input_file> [<output_dir>] [<COMMON_OPTIONS>]

This utility generates a directory with small tiles and metadata, following the OSGeo Tile Map Service Specification. Simple web pages with viewers based on Google Maps, OpenLayers and Leaflet are generated as well - so anybody can comfortably explore your maps on-line and you do not need to install or configure any special software (like MapServer) and the map displays very fast in the web browser. You only need to upload the generated directory onto a web server.

GDAL2Tiles also creates the necessary metadata for Google Earth (KML SuperOverlay), in case the supplied map uses EPSG:4326 projection.

World files and embedded georeferencing is used during tile generation, but you can publish a picture without proper georeferencing too.

NOTE:

Inputs with non-Byte data type (i.e. Int16, UInt16,...) will be clamped to the Byte data type, causing wrong results. To avoid this it is necessary to rescale input to the Byte data type using gdal_translate utility.

NOTE:

Config options of the input drivers may have an effect on the output of gdal2tiles. An example driver config option is GDAL_PDF_DPI, which can be found at Configuration options

NOTE:

gdal2tiles is a Python utility, and is only available if GDAL Python bindings are available.

--help

Show this help message and exit

--help-general

Gives a brief usage message for the generic GDAL commandline options and exit.

-p <PROFILE>, --profile=<PROFILE>

Tile cutting profile (mercator, geodetic, raster) - default 'mercator' (Google Maps compatible).

Starting with GDAL 3.2, additional profiles are available from tms_XXXX.json files placed in GDAL data directory (provided all zoom levels use same origin, tile dimensions, and resolution between consecutive zoom levels vary by a factor of two).

-r <RESAMPLING>, --resampling=<RESAMPLING>

Resampling method (average, near, bilinear, cubic, cubicspline, lanczos, antialias, mode, max, min, med, q1, q3) - default 'average'.

-s <SRS>, --s_srs=<SRS>

The spatial reference system used for the source input data.

--xyz

Generate XYZ tiles (OSM Slippy Map standard) instead of TMS. In the default mode (TMS), tiles at y=0 are the southern-most tiles, whereas in XYZ mode (used by OGC WMTS too), tiles at y=0 are the northern-most tiles.

New in version 3.1.

-d, --tmscompatible

When using the geodetic profile, specifies the base resolution as 0.703125 or 2 tiles at zoom level 0.

-z <ZOOM>, --zoom=<ZOOM>

Zoom levels to render (format:'2-5', '10-' or '10').

-e, --resume

Resume mode. Generate only missing files.

-a <NODATA>, --srcnodata=<NODATA>

Value in the input dataset considered as transparent. If the input dataset had already an associate nodata value, it is overridden by the specified value.

-v, --verbose

Generate verbose output of tile generation.

Starting with GDAL 3.7, that verbose output is emitted through the logging.getLogger("gdal2tiles") object.

-x, --exclude

Exclude transparent tiles from result tileset.

-q, --quiet

Disable messages and status to stdout

New in version 2.1.

--processes=<NB_PROCESSES>

Number of parallel processes to use for tiling, to speed-up the computation.

New in version 2.3.

--mpi

Assume launched by mpiexec, enable MPI parallelism and ignore --processes. Requires working MPI environment and the MPI for Python (mpi4py) package. User should set GDAL_CACHEMAX to an appropriate cache size per process based on memory per node and the number of processes launched per node.

New in version 3.5.

--tilesize=<PIXELS>

Width and height in pixel of a tile. Default is 256.

New in version 3.1.

--tiledriver=<DRIVER>

Which output driver to use for the tiles, determines the file format of the tiles. Currently PNG, WEBP and JPEG (JPEG added in GDAL 3.9) are supported. Default is PNG. Additional configuration for the WEBP and JPEG drivers are documented below.

New in version 3.6.

--excluded-values=<EXCLUDED_VALUES>

Comma-separated tuple of values (thus typically "R,G,B"), that are ignored as contributing source * pixels during resampling. The number of values in the tuple must be the same as the number of bands, excluding the alpha band. Several tuples of excluded values may be specified using the "(R1,G1,B2),(R2,G2,B2)" syntax. Only taken into account by Average currently. This concept is a bit similar to nodata/alpha, but the main difference is that pixels matching one of the excluded value tuples are still considered as valid, when determining the target pixel validity/density.

New in version 3.9.

--excluded-values-pct-threshold=EXCLUDED_VALUES_PCT_THRESHOLD

Minimum percentage of source pixels that must be set at one of the --excluded-values to cause the excluded value, that is in majority among source pixels, to be used as the target pixel value. Default value is 50(%)

New in version 3.9.

--nodata-values-pct-threshold=<NODATA_VALUES_PCT_THRESHOLD>

Minimum percentage of source pixels that must be at nodata (or alpha=0 or any other way to express transparent pixel) to cause the target pixel value to be transparent. Default value is 100 (%), which means that a target pixel is transparent only if all contributing source pixels are transparent. Only taken into account for average resampling.

New in version 3.9.

-h, --help

Show help message and exit.

--version

Show program's version number and exit.

Basic example:

gdal2tiles --zoom=2-5 input.tif output_folder

MapML generation:

gdal2tiles --zoom=16-18 -w mapml -p APSTILE --url "https://example.com" input.tif output_folder

MPI example:

mpiexec -n $NB_PROCESSES gdal2tiles --mpi --config GDAL_CACHEMAX 500 --zoom=2-5 input.tif output_folder

Klokan Petr Pridal <klokan@klokan.cz>

1998-2024