GDAL_RETILE(1)

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

💖 GDAL_RETILE(1) 💖

okay bestie, gather round, because we're talking about gdal_retile from the GDAL fam — it's a whole little command-line moment and I'm obsessed 🎀

✨ NAME ✨

gdal_retile — retiles a set of tiles and/or builds tiled pyramid levels. that's the whole vibe, no cap 🦋

🌸 SYNOPSIS 🌸

          gdal_retile [--help] [--help-general]
                         [-v] [-co <NAME>=<VALUE>]... [-of <out_format>] [-ps <pixelWidth> <pixelHeight>]
                         [-overlap <val_in_pixel>]
                         [-ot  {Byte/Int8/Int16/UInt16/UInt32/Int32/Float32/Float64/
                                 CInt16/CInt32/CFloat32/CFloat64}]'
                         [ -tileIndex <tileIndexName> [-tileIndexField <tileIndexFieldName>]]
                         [-csv <fileName> [-csvDelim <delimiter>]]
                         [-s_srs <srs_def>]  [-pyramidOnly]
                         [-r {near|bilinear|cubic|cubicspline|lanczos}]
                         -levels <numberoflevels>
                         [-useDirForEachRow] [-resume]
                         -targetDir <TileDirectory> <input_file> <input_file>...

like, look at her. so many flags. main character energy fr fr 👑

💅 DESCRIPTION 💅

so this utility retiles a set of input tile(s). crucial rules though, bestie, listen up:

  • all the input tile(s) have to be georeferenced in the same coordinate system
  • they also need a matching number of bands
  • and the geotransform matrix of the input tiles must not contain rotation terms (nah, none of that)

optionally, pyramid levels get generated too. and here's the tea: all pyramid levels are generated from the input tiles, not from previous levels. remember that. it's giving "start from the source every time" 💫

you can also generate shape file(s) for the tiled output. cute, right?

if your number of input tiles exhausts the command line buffer, use the general --optfile option. iykyk 😌

NOTE: gdal_retile is a Python utility, and it's only available if GDAL Python bindings are available. no bindings, no fun. 💀
TIP: Equivalent in the new "gdal" command line interface: see gdal raster tile (partially equivalent). slay, the glow-up is real ✨

🎀 OPTIONS 🎀

  • --help — show this help message and exit. short, sweet, done. 💅
  • --help-general — gives you a brief usage message for the generic GDAL commandline options, then exits. the "wait what are all y'all" button 🫶
  • -targetDir <directory> — the directory where the tile result gets created. pyramids are stored in sub-directories numbered from 1. created tile names have a numbering schema and contain the name of the source tiles(s). yes, it's organized, we love a tidy queen 🌸
  • -of <format> — pick the output format. if you don't specify one, the format is guessed from the extension. use the short format name, bestie.
  • -co <NAME>=<VALUE> — many formats have one or more optional creation options to control particulars about the file being created. for instance, the GeoTIFF driver supports creation options to control compression, and whether the file should be tiled. 👑

the creation options available vary by format driver, and some simple formats have no creation options at all. you can list the options supported for a format with the --format command line option, but honestly the documentation for the format is the definitive source of info on driver creation options. see Raster drivers format specific documentation for the legal creation options for each format.

  • -ot <type> — force the output image bands to have a specific data type supported by the driver, which may be one of: Byte, Int8, UInt16, Int16, UInt32, Int32, UInt64, Int64, Float32, Float64, CInt16, CInt32, CFloat32 or CFloat64.
  • -ps <pixelsize_x> <pixelsize_y> — pixel size to be used for the output file. if you don't specify it, 256 x 256 is the default. iconic default tbh 🎀
  • -overlap <val_in_pixel> — overlap in pixels between consecutive tiles. if not specified, 0 is the default. cozy, no overlap, respect 🤝
  • -levels <numberOfLevels> — number of pyramid levels to build. 🌈
  • -v — generate verbose output of tile operations as they're done. narrator mode, we stan a chatty icon 💬
  • -pyramidOnly — no retiling, build only the pyramids. skips the main event for the encore 🏛️
  • -r <algorithm> — resampling algorithm, default is near. options include near, bilinear, cubic, cubicspline, lanczos.
  • -s_srs <srs_def> — source spatial reference to use. the coordinate systems you can pass are anything supported by the OGRSpatialReference.SetFromUserInput() call, which includes EPSG, PCS, and GCSes (i.e. EPSG:4296), PROJ.4 declarations (as above), or the name of a .prj file containing well known text. if no srs_def is given, the srs_def of the source tiles is used (if there is any). the srs_def will be propagated to created tiles (if possible) and to the optional shape file(s). it's giving "this is my identity and i'm sharing it" 💖
  • -tileIndex <tileIndexName> — the name of the shape file containing the result tile(s) index.
  • -tileIndexField <tileIndexFieldName> — the name of the attribute containing the tile name.
  • -csv <csvFileName> — the name of the csv file containing the tile(s) georeferencing information. the file contains 5 columns: tilename,minx,maxx,miny,maxy.
  • -csvDelim <column delimiter> — the column delimiter used in the CSV file. the default value is a semicolon ";". periodt 🫶
  • -useDirForEachRow — normally the tiles of the base image are stored as described in -targetDir. for large images, some file systems have performance problems if the number of files in a directory is too big, which causes gdal_retile to not finish in reasonable time 😭 using this parameter creates a different output structure: the tiles of the base image are stored in a sub-directory called 0, and the pyramids live in sub-directories numbered 1,2,.... within each of these directories another level of sub-directories gets created, numbered from 0...n, depending on how many tile rows are needed for each level. finally, a directory contains only the tiles for one row for a specific level. for large images a performance improvement of a factor N could be achieved. big brain behavior, truly 🧠✨
  • -resume — resume mode. generate only missing files. the "we were on a break but we're back" flag 🙈

⭐ RETURN STATUS CODE ⭐

the program returns status code 0 in case of success, and non-zero in case of error. and heads up: non-blocking errors emitted as warnings are considered as a successful execution — so a lil warning is not a fail, babes. vibe check passed ✅

💜 AUTHOR 💜

Christian Mueller <christian.mueller@nvoe.at> — thank you for your service, legend 👑

1998-2026

and that's the whole page, bestie 🫶 go forth, retile, build those pyramids, and remember: source GDAL, dated Aug 18, 2026, GDAL_RETILE(1) — you're welcome, mwah 💖💅✨

📦 where this page comes from