Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
GDAL_CALC(1)			     GDAL			  GDAL_CALC(1)

NAME
       gdal_calc - Command line	raster calculator with numpy syntax.

SYNOPSIS
	  gdal_calc [--help] [--help-general]
		       --calc=expression --outfile=<out_filename> [-A <filename>]
		       [--A_band=<n>] [-B...-Z <filename>] [<other_options>]

       DESCRIPTION

       Command	line raster calculator with numpy syntax. Use any basic	arith-
       metic supported by numpy	arrays such as +, -, *,	and / along with logi-
       cal operators such as >.	 Note that all files must have the same	dimen-
       sions (unless the --extent option is used), but no projection  checking
       is performed (unless the	--projectionCheck option is used).

       NOTE:
	  gdal_calc  is	a Python utility, and is only available	if GDAL	Python
	  bindings are available.

       --help Show this	help message and exit

       --help-general
	      Gives a brief usage message for the generic GDAL commandline op-
	      tions and	exit.

       --calc=<expression>
	      Calculation in numpy syntax using	+, -, /, *, or any numpy array
	      functions	(i.e. log10()).	 Multiple --calc options can be	listed
	      to produce a multiband file (GDAL	>= 3.2).  See Example 10.

       -A <filename>
	      Input GDAL raster	file, you  can	use  any  letter  (a-z,	 A-Z).
	      (lower case supported since GDAL 3.3)

	      A	letter may be repeated,	or several values (separated by	space)
	      can  be  provided	(GDAL >= 3.3).	The effect will	be to create a
	      3D numpy array.  Since GDAL 3.5, wildcard	exceptions  (using  ?,
	      *)  are supported	for all	shells/platforms.  In such a case, the
	      calculation formula must use this	input as a 3D array  and  must
	      return  a	2D array (see Example 3).  If the calculation does not
	      return a 2D array	an error will be generated.

       --A_band=<n>
	      Number of	raster band for	file A (default	1).

       --outfile=<filename>
	      Output file to generate or fill.

       --NoDataValue=<value>
	      Output NoDataValue (default datatype specific value).  To	 indi-
	      cate  not	 setting a NoDataValue use --NoDataValue=none (GDAL >=
	      3.3)

	      NOTE:
		 Using the  Python  API:  None	value  will  indicate  default
		 datatype specific value.  'none' value	will indicate not set-
		 ting a	NoDataValue.

       --hideNoData
	      Added in version 3.3.

	      Ignores  the  input  bands  NoDataValue.	 By default, the input
	      bands NoDataValue	are not	participating in the calculation.   By
	      setting this setting - no	special	treatment will be performed on
	      the  input  NoDataValue.	and  they will be participating	in the
	      calculation as any other value.  The output will not have	a  set
	      NoDataValue, unless you explicitly specified a specific value by
	      setting --NoDataValue=<value>.

       --type=<datatype>
	      Output  datatype,	 must  be  one	of [Byte, Int8,	UInt16,	Int16,
	      UInt32, Int32, UInt64, Int64, Float64, Float32, CInt16,  CInt32,
	      CFloat64,	CFloat32].

	      NOTE:
		 Despite  the datatype set using --type, when doing intermedi-
		 ate arithmetic	operations using operands of  the  same	 type,
		 the  operation	 result	will honor the original	datatype. This
		 may lead into unexpected results in the final result.

	      NOTE:
		 UInt64, Int64,	CInt16,	CInt32,	CFloat32, CFloat64  have  been
		 added in GDAL 3.5.3 Int8 has been added in GDAL 3.7

       --format=<gdal_format>
	      GDAL format for output file.

       --color-table=<filename>
	      Allows  specifying  a filename of	a color	table (or a ColorTable
	      object) (with Palette Index interpretation) to be	used  for  the
	      output  raster.	Supported formats: txt (i.e. like gdaldem, but
	      color names are not supported), qlr,  qml	 (i.e.	exported  from
	      QGIS)

       --extent=<option>
	      Added in version 3.3.

	      This  option determines how to handle rasters with different ex-
	      tents.  This option is mutually exclusive	with the  projwin  op-
	      tion, which is used for providing	a custom extent.

	      For  all	the  options below the pixel size (resolution) and SRS
	      (Spatial Reference System) of all	the input rasters must be  the
	      same.

	      ignore  (default)	 - only	the dimensions of the rasters are com-
	      pared. if	the dimensions do not agree the	operation will fail.

	      fail - the dimensions and	the extent  (bounds)  of  the  rasters
	      must agree, otherwise the	operation will fail.

	      union  -	the  extent (bounds) of	the output will	be the minimal
	      rectangle	that contains all the input extents.

	      intersect	- the extent (bounds) of the output will be the	 maxi-
	      mal rectangle that is contained in all the input extents.

       --projwin <ulx> <uly> <lrx> <lry>
	      Added in version 3.3.

	      This option provides a custom extent for the output, it is mutu-
	      ally exclusive with the extent option.

       --projectionCheck
	      Added in version 3.3.

	      By  default,  no projection checking will	be performed.  By set-
	      ting this	option,	if the projection is  not  the	same  for  all
	      bands then the operation will fail.

       --creation-option=<option>
	      Passes  a	creation option	to the output format driver.  Multiple
	      options may be listed. See format	specific documentation for le-
	      gal creation options for each format.

       --co=<option>
	      The same as creation-option.

       --allBands=[a-z,	A-Z]
	      Apply the	expression to  all  bands  of  a  given	 raster.  When
	      --allBands  is  used,  --calc  may  be specified only once.  See
	      Example 11 and Example 12.

       --overwrite
	      Overwrite	output file if it already exists. Overwriting must  be
	      understood  here	as  deleting  and  recreating  the  file  from
	      scratch. Note that if this option	is not specified and the  out-
	      put file already exists, it will be updated in place.

       --debug
	      Print debugging information.

       --quiet
	      Suppress progress	messages.

