GDALTRANSFORM(1)

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

💖 NAME 💖

gdaltransform — it transforms coordinates, and honestly? it ate. 👑

Ok so quick vibe check bestie: this is the manual page for gdaltransform, part of the GDAL family of command-line tools. It reads coordinates from standard input, works its literal magic on them, and writes them back out. That's the whole plot. 🦋

✨ SYNOPSIS ✨

Usage: gdaltransform [--help] [--help-general]
       [-i] [-s_srs <srs_def>] [-t_srs <srs_def>] [-to >NAME>=<VALUE>]...
       [-s_coord_epoch <epoch>] [-t_coord_epoch <epoch>]
       [-ct <proj_string>] [-order <n>] [-tps] [-rpc] [-geoloc]
       [-gcp <pixel> <line> <easting> <northing> [elevation]]...
       [-output_xy] [-E] [-field_sep <sep>] [-ignore_extra_input]
       [<srcfile> [<dstfile>]]

(yes, -to >NAME>=<VALUE> — that's exactly how it's written, don't come for me, I'm just the messenger 💀)

🌸 DESCRIPTION 🌸

So the tea ☕: the gdaltransform utility reprojects a list of coordinates into any supported projection, including GCP-based transformations. Any projection. She's versatile like that. 💅

  • --help — shows you this help message and then exits. bye bestie 👋
  • --help-general — gives you a brief lil' usage message for the generic GDAL commandline options, and then exits. ✨
  • -s_srs <srs_def> — sets the source spatial reference. And what coordinate systems can you pass, you ask? Anything that OGRSpatialReference.SetFromUserInput() supports, and that's a whole buffet: EPSG PCS and GCSes (i.e. EPSG:4296), PROJ.4 declarations (as above), or the name of a .prj file containing well known text. 🗺️
  • -s_coord_epoch <epoch> — added in version 3.8. Assigns a coordinate epoch, linked with the source SRS. It's useful when the source SRS is a dynamic CRS. Only taken into account if -s_srs is used, no cap. ⚠️ And before PROJ 9.4, -s_coord_epoch and -t_coord_epoch were mutually exclusive, due to lack of support for transformations between two dynamic CRS. periodt.
  • -t_srs <srs_def> — sets the target spatial reference. Same deal as the source one, bestie: anything OGRSpatialReference.SetFromUserInput() supports — EPSG PCS and GCSes (i.e. EPSG:4296), PROJ.4 declarations (as above), or the name of a .prj file containing well known text. 🫶
  • -t_coord_epoch <epoch> — added in version 3.8. Assigns a coordinate epoch, linked with the output SRS. Useful when the output SRS is a dynamic CRS. Only taken into account if -t_srs is used. ⚠️ Before PROJ 9.4, -s_coord_epoch and -t_coord_epoch were mutually exclusive, because there was no support for transformations between two dynamic CRS.
  • -ct <string> — a PROJ string (single step operation, or a multiple step string starting with +proj=pipeline), a WKT2 string describing a CoordinateOperation, or a urn:ogc:def:coordinateOperation:EPSG::XXXX URN that overrides the default transformation from the source to the target CRS. 🌀 Heads up: it must take into account the axis order of the source and target CRS. Added in version 3.0.
  • -to <NAME>=<VALUE> — sets a transformer option suitable to pass to GDALCreateGenImgProjTransformer2(). ✨
  • -order <n> — the order of polynomial used for warping (1 to 3). The default is to select a polynomial order based on the number of GCPs. math girlies rise 🧮
  • -tps — forces use of the thin plate spline transformer based on available GCPs.
  • -rpc — forces use of RPCs. 📸
  • -geoloc — forces use of Geolocation Arrays.
  • -i — inverse transformation: going from destination back to source. 🔄
  • -gcp <pixel> <line> <easting> <northing> [<elevation>] — hands over a GCP to be used for the transformation (generally you need three or more of these, so stock up). And note: pixel and line need not be integers. 👀
  • -output_xy — restricts output to "x y" instead of "x y z". keep it minimal, love that for her.
  • -ignore_extra_input — added in version 3.9. Set this flag to avoid extra non-numeric content at the end of input lines being appended to the output lines. 🚫
  • -E — added in version 3.9. Enables Echo mode, where input coordinates get prepended to the output lines. so it's giving... receipts. 🪞
  • -field_sep <sep> — added in version 3.9. Defines the field separator, to separate different values. It defaults to the space character. ✂️
  • <srcfile> — raster dataset with source projection definition or GCPs. If it's not given, source projection/GCPs are read from the command-line -s_srs or -gcp parameters. ⚠️ Important: only the SRS and/or GCPs of this input file is taken into account, and not its pixel content. she's a look, not a vibe. 💅
  • <dstfile> — raster dataset with destination projection definition.

