gdal2tiles.py

Generate TMS tiles for the zoom levels 2 to 5 of a raster dataset

$ gdal2tiles.py --zoom 2-5 [path/to/input.tif] [path/to/output_directory]

$ gdal2tiles.py --zoom 2-5 --xyz [path/to/input.tif] [path/to/output_directory]

gdal2tiles.py [options] <input_file> [<output_directory>]

<input_file>
    The path to the input raster dataset (e.g., a GeoTIFF).

<output_directory>
    The directory where the generated tile pyramid will be stored. If not specified, a directory named after the input file (without extension) will be created.

-p PROFILE, --profile=PROFILE
    Defines the tile cutting profile. Common options include mercator (for Web Mercator/EPSG:3857, default), geodetic (for EPSG:4326/WGS84), and raster (for pixel-based tiles without reprojection).

-s SRS, --s_srs=SRS
    Specifies the Source Spatial Reference System for the input dataset, if it's not correctly defined in the file metadata (e.g., EPSG:4326, PROJ.4 string).

-t SRS, --t_srs=SRS
    Defines the Target Spatial Reference System for the output tiles. Defaults to EPSG:3857 (Web Mercator) if the profile is 'mercator'.

-z ZOOM, --zoom=ZOOM
    Specifies the zoom levels to generate. Can be a single level (e.g., '10'), a range (e.g., '2-12'), or 'all' to generate all relevant zoom levels from the base imagery.

-r METHOD, --resampling=METHOD
    Sets the resampling method used for generating tiles at different zoom levels. Options include average (default), near (nearest neighbor), bilinear, cubic, cubicspline, lanczos, and mode.

-e, --resume
    Enables resume mode, skipping previously generated and existing tiles in the output directory. Useful for continuing interrupted jobs or updating specific parts of a tile set.

-a VALUE, --alpha=VALUE
    Sets a custom alpha band value for transparent areas. Useful for handling nodata values or adding transparency.

--processes=NUM
    Specifies the number of parallel processes (CPU cores) to use for tile generation. Can significantly speed up processing on multi-core systems.

--webviewer=VIEWER
    Generates a simple HTML web viewer for the tiles. Options are openlayers, leaflet, all (both), or none (default).

--xyz
    Forces the output tile structure to be XYZ (Google Maps compatible) instead of TMS, even if another profile might imply TMS.

--tms
    Forces the output tile structure to be TMS (Tile Map Service) instead of XYZ.

--title=TITLE
    Provides a title for the generated web viewer page.

--copyright=TEXT
    Adds copyright information to the web viewer page.

--url=URL
    Specifies a base URL for the tiles, useful when serving them from a different location.

--tile-size=PIXELS
    Sets the size of the output tiles in pixels (e.g., 256 for standard web maps). Default is 256.

--src-nodata=VALUE
    Defines the nodata value for the input dataset. Pixels with this value will be treated as transparent.

--force-alpha
    Ensures an alpha band is added to the output tiles, even if the source image doesn't have one.

-v, --verbose
    Enables verbose output, showing more detailed progress messages during tile generation.

-q, --quiet
    Suppresses most output messages, showing only critical errors.

-h, --help
    Displays the help message and exits.

gdal2tiles.py is a versatile Python script included with the GDAL (Geospatial Data Abstraction Library) project.

Its primary purpose is to convert large geospatial raster datasets, such as GeoTIFFs, satellite imagery, or aerial photographs, into a pyramid of efficiently organized image tiles. These tiles are typically arranged in an XYZ (Google Maps compatible) or TMS (Tile Map Service) structure, optimized for display in web mapping applications like OpenLayers, Leaflet, or the Google Maps API.

The tool handles complex operations including re-projection (e.g., to Web Mercator, EPSG:3857), resampling of imagery at different zoom levels, and precise tile cutting. By pre-generating these tiles, web applications can display vast amounts of geospatial data quickly and smoothly, loading only the necessary tiles for the current viewport and zoom level, significantly enhancing user experience for interactive web maps.

When processing very large input files or generating many zoom levels, gdal2tiles.py can be memory-intensive. Using the --processes option is recommended for multi-core systems, but too many processes with large tile sizes can exhaust RAM. Ensure the input dataset's Spatial Reference System (SRS) is correctly defined or explicitly set with -s SRS to avoid projection errors. Interrupting a process without --resume can lead to incomplete tile sets.

The generated tiles are organized hierarchically in the <output_directory> following a z/x/y.(png|jpg) convention (for XYZ profiles) or z/x/y.(png|jpg) with Y inverted (for TMS profiles). z represents the zoom level, x the column index, and y the row index of the tile. This structure allows web mapping clients to easily request and display tiles based on their current view.

For optimal performance with large datasets, consider:
- Using the --processes option to utilize multiple CPU cores.
- Specifying a limited --zoom range if not all levels are needed.
- Using --resume to pick up interrupted jobs or update existing tile sets.
- Ensuring sufficient disk space for the output, as tile sets can be very large.
- Using efficient input formats (e.g., Cloud Optimized GeoTIFF) for faster reads.

When --webviewer is used, gdal2tiles.py creates a simple HTML file (e.g., openlayers.html or leaflet.html) in the <output_directory>. This HTML file serves as a basic, ready-to-use map viewer that displays the generated tiles. It's an excellent way to quickly preview the output and verify the tiling process without needing to set up a full web mapping application.

gdal2tiles.py emerged as a critical utility within the GDAL (Geospatial Data Abstraction Library) ecosystem, driven by the proliferation of web mapping applications (e.g., Google Maps, OpenStreetMap) in the mid-2000s. As web mapping platforms adopted the tiled map service paradigm, a robust tool was needed to prepare vast raster datasets for efficient online delivery.

Originally developed as a Python script leveraging GDAL's powerful C/C++ backend, it became a de facto standard for converting geospatial imagery into web-ready tile pyramids. Its continuous development reflects ongoing improvements in GDAL, offering support for new formats, projections, and performance optimizations, making it an indispensable tool for geospatial web developers and data providers.

gdalinfo(1), gdalwarp(1), gdal_translate(1), gdalbuildvrt(1)