1GDALWARP(1) GDAL GDALWARP(1)
2
6 gdalwarp - Image reprojection and warping utility.
7
9 gdalwarp [--help-general] [--formats]
10 [-b|-srcband n]* [-dstband n]*
11 [-s_srs srs_def] [-t_srs srs_def] [-ct string]
12 [-to "NAME=VALUE"]* [-vshift | -novshift]
13 [[-s_coord_epoch epoch] | [-t_coord_epoch epoch]]
14 [-order n | -tps | -rpc | -geoloc] [-et err_threshold]
15 [-refine_gcps tolerance [minimum_gcps]]
16 [-te xmin ymin xmax ymax] [-te_srs srs_def]
17 [-tr xres yres]|[-tr square] [-tap] [-ts width height]
18 [-ovr level|AUTO|AUTO-n|NONE] [-wo "NAME=VALUE"] [-ot Byte/Int16/...] [-wt Byte/Int16]
19 [-srcnodata "value [value...]"] [-dstnodata "value [value...]"]
20 [-srcalpha|-nosrcalpha] [-dstalpha]
21 [-r resampling_method] [-wm memory_in_mb] [-multi] [-q]
22 [-cutline datasource] [-cl layer] [-cwhere expression]
23 [-csql statement] [-cblend dist_in_pixels] [-crop_to_cutline]
24 [-if format]* [-of format] [-co "NAME=VALUE"]* [-overwrite]
25 [-nomd] [-cvmd meta_conflict_value] [-setci] [-oo NAME=VALUE]*
26 [-doo NAME=VALUE]*
27 srcfile* dstfile
28
30 The gdalwarp utility is an image mosaicing, reprojection and warping
31 utility. The program can reproject to any supported projection, and can
32 also apply GCPs stored with the image if the image is "raw" with con‐
33 trol information.
34 -b <n>
36 -srcband <n>
38 New in version 3.7.
39 Specify an input band number to warp (between 1 and the number
42 of bands of the source dataset).
43 This option is used to warp a subset of the input bands. All in‐
45 put bands are used when it is not specified.
46 This option may be repeated multiple times to select several in‐
48 put bands. The order in which bands are specified will be the
49 order in which they appear in the output dataset (unless
50 -dstband is specified).
51 The alpha band should not be specified in the list, as it will
53 be automatically retrieved (unless -nosrcalpha is specified).
54 The following invocation will warp an input datasets with bands
56 ordered as Blue, Green, Red, NearInfraRed in an output dataset
57 with bands ordered as Red, Green, Blue.
58 gdalwarp in_bgrn.tif out_rgb.tif -b 3 -b 2 -b 1 -overwrite
60 -dstband <n>
62 New in version 3.7.
63 Specify the output band number in which to warp. In practice,
66 this option is only useful when updating an existing dataset,
67 e.g to warp one band at at time.
68 gdal_create -if in_red.tif -bands 3 out_rgb.tif
70 gdalwarp in_red.tif out_rgb.tif -srcband 1 -dstband 1
71 gdalwarp in_green.tif out_rgb.tif -srcband 1 -dstband 2
72 gdalwarp in_blue.tif out_rgb.tif -srcband 1 -dstband 3
73 If -srcband is specified, there must be as many occurrences of
75 -dstband as there are of -srcband.
76 The output alpha band should not be specified, as it will be au‐
78 tomatically created if the input dataset has an alpha band, or
79 if -dstalpha is specified.
80 If -dstband is not specified, then -dstband 1 -dstband 2 ...
82 -dstband N is assumed where N is the number of input bands
83 (specified explicitly either with -srcband or implicitly)
84 -s_srs <srs def>
86 Set source spatial reference. If not specified the SRS found in
87 the input dataset will be used.
88 The coordinate reference systems that can be passed are anything
90 supported by the OGRSpatialReference.SetFromUserInput() call,
91 which includes EPSG Projected, Geographic or Compound CRS (i.e.
92 EPSG:4296), a well known text (WKT) CRS definition, PROJ.4 dec‐
93 larations, or the name of a .prj file containing a WKT CRS defi‐
94 nition.
95 Starting with GDAL 2.2, if the SRS has an explicit vertical da‐
97 tum that points to a PROJ.4 geoidgrids, and the input dataset is
98 a single band dataset, a vertical correction will be applied to
99 the values of the dataset.
100 -s_coord_epoch <epoch>
102 New in version 3.4.
103 Assign a coordinate epoch, linked with the source SRS. Useful
106 when the source SRS is a dynamic CRS. Only taken into account if
107 -s_srs is used.
108 Currently -s_coord_epoch and -t_coord_epoch are mutually exclu‐
110 sive, due to lack of support for transformations between two dy‐
111 namic CRS.
112 -t_srs <srs_def>
114 Set target spatial reference.
115 A source SRS must be available for reprojection to occur. The
117 source SRS will be by default the one found in the input dataset
118 when it is available, or as overridden by the user with -s_srs
119 The coordinate reference systems that can be passed are anything
121 supported by the OGRSpatialReference.SetFromUserInput() call,
122 which includes EPSG Projected, Geographic or Compound CRS (i.e.
123 EPSG:4296), a well known text (WKT) CRS definition, PROJ.4 dec‐
124 larations, or the name of a .prj file containing a WKT CRS defi‐
125 nition.
126 Starting with GDAL 2.2, if the SRS has an explicit vertical da‐
128 tum that points to a PROJ.4 geoidgrids, and the input dataset is
129 a single band dataset, a vertical correction will be applied to
130 the values of the dataset.
131 -t_coord_epoch <epoch>
133 New in version 3.4.
134 Assign a coordinate epoch, linked with the target SRS. Useful
137 when the target SRS is a dynamic CRS. Only taken into account if
138 -t_srs is used.
139 Currently -s_coord_epoch and -t_coord_epoch are mutually exclu‐
141 sive, due to lack of support for transformations between two dy‐
142 namic CRS.
143 -ct <string>
145 A PROJ string (single step operation or multiple step string
146 starting with +proj=pipeline), a WKT2 string describing a Coor‐
147 dinateOperation, or a urn:ogc:def:coordinateOperation:EPSG::XXXX
148 URN overriding the default transformation from the source to the
149 target CRS. It must take into account the axis order of the
150 source and target CRS.
151 New in version 3.0.
153 -to <NAME=VALUE>
156 Set a transformer option suitable to pass to
157 GDALCreateGenImgProjTransformer2(). See
158 GDALCreateRPCTransformerV2() for RPC specific options.
159 -vshift
161 Force the use of vertical shift. This option is generally not
162 necessary, except when using an explicit coordinate transforma‐
163 tion (-ct), and not specifying an explicit source and target
164 SRS.
165 New in version 3.4.
167 -novshift
170 Disable the use of vertical shift when one of the source or tar‐
171 get SRS has an explicit vertical datum, and the input dataset is
172 a single band dataset.
173 NOTE:
175 this option was named -novshiftgrid in GDAL 2.2 to 3.3.
176 New in version 3.4.
178 -order <n>
181 order of polynomial used for warping (1 to 3). The default is to
182 select a polynomial order based on the number of GCPs.
183 -tps Force use of thin plate spline transformer based on available
185 GCPs.
186 -rpc Force use of RPCs.
188 -geoloc
190 Force use of Geolocation Arrays.
191 -et <err_threshold>
193 Error threshold for transformation approximation (in pixel units
194 - defaults to 0.125, unless, starting with GDAL 2.1, the RPC_DEM
195 transformer option is specified, in which case, an exact trans‐
196 former, i.e. err_threshold=0, will be used).
197 -refine_gcps <tolerance minimum_gcps>
199 Refines the GCPs by automatically eliminating outliers. Out‐
200 liers will be eliminated until minimum_gcps are left or when no
201 outliers can be detected. The tolerance is passed to adjust
202 when a GCP will be eliminated. Not that GCP refinement only
203 works with polynomial interpolation. The tolerance is in pixel
204 units if no projection is available, otherwise it is in SRS
205 units. If minimum_gcps is not provided, the minimum GCPs ac‐
206 cording to the polynomial model is used.
207 -te <xmin ymin xmax ymax>
209 Set georeferenced extents of output file to be created (in tar‐
210 get SRS by default, or in the SRS specified with -te_srs)
211 -te_srs <srs_def>
213 Specifies the SRS in which to interpret the coordinates given
214 with -te. The <srs_def> may be any of the usual GDAL/OGR forms,
215 complete WKT, PROJ.4, EPSG:n or a file containing the WKT. This
216 must not be confused with -t_srs which is the target SRS of the
217 output dataset. -te_srs is a convenience e.g. when knowing the
218 output coordinates in a geodetic long/lat SRS, but still wanting
219 a result in a projected coordinate system.
220 -tr <xres> <yres> | -tr square
222 Set output file resolution (in target georeferenced units).
223 If not specified (or not deduced from -te and -ts), gdalwarp
225 will, in the general case, generate an output raster with
226 xres=yres.
227 Starting with GDAL 3.7, if neither -tr nor -ts are specified,
229 that no reprojection is involved (including taking into account
230 geolocation arrays or RPC), the resolution of the source file(s)
231 will be preserved (in previous version, an output raster with
232 xres=yres was always generated). It is possible to ask square
233 pixels to still be generated, by specifying square as the value
234 for -tr.
235 -tap (target aligned pixels) align the coordinates of the extent of
237 the output file to the values of the -tr, such that the aligned
238 extent includes the minimum extent. Alignment means that xmin /
239 resx, ymin / resy, xmax / resx and ymax / resy are integer val‐
240 ues.
241 -ts <width> <height>
243 Set output file size in pixels and lines. If width or height is
244 set to 0, the other dimension will be guessed from the computed
245 resolution. Note that -ts cannot be used with -tr
246 -ovr <level|AUTO|AUTO-n|NONE>
248 To specify which overview level of source files must be used.
249 The default choice, AUTO, will select the overview level whose
250 resolution is the closest to the target resolution. Specify an
251 integer value (0-based, i.e. 0=1st overview level) to select a
252 particular level. Specify AUTO-n where n is an integer greater
253 or equal to 1, to select an overview level below the AUTO one.
254 Or specify NONE to force the base resolution to be used (can be
255 useful if overviews have been generated with a low quality re‐
256 sampling method, and the warping is done using a higher quality
257 resampling method).
258 -wo `"NAME=VALUE"`
260 Set a warp option. The GDALWarpOptions::papszWarpOptions docs
261 show all options. Multiple -wo options may be listed.
262 -ot <type>
264 Force the output image bands to have a specific data type sup‐
265 ported by the driver, which may be one of the following: Byte,
266 Int8, UInt16, Int16, UInt32, Int32, UInt64, Int64, Float32,
267 Float64, CInt16, CInt32, CFloat32 or CFloat64.
268 -wt <type>
270 Working pixel data type. The data type of pixels in the source
271 image and destination image buffers.
272 -r <resampling_method>
274 Resampling method to use. Available methods are:
275 near: nearest neighbour resampling (default, fastest algorithm,
277 worst interpolation quality).
278 bilinear: bilinear resampling.
280 cubic: cubic resampling.
282 cubicspline: cubic spline resampling.
284 lanczos: Lanczos windowed sinc resampling.
286 average: average resampling, computes the weighted average of
288 all non-NODATA contributing pixels.
289 rms root mean square / quadratic mean of all non-NODATA con‐
291 tributing pixels (GDAL >= 3.3)
292 mode: mode resampling, selects the value which appears most of‐
294 ten of all the sampled points. In the case of ties, the first
295 value identified as the mode will be selected.
296 max: maximum resampling, selects the maximum value from all
298 non-NODATA contributing pixels.
299 min: minimum resampling, selects the minimum value from all
301 non-NODATA contributing pixels.
302 med: median resampling, selects the median value of all non-NO‐
304 DATA contributing pixels.
305 q1: first quartile resampling, selects the first quartile value
307 of all non-NODATA contributing pixels.
308 q3: third quartile resampling, selects the third quartile value
310 of all non-NODATA contributing pixels.
311 sum: compute the weighted sum of all non-NODATA contributing
313 pixels (since GDAL 3.1)
314 NOTE:
316 When downsampling is performed (use of -tr or -ts), existing
317 overviews (either internal/implicit or external ones) on the
318 source image will be used by default by selecting the closest
319 overview to the desired output resolution. The resampling
320 method used to create those overviews is generally not the
321 one you specify through the -r option. Some formats, like
322 JPEG2000, can contain significant outliers due to wavelet
323 compression works. It might thus be useful in those situa‐
324 tions to use the -ovr NONE option to prevent existing over‐
325 views to be used.
326 -srcnodata <value [value...]>
328 Set nodata masking values for input bands (different values can
329 be supplied for each band). If more than one value is supplied
330 all values should be quoted to keep them together as a single
331 operating system argument. Masked values will not be used in
332 interpolation (details given in Nodata / source validity mask
333 handling)
334 Use a value of None to ignore intrinsic nodata settings on the
336 source dataset.
337 When this option is set to a non-None value, it causes the UNI‐
339 FIED_SRC_NODATA warping option (see
340 GDALWarpOptions::papszWarpOptions) to be set to YES, if it is
341 not explicitly set.
342 If -srcnodata is not explicitly set, but the source dataset has
344 nodata values, they will be taken into account, with UNI‐
345 FIED_SRC_NODATA at PARTIAL by default.
346 -dstnodata <value [value...]>
348 Set nodata values for output bands (different values can be sup‐
349 plied for each band). If more than one value is supplied all
350 values should be quoted to keep them together as a single oper‐
351 ating system argument. New files will be initialized to this
352 value and if possible the nodata value will be recorded in the
353 output file. Use a value of None to ensure that nodata is not
354 defined. If this argument is not used then nodata values will
355 be copied from the source dataset.
356 -srcalpha
358 Force the last band of a source image to be considered as a
359 source alpha band.
360 -nosrcalpha
362 Prevent the alpha band of a source image to be considered as
363 such (it will be warped as a regular band)
364 New in version 2.2.
366 -dstalpha
369 Create an output alpha band to identify nodata (unset/transpar‐
370 ent) pixels.
371 -wm <memory_in_mb>
373 Set the amount of memory that the warp API is allowed to use for
374 caching. The value is interpreted as being in megabytes if the
375 value is less than 10000. For values >=10000, this is inter‐
376 preted as bytes.
377 -multi Use multithreaded warping implementation. Two threads will be
379 used to process chunks of image and perform input/output opera‐
380 tion simultaneously. Note that computation is not multithreaded
381 itself. To do that, you can use the -wo NUM_THREADS=val/ALL_CPUS
382 option, which can be combined with -multi
383 -q Be quiet.
385 -if <format>
387 Format/driver name to be attempted to open the input file(s). It
388 is generally not necessary to specify it, but it can be used to
389 skip automatic driver detection, when it fails to select the ap‐
390 propriate driver. This option can be repeated several times to
391 specify several candidate drivers.
392 New in version 3.2.
394 -of <format>
397 Select the output format. Starting with GDAL 2.3, if not speci‐
398 fied, the format is guessed from the extension (previously was
399 GTiff). Use the short format name.
400 -co <NAME=VALUE>
402 Many formats have one or more optional creation options that can
403 be used to control particulars about the file created. For in‐
404 stance, the GeoTIFF driver supports creation options to control
405 compression, and whether the file should be tiled.
406 The creation options available vary by format driver, and some
408 simple formats have no creation options at all. A list of op‐
409 tions supported for a format can be listed with the --formats
410 command line option but the documentation for the format is the
411 definitive source of information on driver creation options.
412 See Raster drivers format specific documentation for legal cre‐
413 ation options for each format.
414 -cutline <datasource>
416 Enable use of a blend cutline from the name OGR support data‐
417 source.
418 -cl <layername>
420 Select the named layer from the cutline datasource.
421 -cwhere <expression>
423 Restrict desired cutline features based on attribute query.
424 -csql <query>
426 Select cutline features using an SQL query instead of from a
427 layer with -cl.
428 -cblend <distance>
430 Set a blend distance to use to blend over cutlines (in pixels).
431 -crop_to_cutline
433 Crop the extent of the target dataset to the extent of the cut‐
434 line.
435 -overwrite
437 Overwrite the target dataset if it already exists. Overwriting
438 must be understood here as deleting and recreating the file from
439 scratch. Note that if this option is not specified and the out‐
440 put file already exists, it will be updated in place.
441 -nomd Do not copy metadata. Without this option, dataset and band
443 metadata (as well as some band information) will be copied from
444 the first source dataset. Items that differ between source
445 datasets will be set to * (see -cvmd option).
446 -cvmd <meta_conflict_value>
448 Value to set metadata items that conflict between source
449 datasets (default is "*"). Use "" to remove conflicting items.
450 -setci Set the color interpretation of the bands of the target dataset
452 from the source dataset.
453 -oo <NAME=VALUE>
455 Dataset open option (format specific)
456 -doo <NAME=VALUE>
458 Output dataset open option (format specific)
459 New in version 2.1.
461 <srcfile>
464 The source file name(s).
465 <dstfile>
467 The destination file name.
468 Mosaicing into an existing output file is supported if the output file
470 already exists. The spatial extent of the existing file will not be
471 modified to accommodate new data, so you may have to remove it in that
472 case, or use the -overwrite option.
473 Polygon cutlines may be used as a mask to restrict the area of the des‐
475 tination file that may be updated, including blending. If the OGR
476 layer containing the cutline features has no explicit SRS, the cutline
477 features must be in the SRS of the destination file. When writing to a
478 not yet existing target dataset, its extent will be the one of the
479 original raster unless -te or -crop_to_cutline are specified.
480 Starting with GDAL 3.1, it is possible to use as output format a driver
482 that only supports the CreateCopy operation. This may internally imply
483 creation of a temporary file.
484
486 Invalid values in source pixels, either identified through a nodata
487 value metadata set on the source band, a mask band, an alpha band or
488 the use of -srcnodata will not be used in interpolation. The details
489 of how it is taken into account depends on the resampling kernel:
490 • for nearest resampling, for each target pixel, the coordinate of its
492 center is projected back to source coordinates and the source pixel
493 containing that coordinate is identified. If this source pixel is in‐
494 valid, the target pixel is considered as nodata.
495 • for bilinear, cubic, cubicspline and lanczos, for each target pixel,
497 the coordinate of its center is projected back to source coordinates
498 and a correspond source pixel is identified. If this source pixel is
499 invalid, the target pixel is considered as nodata. Given that those
500 resampling kernels have a non-null kernel radius, this source pixel
501 is just one among other several source pixels, and it might be possi‐
502 ble that there are invalid values in those other contributing source
503 pixels. The weights used to take into account those invalid values
504 will be set to zero to ignore them.
505 • for the other resampling methods, source pixels contributing to the
507 target pixel are ignored if invalid. Only the valid ones are taken
508 into account. If there are none, the target pixel is considered as
509 nodata.
510
512 • Basic transformation:
513 gdalwarp -t_srs EPSG:4326 input.tif output.tif
515 • For instance, an eight bit spot scene stored in GeoTIFF with control
517 points mapping the corners to lat/long could be warped to a UTM pro‐
518 jection with a command like this:
519 gdalwarp -t_srs '+proj=utm +zone=11 +datum=WGS84' -overwrite raw_spot.tif utm11.tif
521 • For instance, the second channel of an ASTER image stored in HDF with
523 control points mapping the corners to lat/long could be warped to a
524 UTM projection with a command like this:
525 New in version 2.2.
526 gdalwarp -overwrite HDF4_SDS:ASTER_L1B:"pg-PR1B0000-2002031402_100_001":2 pg-PR1B0000-2002031402_100_001_2.tif
529 • To apply a cutline on a un-georeferenced image and clip from pixel
531 (220,60) to pixel (1160,690):
532 gdalwarp -overwrite -to SRC_METHOD=NO_GEOTRANSFORM -to DST_METHOD=NO_GEOTRANSFORM -te 220 60 1160 690 -cutline cutline.csv in.png out.tif
534 where cutline.csv content is like:
536 id,WKT
538 1,"POLYGON((....))"
539 • To transform a DEM from geoid elevations (using EGM96) to WGS84 el‐
541 lipsoidal heights:
542 New in version 2.2.
543 gdalwarp -overwrite in_dem.tif out_dem.tif -s_srs EPSG:4326+5773 -t_srs EPSG:4979
546
548 This utility is also callable from C with GDALWarp().
549
551 Wiki page discussing options and behaviours of gdalwarp
552
554 Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer <silke@inteva‐
555 tion.de>
556
558 1998-2023
559 Oct 30, 2023 GDALWARP(1)