GDAL-RASTER-TILE(1)

📦
version 3.13.3 · 7 versions
, in alpine 3.24, arch rolling, ubuntu stonking

🎀 GDAL-RASTER-TILE(1) 🎀

okay so bestie, welcome to the gdal-raster-tile manual page — it lives in the GDAL manual, section 1. This one is giving main character energy and we're gonna get through all of it together. 💅

✨ NAME ✨

gdal-raster-tile — generates tiles in separate files from a raster dataset. 🌈

🚨 Oh and heads up: added in version 3.11. She's new, she's fresh, she ate. 👑

🌸 SYNOPSIS 🌸

Usage: gdal raster tile [OPTIONS] <INPUT> <OUTPUT>

Generate tiles in separate files from a raster dataset.

💖 Positional arguments 💖

  • -i, --dataset, --input <INPUT> — the input raster datasets you're feeding in. [required] [not available in pipelines] ⚠️ (yes, you literally cannot do this without it, bestie)
  • -o, --output <OUTPUT> — the output directory where all the little tile babies live. [required]

🧚 Common Options 🧚

  • -h, --help — display the help message and exit. 🙈 the classic.
  • --json-usage — display usage as a JSON document and exit. machine-readable slay.
  • --config <KEY>=<VALUE> — a configuration option. [may be repeated]
  • -q, --quiet — quiet mode, meaning no progress bar and no warning message. [not available in pipelines] 🤫

👑 Options 👑

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — the output format. (default: PNG)
  • --co, --creation-option <KEY>=<VALUE> — a creation option. [may be repeated]
  • --tiling-scheme <TILING-SCHEME> — the tiling scheme. TILING-SCHEME=raster|WebMercatorQuad|WorldCRS84Quad|WorldMercatorWGS84Quad|GoogleCRS84Quad|PseudoTMS_GlobalMercator|GlobalGeodeticOriginLat270|LINZAntarticaMapTilegrid|APSTILE|CBMTILE|NZTM2000 (default: WebMercatorQuad)
  • --min-zoom <MIN-ZOOM> — minimum zoom level.
  • --max-zoom <MAX-ZOOM> — maximum zoom level.
  • --min-x <MIN-X> — minimum tile X coordinate.
  • --max-x <MAX-X> — maximum tile X coordinate.
  • --min-y <MIN-Y> — minimum tile Y coordinate.
  • --max-y <MAX-Y> — maximum tile Y coordinate.
  • --no-intersection-ok — whether a dataset extent that does not intersect the tile matrix is only a warning. 🫶 (basically: is the "uh oh, no intersection" situation just a lil warning?)
  • -r, --resampling <RESAMPLING> — resampling method used for the max zoom. RESAMPLING=nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum (default: cubic)
  • --overview-resampling <OVERVIEW-RESAMPLING> — resampling method used for the overviews. OVERVIEW-RESAMPLING=nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum
  • --convention <CONVENTION> — tile numbering convention: xyz (counting from the top) or tms (counting from the bottom). CONVENTION=xyz|tms (default: xyz)
  • --tile-size <TILE-SIZE> — override the default tile size.
  • --add-alpha — whether to force adding an alpha channel. mutually exclusive with --no-alpha 💀
  • --no-alpha — whether to disable adding an alpha channel. mutually exclusive with --add-alpha
  • --output-nodata <OUTPUT-NODATA> — output nodata value.
  • --skip-blank — do not generate blank tiles. ✋ blank tiles stay home.
  • --metadata <KEY>=<VALUE> — add a metadata item to the output tiles. [may be repeated]
  • --copy-src-metadata — whether to copy metadata from the source dataset.
  • --aux-xml — generate .aux.xml sidecar files when needed.
  • --kml — generate KML files.
  • --resume — generate only the missing files. 🏃‍♀️
  • -j, --num-threads <NUM-THREADS> — number of jobs (or ALL_CPUS). (default: ALL_CPUS)
  • --parallel-method <PARALLEL-METHOD> — parallelization method: thread, spawn, or fork. PARALLEL-METHOD=thread|spawn|fork

🌟 Advanced Options 🌟

  • --if, --input-format <INPUT-FORMAT> — input formats. [may be repeated] [not available in pipelines]
  • --oo, --open-option <KEY>=<VALUE> — open options. [may be repeated] [not available in pipelines]

🍓 Advanced Resampling Options 🍓

  • --excluded-values <EXCLUDED-VALUES> — tuples of values (like <R>,<G>,<B> or (<R1>,<G1>,<B1>),(<R2>,<G2>,<B2>)) that must be ignored as contributing source pixels during (average) resampling.
  • --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 to be used as the target pixel value. (default: 50)
  • --nodata-values-pct-threshold <NODATA-VALUES-PCT-THRESHOLD> — minimum percentage of source pixels that must be set at one of nodata (or alpha=0 or any other way to express a transparent pixel) to cause the target pixel value to be transparent. (default: 100)

