.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "GDAL-RASTER-TILE" "1" "May 06, 2025" "" "GDAL"
.SH NAME
gdal-raster-tile \- Generate tiles in separate files from a raster dataset
.sp
Added in version 3.11.

.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Usage: gdal raster tile [OPTIONS] <INPUT> <OUTPUT>

Generate tiles in separate files from a raster dataset.

Positional arguments:
  \-i, \-\-input <INPUT>                                  Input raster dataset [required]
  \-o, \-\-output <OUTPUT>                                Output directory [required]

Common Options:
  \-h, \-\-help                                           Display help message and exit
  \-\-json\-usage                                         Display usage as JSON document and exit
  \-\-config <KEY>=<VALUE>                               Configuration option [may be repeated]
  \-\-progress                                           Display progress bar

Options:
  \-f, \-\-of, \-\-format, \-\-output\-format <OUTPUT\-FORMAT>  Output format (default: PNG)
  \-\-co, \-\-creation\-option <KEY>=<VALUE>                Creation option [may be repeated]
  \-\-tiling\-scheme <TILING\-SCHEME>                      Tiling scheme. TILING\-SCHEME=raster|WebMercatorQuad|WorldCRS84Quad|WorldMercatorWGS84Quad|GoogleCRS84Quad|PseudoTMS_GlobalMercator|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 dataset extent not intersecting tile matrix is only a warning
  \-r, \-\-resampling <RESAMPLING>                        Resampling method for 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 for overviews. OVERVIEW\-RESAMPLING=nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum
  \-\-convention <CONVENTION>                            Tile numbering convention: xyz (from top) or tms (from bottom). CONVENTION=xyz|tms (default: xyz)
  \-\-tile\-size <TILE\-SIZE>                              Override 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
  \-\-dst\-nodata <DST\-NODATA>                            Destination nodata value
  \-\-skip\-blank                                         Do not generate blank tiles
  \-\-metadata <KEY>=<VALUE>                             Add metadata item to output tiles [may be repeated]
  \-\-copy\-src\-metadata                                  Whether to copy metadata from source dataset
  \-\-aux\-xml                                            Generate .aux.xml sidecar files when needed
  \-\-kml                                                Generate KML files
  \-\-resume                                             Generate only missing files
  \-j, \-\-num\-threads <NUM\-THREADS>                      Number of jobs (or ALL_CPUS) (default: ALL_CPUS)

Advanced Options:
  \-\-oo, \-\-open\-option <KEY>=<VALUE>                    Open options [may be repeated]
  \-\-if, \-\-input\-format <INPUT\-FORMAT>                  Input formats [may be repeated]

Publication Options:
  \-\-webviewer <WEBVIEWER>                              Web viewer to generate. WEBVIEWER=none|all|leaflet|openlayers|mapml (default: all) [may be repeated]
  \-\-url <URL>                                          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
