1GDALWARP(1) GDAL GDALWARP(1)
2
6 gdalwarp - Image reprojection and warping utility.
7
9 gdalwarp [--help-general] [--formats]
10 [-s_srs srs_def] [-t_srs srs_def] [-ct string] [-to "NAME=VALUE"]* [-vshift | -novshift]
11 [[-s_coord_epoch epoch] | [-t_coord_epoch epoch]]
12 [-order n | -tps | -rpc | -geoloc] [-et err_threshold]
13 [-refine_gcps tolerance [minimum_gcps]]
14 [-te xmin ymin xmax ymax] [-te_srs srs_def]
15 [-tr xres yres] [-tap] [-ts width height]
16 [-ovr level|AUTO|AUTO-n|NONE] [-wo "NAME=VALUE"] [-ot Byte/Int16/...] [-wt Byte/Int16]
17 [-srcnodata "value [value...]"] [-dstnodata "value [value...]"]
18 [-srcalpha|-nosrcalpha] [-dstalpha]
19 [-r resampling_method] [-wm memory_in_mb] [-multi] [-q]
20 [-cutline datasource] [-cl layer] [-cwhere expression]
21 [-csql statement] [-cblend dist_in_pixels] [-crop_to_cutline]
22 [-if format]* [-of format] [-co "NAME=VALUE"]* [-overwrite]
23 [-nomd] [-cvmd meta_conflict_value] [-setci] [-oo NAME=VALUE]*
24 [-doo NAME=VALUE]*
25 srcfile* dstfile
26
28 The gdalwarp utility is an image mosaicing, reprojection and warping
29 utility. The program can reproject to any supported projection, and can
30 also apply GCPs stored with the image if the image is "raw" with con‐
31 trol information.
32 -s_srs <srs def>
34 Set source spatial reference. If not specified the SRS found in
35 the input dataset will be used.
36 The coordinate reference systems that can be passed are anything
38 supported by the OGRSpatialReference.SetFromUserInput() call,
39 which includes EPSG Projected, Geographic or Compound CRS (i.e.
40 EPSG:4296), a well known text (WKT) CRS definition, PROJ.4 dec‐
41 larations, or the name of a .prj file containing a WKT CRS defi‐
42 nition.
43 Starting with GDAL 2.2, if the SRS has an explicit vertical da‐
45 tum that points to a PROJ.4 geoidgrids, and the input dataset is
46 a single band dataset, a vertical correction will be applied to
47 the values of the dataset.
48 -s_coord_epoch <epoch>
50 New in version 3.4.
51 Assign a coordinate epoch, linked with the source SRS. Useful
54 when the source SRS is a dynamic CRS. Only taken into account if
55 -s_srs is used.
56 Currently -s_coord_epoch and -t_coord_epoch are mutually exclu‐
58 sive, due to lack of support for transformations between two dy‐
59 namic CRS.
60 -t_srs <srs_def>
62 Set target spatial reference.
63 A source SRS must be available for reprojection to occur. The
65 source SRS will be by default the one found in the input dataset
66 when it is available, or as overridden by the user with -s_srs
67 The coordinate reference systems that can be passed are anything
69 supported by the OGRSpatialReference.SetFromUserInput() call,
70 which includes EPSG Projected, Geographic or Compound CRS (i.e.
71 EPSG:4296), a well known text (WKT) CRS definition, PROJ.4 dec‐
72 larations, or the name of a .prj file containing a WKT CRS defi‐
73 nition.
74 Starting with GDAL 2.2, if the SRS has an explicit vertical da‐
76 tum that points to a PROJ.4 geoidgrids, and the input dataset is
77 a single band dataset, a vertical correction will be applied to
78 the values of the dataset.
79 -t_coord_epoch <epoch>
81 New in version 3.4.
82 Assign a coordinate epoch, linked with the target SRS. Useful
85 when the target SRS is a dynamic CRS. Only taken into account if
86 -t_srs is used.
87 Currently -s_coord_epoch and -t_coord_epoch are mutually exclu‐
89 sive, due to lack of support for transformations between two dy‐
90 namic CRS.
91 -ct <string>
93 A PROJ string (single step operation or multiple step string
94 starting with +proj=pipeline), a WKT2 string describing a Coor‐
95 dinateOperation, or a urn:ogc:def:coordinateOperation:EPSG::XXXX
96 URN overriding the default transformation from the source to the
97 target CRS. It must take into account the axis order of the
98 source and target CRS.
99 New in version 3.0.
101 -to <NAME=VALUE>
104 Set a transformer option suitable to pass to
105 GDALCreateGenImgProjTransformer2(). See
106 GDALCreateRPCTransformerV2() for RPC specific options.
107 -vshift
109 Force the use of vertical shift. This option is generally not
110 necessary, except when using an explicit coordinate transforma‐
111 tion (-ct), and not specifying an explicit source and target
112 SRS.
113 New in version 3.4.
115 -novshift
118 Disable the use of vertical shift when one of the source or tar‐
119 get SRS has an explicit vertical datum, and the input dataset is
120 a single band dataset.
121 NOTE:
123 this option was named -novshiftgrid in GDAL 2.2 to 3.3.
124 New in version 3.4.
126 -order <n>
129 order of polynomial used for warping (1 to 3). The default is to
130 select a polynomial order based on the number of GCPs.
131 -tps Force use of thin plate spline transformer based on available
133 GCPs.
134 -rpc Force use of RPCs.
136 -geoloc
138 Force use of Geolocation Arrays.
139 -et <err_threshold>
141 Error threshold for transformation approximation (in pixel units
142 - defaults to 0.125, unless, starting with GDAL 2.1, the RPC_DEM
143 transformer option is specified, in which case, an exact trans‐
144 former, i.e. err_threshold=0, will be used).
145 -refine_gcps <tolerance minimum_gcps>
147 Refines the GCPs by automatically eliminating outliers. Out‐
148 liers will be eliminated until minimum_gcps are left or when no
149 outliers can be detected. The tolerance is passed to adjust
150 when a GCP will be eliminated. Not that GCP refinement only
151 works with polynomial interpolation. The tolerance is in pixel
152 units if no projection is available, otherwise it is in SRS
153 units. If minimum_gcps is not provided, the minimum GCPs ac‐
154 cording to the polynomial model is used.
155 -te <xmin ymin xmax ymax>
157 Set georeferenced extents of output file to be created (in tar‐
158 get SRS by default, or in the SRS specified with -te_srs)
159 -te_srs <srs_def>
161 Specifies the SRS in which to interpret the coordinates given
162 with -te. The <srs_def> may be any of the usual GDAL/OGR forms,
163 complete WKT, PROJ.4, EPSG:n or a file containing the WKT. This
164 must not be confused with -t_srs which is the target SRS of the
165 output dataset. -te_srs is a convenience e.g. when knowing the
166 output coordinates in a geodetic long/lat SRS, but still wanting
167 a result in a projected coordinate system.
168 -tr <xres> <yres>
170 Set output file resolution (in target georeferenced units).
171 If not specified (or not deduced from -te and -ts), gdalwarp
173 will generate an output raster with xres=yres, and that even
174 when using gdalwarp in scenarios not involving reprojection.
175 -tap (target aligned pixels) align the coordinates of the extent of
177 the output file to the values of the -tr, such that the aligned
178 extent includes the minimum extent. Alignment means that xmin /
179 resx, ymin / resy, xmax / resx and ymax / resy are integer val‐
180 ues.
181 -ts <width> <height>
183 Set output file size in pixels and lines. If width or height is
184 set to 0, the other dimension will be guessed from the computed
185 resolution. Note that -ts cannot be used with -tr
186 -ovr <level|AUTO|AUTO-n|NONE>
188 To specify which overview level of source files must be used.
189 The default choice, AUTO, will select the overview level whose
190 resolution is the closest to the target resolution. Specify an
191 integer value (0-based, i.e. 0=1st overview level) to select a
192 particular level. Specify AUTO-n where n is an integer greater
193 or equal to 1, to select an overview level below the AUTO one.
194 Or specify NONE to force the base resolution to be used (can be
195 useful if overviews have been generated with a low quality re‐
196 sampling method, and the warping is done using a higher quality
197 resampling method).
198 -wo `"NAME=VALUE"`
200 Set a warp option. The GDALWarpOptions::papszWarpOptions docs
201 show all options. Multiple -wo options may be listed.
202 -ot <type>
204 Force the output image bands to have a specific data type sup‐
205 ported by the driver, which may be one of the following: Byte,
206 UInt16, Int16, UInt32, Int32, Float32, Float64, CInt16, CInt32,
207 CFloat32 or CFloat64.
208 -wt <type>
210 Working pixel data type. The data type of pixels in the source
211 image and destination image buffers.
212 -r <resampling_method>
214 Resampling method to use. Available methods are:
215 near: nearest neighbour resampling (default, fastest algorithm,
217 worst interpolation quality).
218 bilinear: bilinear resampling.
220 cubic: cubic resampling.
222 cubicspline: cubic spline resampling.
224 lanczos: Lanczos windowed sinc resampling.
226 average: average resampling, computes the weighted average of
228 all non-NODATA contributing pixels.
229 rms root mean square / quadratic mean of all non-NODATA con‐
231 tributing pixels (GDAL >= 3.3)
232 mode: mode resampling, selects the value which appears most of‐
234 ten of all the sampled points. In the case of ties, the first
235 value identified as the mode will be selected.
236 max: maximum resampling, selects the maximum value from all
238 non-NODATA contributing pixels.
239 min: minimum resampling, selects the minimum value from all
241 non-NODATA contributing pixels.
242 med: median resampling, selects the median value of all non-NO‐
244 DATA contributing pixels.
245 q1: first quartile resampling, selects the first quartile value
247 of all non-NODATA contributing pixels.
248 q3: third quartile resampling, selects the third quartile value
250 of all non-NODATA contributing pixels.
251 sum: compute the weighted sum of all non-NODATA contributing
253 pixels (since GDAL 3.1)
254 NOTE:
256 When downsampling is performed (use of -tr or -ts), existing
257 overviews (either internal/implicit or external ones) on the
258 source image will be used by default by selecting the closest
259 overview to the desired output resolution. The resampling
260 method used to create those overviews is generally not the
261 one you specify through the -r option. Some formats, like
262 JPEG2000, can contain significant outliers due to wavelet
263 compression works. It might thus be useful in those situa‐
264 tions to use the -ovr NONE option to prevent existing over‐
265 views to be used.
266 -srcnodata <value [value...]>
268 Set nodata masking values for input bands (different values can
269 be supplied for each band). If more than one value is supplied
270 all values should be quoted to keep them together as a single
271 operating system argument. Masked values will not be used in
272 interpolation. Use a value of None to ignore intrinsic nodata
273 settings on the source dataset.
274 When this option is set to a non-None value, it causes the UNI‐
276 FIED_SRC_NODATA warping option (see
277 GDALWarpOptions::papszWarpOptions) to be set to YES, if it is
278 not explicitly set.
279 If -srcnodata is not explicitly set, but the source dataset has
281 nodata values, they will be taken into account, with UNI‐
282 FIED_SRC_NODATA at PARTIAL by default.
283 -dstnodata <value [value...]>
285 Set nodata values for output bands (different values can be sup‐
286 plied for each band). If more than one value is supplied all
287 values should be quoted to keep them together as a single oper‐
288 ating system argument. New files will be initialized to this
289 value and if possible the nodata value will be recorded in the
290 output file. Use a value of None to ensure that nodata is not
291 defined. If this argument is not used then nodata values will
292 be copied from the source dataset.
293 -srcalpha
295 Force the last band of a source image to be considered as a
296 source alpha band.
297 -nosrcalpha
299 Prevent the alpha band of a source image to be considered as
300 such (it will be warped as a regular band)
301 New in version 2.2.
303 -dstalpha
306 Create an output alpha band to identify nodata (unset/transpar‐
307 ent) pixels.
308 -wm <memory_in_mb>
310 Set the amount of memory that the warp API is allowed to use for
311 caching. The value is interpreted as being in megabytes if the
312 value is less than 10000. For values >=10000, this is inter‐
313 preted as bytes.
314 -multi Use multithreaded warping implementation. Two threads will be
316 used to process chunks of image and perform input/output opera‐
317 tion simultaneously. Note that computation is not multithreaded
318 itself. To do that, you can use the -wo NUM_THREADS=val/ALL_CPUS
319 option, which can be combined with -multi
320 -q Be quiet.
322 -if <format>
324 Format/driver name to be attempted to open the input file(s). It
325 is generally not necessary to specify it, but it can be used to
326 skip automatic driver detection, when it fails to select the ap‐
327 propriate driver. This option can be repeated several times to
328 specify several candidate drivers.
329 New in version 3.2.
331 -of <format>
334 Select the output format. Starting with GDAL 2.3, if not speci‐
335 fied, the format is guessed from the extension (previously was
336 GTiff). Use the short format name.
337 -co <NAME=VALUE>
339 Many formats have one or more optional creation options that can
340 be used to control particulars about the file created. For in‐
341 stance, the GeoTIFF driver supports creation options to control
342 compression, and whether the file should be tiled.
343 The creation options available vary by format driver, and some
345 simple formats have no creation options at all. A list of op‐
346 tions supported for a format can be listed with the --formats
347 command line option but the documentation for the format is the
348 definitive source of information on driver creation options.
349 See Raster drivers format specific documentation for legal cre‐
350 ation options for each format.
351 -cutline <datasource>
353 Enable use of a blend cutline from the name OGR support data‐
354 source.
355 -cl <layername>
357 Select the named layer from the cutline datasource.
358 -cwhere <expression>
360 Restrict desired cutline features based on attribute query.
361 -csql <query>
363 Select cutline features using an SQL query instead of from a
364 layer with -cl.
365 -cblend <distance>
367 Set a blend distance to use to blend over cutlines (in pixels).
368 -crop_to_cutline
370 Crop the extent of the target dataset to the extent of the cut‐
371 line.
372 -overwrite
374 Overwrite the target dataset if it already exists. Overwriting
375 must be understood here as deleting and recreating the file from
376 scratch. Note that if this option is not specified and the out‐
377 put file already exists, it will be updated in place.
378 -nomd Do not copy metadata. Without this option, dataset and band
380 metadata (as well as some band information) will be copied from
381 the first source dataset. Items that differ between source
382 datasets will be set to * (see -cvmd option).
383 -cvmd <meta_conflict_value>
385 Value to set metadata items that conflict between source
386 datasets (default is "*"). Use "" to remove conflicting items.
387 -setci Set the color interpretation of the bands of the target dataset
389 from the source dataset.
390 -oo <NAME=VALUE>
392 Dataset open option (format specific)
393 -doo <NAME=VALUE>
395 Output dataset open option (format specific)
396 New in version 2.1.
398 <srcfile>
401 The source file name(s).
402 <dstfile>
404 The destination file name.
405 Mosaicing into an existing output file is supported if the output file
407 already exists. The spatial extent of the existing file will not be
408 modified to accommodate new data, so you may have to remove it in that
409 case, or use the -overwrite option.
410 Polygon cutlines may be used as a mask to restrict the area of the des‐
412 tination file that may be updated, including blending. If the OGR
413 layer containing the cutline features has no explicit SRS, the cutline
414 features must be in the SRS of the destination file. When writing to a
415 not yet existing target dataset, its extent will be the one of the
416 original raster unless -te or -crop_to_cutline are specified.
417 Starting with GDAL 3.1, it is possible to use as output format a driver
419 that only supports the CreateCopy operation. This may internally imply
420 creation of a temporary file.
421
423 • Basic transformation:
424 gdalwarp -t_srs EPSG:4326 input.tif output.tif
426 • For instance, an eight bit spot scene stored in GeoTIFF with control
428 points mapping the corners to lat/long could be warped to a UTM pro‐
429 jection with a command like this:
430 gdalwarp -t_srs '+proj=utm +zone=11 +datum=WGS84' -overwrite raw_spot.tif utm11.tif
432 • For instance, the second channel of an ASTER image stored in HDF with
434 control points mapping the corners to lat/long could be warped to a
435 UTM projection with a command like this:
436 New in version 2.2.
437 gdalwarp -overwrite HDF4_SDS:ASTER_L1B:"pg-PR1B0000-2002031402_100_001":2 pg-PR1B0000-2002031402_100_001_2.tif
440 • To apply a cutline on a un-georeferenced image and clip from pixel
442 (220,60) to pixel (1160,690):
443 gdalwarp -overwrite -to SRC_METHOD=NO_GEOTRANSFORM -to DST_METHOD=NO_GEOTRANSFORM -te 220 60 1160 690 -cutline cutline.csv in.png out.tif
445 where cutline.csv content is like:
447 id,WKT
449 1,"POLYGON((....))"
450 • To transform a DEM from geoid elevations (using EGM96) to WGS84 el‐
452 lipsoidal heights:
453 New in version 2.2.
454 gdalwarp -overwrite in_dem.tif out_dem.tif -s_srs EPSG:4326+5773 -t_srs EPSG:4979
457
459 Wiki page discussing options and behaviours of gdalwarp
460
462 Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer <silke@inteva‐
463 tion.de>
464
466 1998-2023
467 Apr 17, 2023 GDALWARP(1)