🦋 Publication Options 🦋

  • --webviewer <WEBVIEWER> — web viewer to generate. WEBVIEWER=none|all|leaflet|openlayers|mapml|stac (default: all) [may be repeated]
  • --url <URL> — the URL address where the generated tiles are going to be published.
  • --title <TITLE> — title of the map.
  • --copyright <COPYRIGHT> — copyright for the map.
  • --mapml-template <MAPML-TEMPLATE> — filename of a template mapml file where variables will be substituted.

💜 DESCRIPTION 💜

okay so here's the whole vibe, bestie. gdal raster tile generates a directory with small tiles and metadata in it, following the OGC WMTS Specification. ✨

On top of that, simple web pages with viewers based on OpenLayers and Leaflet are generated as well — so literally 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. 🚀 The only thing you have to do is upload the generated directory onto a web server. periodt.

It generates PNG files by default, but other output formats can be selected (JPEG, WEBP, GTiff, etc.). 🎨

⚠️ Careful though: not all formats support non-Byte data types. JPEG and WEBP only support Byte. PNG supports Byte and UInt16. GeoTiff can support all data types. 💀

It can also use a tiling scheme fully adapted to the input raster, in terms of origin and resolution, when using the raster tiling scheme. In that scheme, tiles at the maximum zoom level will have the same resolution as the raster. 👑

Starting with GDAL 3.12, gdal raster tile can be used as the last step of a pipeline. 🌈

🌈 PROGRAM-SPECIFIC OPTIONS 🌈

okay bestie these are the actual fun ones, the flags that make this whole tiling thing go 💅

  • --aux-xml — makes .aux.xml sidecar files whenever they're needed.
  • --add-alpha — forces an alpha channel to be added. lowkey it gets added by default anyway, unless the source dataset has a nodata value and the output format supports it. so this is you overriding the vibe check.
  • --copy-src-metadata — copies the metadata from the source dataset over into your output tiles. yes queen, inherit the lore.
  • --convention xyz|tms — which way do the tiles number themselves:
    • xyz (the default): numbering starts from the top, exactly like the OGC Web Map Tiling Specification (WMTS). 🫶
    • tms: numbering starts from the bottom, like the OSGeo Tile Map Service (TMS) Specification.
  • --output-nodata <NODATA> — the nodata value for the output. that's it, that's the tweet.
  • -i, --input <INPUT> — your input raster dataset. this one is required, no skipping it 🙅‍♀️
  • --kml — generates Google Earth SuperOverlay metadata. ⚠️ but heads up: it is not compatible with tiling schemes that have non-power-of-two zoom levels. not compatible!! at all!!
  • --max-x <MAX-X> — max tile X coordinate, at the maximum zoom level. use it to restrict the tiling process.
  • --max-y <MAX-Y> — max tile Y coordinate, at the maximum zoom level. also there to restrict the tiling process.
  • --max-zoom <MAX-ZOOM> — the biggest zoom level to generate. if you don't say anything, this gets figured out by comparing the resolution of your input dataset against the closest resolution in the tile matrix list of the tile matrix set. it's giving ✨automatic✨
  • --metadata <KEY>=<VALUE> — drops a metadata item onto the output tiles. and listen — this one may be repeated. stack them like accessories 💅
  • --min-x <MIN-X> — min tile X coordinate, at the maximum zoom level. restricts the tiling process.
  • --min-y <MIN-Y> — min tile Y coordinate, at the maximum zoom level. restricts the tiling process.
  • --min-zoom <MIN-ZOOM> — the smallest zoom level to generate. if you leave it out, it's equal to --max-zoom.
  • --no-alpha — turns OFF the creation of an alpha channel.
  • --no-intersection-ok — makes it so that the dataset extent not intersecting the tile matrix is only a warning. otherwise, by default, it's an error if that happens. so this flag is basically "bestie i know, chill" 😌
  • -j, --num-threads <value> — how many jobs run at once. default: however many CPUs get detected.
  • -o, --output <OUTPUT> — output directory. required! and important: the directory itself will be created if it doesn't exist, but its parent directory must exist. don't ask me why, that's just the rule 🎀
  • --overview-resampling nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum — the resampling method used to generate zoom levels lower than the maximum zoom level. it defaults to whatever --resampling is, if --resampling isn't specified.
  • --parallel-method thread|spawn|fork — added in version GDAL: 3.12 ✨ here's how the parallelizing goes:
    • thread uses multi-threading, meaning the parallelized tasks all run within the same process.
    • spawn launches child gdal sub-processes. spawn can get you better "scaling", but it requires the gdal binary to actually be available. GDAL will try to locate it, but you can also set the GDAL_PATH configuration option to point at the directory where the gdal binary lives.
    • fork is a variant of spawn, using the system call fork, without executing the gdal binary. this method is not available on Windows. and on Unix systems where it is available, it's not recommended to use it on multithreaded processes — especially ones where other threads are doing GDAL operations — because it can potentially cause deadlocks. 💀 yeah. noted.