.EE
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
\fBgdal raster tile\fP generates a directory with small tiles and metadata,
following the OGC WMTS Specification. Simple web pages with viewers based on
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.
.sp
It generates PNG files by default, but other output formats can be selected
(JPEG, WEBP, GTiff, etc.). Note that 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.
.sp
It can also use a tiling scheme fully adapted to the input raster, in terms of
origin and resolution, when using the \fBraster\fP tiling scheme. In that scheme,
tiles at the maximum zoom level will have the same resolution as the raster.
.SS Standard options
.INDENT 0.0
.TP
.B \-i, \-\-input <INPUT>
Input raster dataset [required]
.UNINDENT
.INDENT 0.0
.TP
.B \-o, \-\-output <OUTPUT>
Output directory [required]
.sp
The directory will be created if it does not exist, but its parent
directory must exist.
.UNINDENT
.INDENT 0.0
.TP
.B \-f, \-\-of, \-\-format, \-\-output\-format <OUTPUT\-FORMAT>
Which output raster format to use. Allowed values may be given by
\fBgdal \-\-formats | grep raster | grep rw | sort\fP
.sp
Defaults to PNG.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-co <NAME>=<VALUE>
Many formats have one or more optional creation options that can be
used to control particulars about the file created. For instance,
the GeoTIFF driver supports creation options to control compression,
and whether the file should be tiled.
.sp
May be repeated.
.sp
The creation options available vary by format driver, and some
simple formats have no creation options at all. A list of options
supported for a format can be listed with the
\fI\%\-\-formats\fP
command line option but the documentation for the format is the
definitive source of information on driver creation options.
See \fI\%Raster drivers\fP format
specific documentation for legal creation options for each format.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tiling\-scheme <TILING\-SCHEME>
Tile cutting scheme. Defaults to WebMercatorQuad (also known as Google Maps compatible).
.sp
The following base profiles are available:
.INDENT 7.0
.IP \(bu 2
\fBraster\fP: CRS = CRS of raster, tile size = 256 pixels, raster coverage at all zoom levels.
.IP \(bu 2
\fBWebMercatorQuad\fP: CRS = EPSG:3857 (\(dqWGS 84 / Pseudo\-Mercator\(dq), tile size: 256 pixels, whole world coverage at zoom level 0, one single tile at zoom level 0.
.IP \(bu 2
\fBWorldCRS84Quad\fP: CRS = EPSG:4326 (\(dqWGS 84\(dq), tile size: 256 pixels, whole world coverage at zoom level 0, two side\-by\-side tiles at zoom level 0
.IP \(bu 2
\fBWorldMercatorWGS84Quad\fP: CRS = EPSG:3395 (\(dqWGS 84 / World Mercator\(dq), tile size: 256 pixels, whole world coverage at zoom level 0, one single tile at zoom level 0. This can be seen as a variant of WebMercatorQuad except that it is fully conformal on the WGS84 ellipsoid.
.IP \(bu 2
\fBGoogleCRS84Quad\fP: CRS = EPSG:4326 (\(dqWGS 84\(dq), 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).
.IP \(bu 2
\fBPseudoTMS_GlobalMercator\fP: CRS = EPSG:3857 (\(dqWGS 84 / Pseudo\-Mercator\(dq), tile size: 256 pixels, whole world coverage at zoom level 0, 2x2 tiles at zoom level 0. This is equivalent to \fBWebMercatorQuad\fP, but with the zoom level shifted by one.
.IP \(bu 2
\fBLINZAntarticaMapTileGrid\fP: LINZ Antarctic Map Tile Grid (Ross Sea Region). See \X'tty: link https://github.com/OSGeo/gdal/blob/master/gcore/data/tms_LINZAntarticaMapTileGrid.json'\fI\%tms_LINZAntarticaMapTileGrid.json\fP\X'tty: link'
.IP \(bu 2
\fBAPSTILE\fP: Alaska Polar Stereographic\-based tiled coordinate reference system for the Arctic region. See \X'tty: link https://github.com/OSGeo/gdal/blob/master/gcore/data/tms_MapML_APSTILE.json'\fI\%tms_MapML_APSTILE.json\fP\X'tty: link'
.IP \(bu 2
\fBCBMTILE\fP: Lambert Conformal Conic\-based tiled coordinate reference system for Canada. See \X'tty: link https://github.com/OSGeo/gdal/blob/master/gcore/data/tms_MapML_CBMTILE.json'\fI\%tms_MapML_CBMTILE.json\fP\X'tty: link'
.IP \(bu 2
\fBNZTM2000\fP: LINZ NZTM2000 Map Tile Grid. See \X'tty: link https://github.com/OSGeo/gdal/blob/master/gcore/data/tms_NZTM2000.json'\fI\%tms_NZTM2000.json\fP\X'tty: link'
.UNINDENT
.sp
Additional tiling schemes are discovered from \fBtms_XXXX.json\fP files placed in the GDAL data directory.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-min\-zoom <MIN\-ZOOM>
Minimum zoom level to generate. If not specified, equal to \fI\%\-\-max\-zoom\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-max\-zoom <MIN\-ZOOM>
Maximum zoom level to generate. If not specified, this will be determined by
comparing the resolution of the input dataset with the closest resolution in
the list of tile matrix of the tile matrix set.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-min\-x <MIN\-X>
Minimum tile X coordinate, at maximum zoom level. Can be set to restrict
the tiling process.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-min\-y <MIN\-Y>
Minimum tile Y coordinate, at maximum zoom level. Can be set to restrict
the tiling process.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-max\-x <MAX\-X>
Maximum tile X coordinate, at maximum zoom level. Can be set to restrict
the tiling process.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-max\-y <MAX\-Y>
Maximum tile Y coordinate, at maximum zoom level. Can be set to restrict
the tiling process.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-intersection\-ok
Whether the dataset extent not intersecting the tile matrix is only a warning.
Otherwise, by default, an error will be emitted if that occurs.
.UNINDENT
.INDENT 0.0
.TP
.B \-r, \-\-resampling nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum
Resampling method used to generate maximum zoom level, and also lower zoom
levels if \fI\%\-\-overview\-resampling\fP is not specified.
Defaults to \fBcubic\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-overview\-resampling nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum
Resampling method used to generate zoom levels lower than the maximum zoom
level. Defaults to the value of \fI\%\-\-resampling\fP is not specified.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-convention xyz|tms
Tile numbering convention:
.INDENT 7.0
.IP \(bu 2
\fBxyz\fP (default): from top, as in OGC Web Map Tiling Specification (WMTS)
.IP \(bu 2
\fBtms\fP: from bottom, as in OSGeo Tile Map Service (TMS) Specification.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-tile\-size <PIXELS>
Width and height of a tile, in pixels. Default is 256 for default tiling schemes.
Setting it to a higher value enables generating higher DPI tile sets.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-add\-alpha
Whether to force adding an alpha channel. An alpha channel is added by default,
unless the source dataset has a nodata value and the output format supports it.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-no\-alpha
Disable the creation of an alpha channel.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-dstnodata <DSTNODATA>
Destination nodata value.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-skip\-blank
Do not generate fully blank/transparent tiles.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-metadata <KEY>=<VALUE>
Add metadata item to output tiles [may be repeated]
.UNINDENT
.INDENT 0.0
.TP
.B \-\-copy\-src\-metadata
Whether to copy metadata from source dataset into output tiles.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-aux\-xml
Generate .aux.xml sidecar files when needed
.UNINDENT
.INDENT 0.0
.TP
.B \-\-kml
Generate Google Earth SuperOverlay metadata.
Not compatible with tiling schemes with non\-power\-of\-two zoom levels.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-resume
Generate only missing files. Can be used when interrupting a previous run
to restart it.
.UNINDENT
.INDENT 0.0
.TP
.B \-j, \-\-num\-threads <value>
Number of jobs to run at once.
Default: number of CPUs detected.
.UNINDENT
.SS Publication Options
.INDENT 0.0
.TP
.B \-\-webviewer none|all|leaflet|openlayers|mapml
Web viewer to generate. Defaults to \fBall\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-url
URL address where the generated tiles are going to be published.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-title <TITLE>
Title of the map.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-copyright <COPYRIGHT>
Copyright for the map.
.UNINDENT
.SS MapML options
.sp
MapML webviewer can only be generated if \fI\%\-\-convention\fP is set to the
default value \fBxyz\fP\&.
.sp
The following profiles are supported:
.INDENT 0.0
.IP \(bu 2
\fBWebMercatorQuad\fP: mapped to OSMTILE MapML tiling scheme
.IP \(bu 2
\fBGoogleCRS84Quad\fP: mapped to WGS84 MapML tiling scheme
.IP \(bu 2
\fBAPSTILE\fP: from the tms_MapML_APSTILE.json data file
.IP \(bu 2
\fBCBMTILE\fP: from the tms_MapML_CBMTILE.json data file
.UNINDENT
.sp
The generated MapML file in the output directory is \fBmapml.mapl\fP
.sp
Available options are:
.INDENT 0.0
.TP
.B \-\-mapml\-template <filename>
Filename of a template mapml file where variables will
be substituted. If not specified, the generic
template_tiles.mapml file from GDAL data resources
will be used
.UNINDENT
.sp
The \fI\%\-\-url\fP option is also used to substitute \fB${URL}\fP in the template MapML file.
.SH EXAMPLES
.SS Example 1: Generate PNG tiles with WebMercatorQuad tiling scheme for zoom levels 2 to 5.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
gdal raster tile \-\-min\-zoom=2 \-\-max\-zoom=5 input.tif output_folder
.EE
.UNINDENT
.UNINDENT
.SS Example 2: Retile a raster using its origin and resolution
.INDENT 0.0
.INDENT 3.5
.sp
.EX
gdal raster tile \-\-tiling\-scheme raster input.tif output_folder
.EE
.UNINDENT
.UNINDENT
.SH AUTHOR
Even Rouault <even.rouault@spatialys.com>
.SH COPYRIGHT
1998-2025
.\" Generated by docutils manpage writer.
.