Coordinates are read as pairs, triples (for 3D,) or (since GDAL 3.0.0,) quadruplets (for X,Y,Z,time) of numbers per line from standard input, transformed, and written out to standard output in the same way. All transformations offered by gdalwarp are handled, including gcp-based ones. 😤

Starting with GDAL 3.9, additional non-numeric content (typically point name) at the end of an input line will also be appended to the output line, unless the -ignore_extra_input is added.

⚠️ Note that input and output must always be in decimal form. There is currently no support for DMS input or output. 🚨 Don't try it. She will not help you.

If an input image file is provided, input is in pixel/line coordinates on that image. If an output file is provided, output is in pixel/line coordinates on that image. 🖼️

🎀 RETURN STATUS CODE 🎀

The program returns status code 0 in case of success, and non-zero in case of error (non-blocking errors emitted as warnings are considered as a successful execution). So like, a warning is not a fail, bestie. exhale. 😮‍💨

🔥 EXAMPLES 🔥

💫 Reprojection Example 💫

Simple reprojection from one projected coordinate system to another:

gdaltransform -s_srs EPSG:28992 -t_srs EPSG:31370
177502 311865

Produces the following output in meters in the "Belge 1972 / Belgian Lambert 72" projection:

244296.724777415 165937.350217148 0

📸 Image RPC Example 📸

The following command requests an RPC based transformation using the RPC model associated with the named file. Because the -i (inverse) flag is used, the transformation is from output georeferenced (WGS84) coordinates back to image coordinates. we love a reverse uno 🃏

gdaltransform -i -rpc 06OCT20025052-P2AS-005553965230_01_P001.TIF
125.67206 39.85307 50

Produces this output measured in pixels and lines on the image:

3499.49282422381 2910.83892848414 50

🌈 X,Y,Z,time transform 🌈

15-term time-dependent Helmert coordinate transformation from ITRF2000 to ITRF93 for a coordinate at epoch 2000.0 🕰️ (yes queens, it's time-dependent, she contains multitudes)

gdaltransform -ct "+proj=pipeline +step +proj=unitconvert +xy_in=deg \
+xy_out=rad +step +proj=cart +step +proj=helmert +convention=position_vector \
+x=0.0127 +dx=-0.0029 +rx=-0.00039 +drx=-0.00011 +y=0.0065 +dy=-0.0002 \
+ry=0.00080 +dry=-0.00019 +z=-0.0209 +dz=-0.0006 +rz=-0.00114 +drz=0.00007 \
+s=0.00195 +ds=0.00001 +t_epoch=1988.0 +step +proj=cart +inv +step \
+proj=unitconvert +xy_in=rad +xy_out=deg"
2 49 0 2000

Produces this output measured in longitude degrees, latitude degrees and ellipsoid height in meters:

2.0000005420366 49.0000003766711 -0.0222802283242345

🌸 Ground control points 🌸

Task: find one address and assign another. We pick Salt Lake City, where road names are their grid values. We first establish some ground control points at road intersections. We'll use --optfile for easy reuse of our GCPs. iconic behavior honestly 💅

echo -output_xy \
-gcp 0   0    -111.89114717 40.76932606 \
-gcp 0   -500 -111.89114803 40.75846686 \
-gcp 500 0    -111.87685039 40.76940631 > optfile.txt

Where is the address "370 S. 300 E."?

echo 300 -370 Address 370 S. 300 E. | gdaltransform --optfile optfile.txt
-111.8825697384 40.761338402 Address 370 S. 300 E.

(The 370 is protected from being consumed as an elevation by placing a word before it.) 🛡️ sneaky but valid.

Nearby, a newly constructed building needs an address assigned. We use -i:

echo -111.88705 40.76502 Building ABC123 | gdaltransform -i --optfile optfile.txt
143.301947786644 -199.32683635161 Building ABC123

(i.e., 143 E. 200 S. Or 144 if across the street.) 🏠 slay.

👑 AUTHOR 👑

Frank Warmerdam <warmerdam@pobox.com>, Jan Hartmann <j.l.h.hartmann@uva.nl>

the OGs, fr fr 🙌

1998-2026

okay bestie that's the whole page!! 🦋✨ this was the GDALTRANSFORM(1) page from the GDAL manual, dated Aug 18, 2026, with copyright 1998-2026 — now go transform some coordinates, you've got this 💖🎀🫶

📦 where this page comes from