if --parallel-method isn't specified, GDAL auto-decides which method is most appropriate: it opts for spawn if the gdal binary can be located and a sufficient number of tiles per job are being generated, and otherwise falls back to fork on Linux, MacOSX or FreeBSD (only if no other thread is running), and otherwise falls back to thread. it's choosing for you, trust the process 🧚

  • -r, --resampling nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum — the resampling method used for the maximum zoom level, and also for lower zoom levels if --overview-resampling isn't specified. defaults to cubic.
  • --resume — only generates the missing files. perfect for when you interrupt a previous run and want to restart it. the comeback tour 🫶
  • --skip-blank — don't generate fully blank/transparent tiles. we're not keeping those, they didn't serve.
  • --tile-size <PIXELS> — width and height of a tile, in pixels. default is 256 for the default tiling schemes. fun fact: setting it higher lets you generate higher DPI tile sets 👑
  • --tiling-scheme <TILING-SCHEME> — the tile cutting scheme. defaults to WebMercatorQuad (also known as Google Maps compatible).

these are the base profiles available:

  • raster: CRS = CRS of the raster, tile size = 256 pixels, raster coverage at all zoom levels.
  • WebMercatorQuad: CRS = EPSG:3857 ("WGS 84 / Pseudo-Mercator"), tile size: 256 pixels, whole world coverage at zoom level 0, one single tile at zoom level 0.
  • WorldCRS84Quad: CRS = EPSG:4326 ("WGS 84"), tile size: 256 pixels, whole world coverage at zoom level 0, two side-by-side tiles at zoom level 0.
  • WorldMercatorWGS84Quad: CRS = EPSG:3395 ("WGS 84 / World Mercator"), tile size: 256 pixels, whole world coverage at zoom level 0, one single tile at zoom level 0. think of it as a variant of WebMercatorQuad, except it's fully conformal on the WGS84 ellipsoid. slay.
  • GoogleCRS84Quad: CRS = EPSG:4326 ("WGS 84"), tile size: 256 pixels, whole world coverage at zoom level 0, one single tile at zoom level 0 whose first and last 64 lines are blank (the top origin of the tile is a pseudo latitude of 180 degree, and its bottom -180 degree).
  • PseudoTMS_GlobalMercator: CRS = EPSG:3857 ("WGS 84 / Pseudo-Mercator"), tile size: 256 pixels, whole world coverage at zoom level 0, 2x2 tiles at zoom level 0. this is equivalent to WebMercatorQuad, but with the zoom level shifted by one.
  • LINZAntarticaMapTileGrid: LINZ Antarctic Map Tile Grid (Ross Sea Region). see tms_LINZAntarticaMapTileGrid.json
  • APSTILE: Alaska Polar Stereographic-based tiled coordinate reference system for the Arctic region. see tms_MapML_APSTILE.json
  • CBMTILE: Lambert Conformal Conic-based tiled coordinate reference system for Canada. see tms_MapML_CBMTILE.json
  • NZTM2000: LINZ NZTM2000 Map Tile Grid. see tms_NZTM2000.json

and bestie, extra tiling schemes get discovered from tms_XXXX.json files placed in the GDAL data directory. there's always more 👀

🧪 Advanced Resampling Options 🧪

these are the deep cuts. the ones where resampling gets very specific.

  • --excluded-values <EXCLUDED-VALUES> — a comma-separated tuple of values (so, typically "R,G,B") that get ignored as contributing source pixels during resampling. the number of values in the tuple must equal the number of bands, excluding the alpha band. you can specify several tuples of excluded values using the "(R1,G1,B2),(R2,G2,B2)" syntax. ⚠️ this is only taken into account for average resampling. the concept is a bit similar to nodata/alpha, but the key difference is: pixels matching one of the excluded value tuples are still considered as valid when determining the target pixel validity/density. sneaky but intentional 💅

Added in version 3.11.1.

  • --excluded-values-pct-threshold <EXCLUDED-VALUES-PCT-THRESHOLD> — the minimum percentage of source pixels that must be set at one of the --excluded-values to cause the excluded value, the one that's in the majority among source pixels, to be used as the target pixel value. default value is 50(%).