PYTHON OPTIONS
       Added in	version	3.3.

       The  following  options	are available by using the Python interface of
       gdal_calc.  They	are not	available using	the command prompt.

       user_namespace
	      A	dictionary of custom functions or other	names to be  available
	      for use in the Calc expression.

       return_ds
	      If  enabled,  the	output dataset will be returned	from the func-
	      tion and not closed.

       color_table
	      Allows specifying	a ColorTable object (with Palette Index	inter-
	      pretation) to be used for	the output raster.

EXAMPLES
   Example 1: Average of two files
	  gdal_calc -A input1.tif -B input2.tif	--outfile=result.tif --calc="(A+B)/2"

       CAUTION:
	  If A and B inputs both have integer  data  types,  integer  division
	  will	be  performed.	 To  avoid this, you can convert of one	of the
	  operands to a	floating point type before the division	operation.

	      gdal_calc	-A input.tif -B	input2.tif --outfile=result.tif	--calc="(A.astype(numpy.float64) + B) /	2"

   Example 2: Summing three files
	  gdal_calc -A input1.tif -B input2.tif	-C input3.tif --outfile=result.tif --calc="A+B+C"

   Example 3: Combining	three files into a 3D array and	summing
	  gdal_calc -A input1.tif -A input2.tif	-A input3.tif --outfile=result.tif --calc="numpy.sum(A,axis=0)".

   Example 4: Average of three files
	  gdal_calc -A input1.tif -B input2.tif	-C input3.tif --outfile=result.tif --calc="(A+B+C)/3"

   Example 5: Average of three files, using 3D array
	  gdal_calc -A input1.tif input2.tif input3.tif	--outfile=result.tif --calc="numpy.average(a,axis=0)".

   Example 6: Maximum of three files
	  gdal_calc -A input1.tif -B input2.tif	-C input3.tif --outfile=result.tif --calc="numpy.max((A,B,C),axis=0)"

   Example 7: Maximum of three files, using a 3D array
	  gdal_calc -A input1.tif input2.tif input3.tif	--outfile=result.tif --calc="numpy.max(A,axis=0)"

   Example 8: Setting values of	zero and below to NODATA
	  gdal_calc -A input.tif --outfile=result.tif --calc="A*(A>0)" --NoDataValue=0

   Example 9: Using logical operator to	keep a range of	values from input
	  gdal_calc -A input.tif --outfile=result.tif --calc="A*logical_and(A>100,A<150)"

   Example 10: Performing two calculations and	storing	 results  in  separate
       bands
	  gdal_calc -A input.tif --A_band=1 -B input.tif --B_band=2 \
	    --outfile=result.tif --calc="(A+B)/2" --calc="B*logical_and(A>100,A<150)"

   Example 11: Add a raster to each band in a 3-band raster
	  gdal_calc -A 3band.tif -B 1band.tif --outfile	result.tif --calc "A+B"	--allBands A

       The  result  will have three bands, where each band contains the	values
       of 1band.tif added to the corresponding band in 3band.tif.

   Example 12: Add two three-band rasters
	  gdal_calc -A 3band_a.tif -B 3band_b.tif --outfile result.tif --calc "A+B" --allBands A --allBands B

       The result will have three bands, where each band contains  the	values
       of  the	corresponding  band  of	3band_a.tif added to the corresponding
       band of 3band_b.tif.

AUTHOR
       Chris Yesson <chris dot yesson at ioz dot ac dot	uk>, Etienne  Tourigny
       <etourigny dot dev at gmail dot com>

COPYRIGHT
       1998-2025

				 Jul 12, 2025			  GDAL_CALC(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=gdal_calc&sektion=1&manpath=FreeBSD+Ports+15.0>

home | help