Added in version 3.11.1.

  • --nodata-values-pct-threshold <NODATA-VALUES-PCT-THRESHOLD> — the minimum percentage of source pixels that must be at nodata (or alpha=0, or any other way to express a transparent pixel) to cause the target pixel value to be transparent. default value is 100 (%), which means a target pixel is transparent only if all contributing source pixels are transparent. ⚠️ only taken into account for average resampling.

Added in version 3.11.1.

🌐 Publication Options 🌐

  • --webviewer none|all|leaflet|openlayers|mapml|stac — which web viewer to generate. defaults to all. these viewers get created at the root of the output directory. and stac generates a stacta.json file, following the Spatio-Temporal Asset Catalog Tiled Assets specification, and that can be opened by the STACTA driver. iconic 🎀
  • --url — the URL address where the generated tiles are going to be published.
  • --title <TITLE> — the title of the map. name her 💖
  • --copyright <COPYRIGHT> — the copyright for the map.

🗺️ MapML options 🗺️

bestie listen: the MapML webviewer can only be generated if --convention is set to the default value xyz. that's the rule, no exceptions 🙈

these are the profiles that are supported:

  • WebMercatorQuad: mapped to the OSMTILE MapML tiling scheme
  • GoogleCRS84Quad: mapped to the WGS84 MapML tiling scheme
  • APSTILE: from the tms_MapML_APSTILE.json data file
  • CBMTILE: from the tms_MapML_CBMTILE.json data file

the generated MapML file in the output directory is mapml.mapl.

the options available are:

  • --mapml-template <filename> — the filename of a template mapml file where variables will be substituted. if you don't specify one, the generic template_tiles.mapml file from the GDAL data resources gets used instead. ✨

also heads up: the --url option is ALSO used to substitute ${URL} in the template MapML file. so don't forget about it, it's pulling double duty 🫶

✨ STANDARD OPTIONS ✨

okay bestie these are the glow-up options that basically every gdal command shares, so they're lowkey the universal cheat codes 💅

  • --co, --creation-option <NAME>=<VALUE> — soooo many formats have these little optional creation options that let you control the exact particulars of the file you're creating. Like, the GeoTIFF driver has creation options for controlling compression and whether the file should be tiled. Cute right? 🎀

You can repeat this one as many times as you want. ✨

The creation options that actually exist vary by format driver, and some of the simple little formats have literally no creation options at all (they're giving minimalist 🧚). You can list the options a format supports with the --formats command line option, but fr fr the documentation for the format itself is the definitive source of info on driver creation options. Head to the Raster drivers format specific documentation for the legal creation options for each format. no cap 🔥

  • --if, --input-format <format> — the format/driver name you want the tool to attempt to open your input file(s) with. ngl you generally don't need to specify it, but it's super handy for skipping automatic driver detection when the auto-detection is failing to pick the right driver. You can repeat this option several times to hand it a whole squad of candidate drivers. 👑
Careful though bestie — it does not force those drivers to open the dataset. Some drivers have requirements on file extensions, so it might still ghost you. 💀

May be repeated.

  • --oo, --open-option <NAME>=<VALUE> — dataset open option baby, and it's format specific. 🌸

May be repeated.

  • -f, --of, --format, --output-format <OUTPUT-FORMAT> — which output raster format are we serving today? 💖 Allowed values may be given by:
gdal --formats | grep raster | grep rw | sort

Defaults to PNG. periodt. ✨

🫶 RETURN STATUS CODE

The program returns status code 0 when it's slaying (success), and non-zero when something went wrong (error). Note that non-blocking errors emitted as warnings still count as a successful execution — they're just the tool being a lil dramatic, not actually failing you. 😭

🌈 EXAMPLES

💫 Example 1: Generate PNG tiles with WebMercatorQuad tiling scheme for zoom levels 2 to 5.

gdal raster tile --min-zoom=2 --max-zoom=5 input.tif output_folder

💫 Example 2: Retile a raster using its origin and resolution

gdal raster tile --tiling-scheme raster input.tif output_folder

💫 Example 3: Creating a tiled dataset, compatible of the Spatio-Temporal Asset Catalog Tiled Assets specification, using Cloud-Optimized GeoTIFF metatiles of dimension 4096x4096.

gdal raster tile --format COG --tile-size 4096 input.tif output_folder

💫 Example 4: Mosaic on-the-fly several input files and tile that mosaic.

gdal raster pipeline ! mosaic input*.tif ! tile output_folder

👑 AUTHOR

Even Rouault <even.rouault@spatialys.com>

1998-2026

and that's the whole vibe bestie, we ate and left absolutely no crumbs 💅✨ this was GDAL-RASTER-TILE(1) from Aug 18, 2026 — go make some tiles, you absolute main character 🦋💖

📦 where this page comes from