3.4.7. Band calc

The Band calc allows for the raster calculation for bands (i.e. calculation of pixel values) using NumPy functions. Band calc can also work with multiple expression lines to perform multiple calculation at a time; several iteration functions are available for Band sets allowing for performing multi-temporal calculations.

This tool supports virtual raster output; if the output file name ends with .vrt then the output is created as virtual raster composed of as many .tif files as the number of CPU threads defined in System; for large rasters this can speed up the process.

Raster bands must be already loaded in QGIS. Input rasters can also be in different projection, but the output will have the projection of the reference raster.

Порада

Information about APIs of this tool in Remotior Sensus at this link .

3.4.7.1. Band list 

Tool symbol and name	Description
Band list	table containing a list of single band rasters (already loaded in QGIS) and Input variables defined from Band set
Filter	filter the variable list
	refresh band list

3.4.7.2. Expression 

Enter a mathematical expression for raster bands. In particular, NumPy functions can be used with the prefix np. (e.g. np.log10(raster1) ). For a list of NumPy functions see the NumPy page .

The expression can work with Variable between ". Double click on any item in the Band list for adding the name thereof to the expression.

If text color in the Expression is green, then the syntax is correct; if text color is red, then the syntax is incorrect and it is not possible to execute the calculation.

It is possible to enter multiple expressions separated by newlines such as the following example:

"raster1" + "raster2"
"raster3" - "raster4"

The above example calculates two new rasters in the output directory with the suffix _1 (e.g. calc_raster_1 ) for the first expression and _2 (e.g. calc_raster_2 ) for the second expression. Also, it is possible to define the output name using the symbol @ followed by the name, such as the following example:

"raster1" + "raster2" @calc_1
"raster3" - "raster4" @calc_2

Input variables and Output variables can be used in the expression.

Tool symbol and name	Description
Input NoData as value	if checked, input `NoData` pixels are replaced by `NoData` value and accounted in calculation
Use value as NoData	if checked, selected value is used as `NoData` during calculation
Calculation data type	select the data type used during calculation as Float32 (default), Int32, Int16, UInt32, UInt16, Byte; for instance, if Int32 is selected, input float values will be evaluated as integer
Functions	list of Functions names (double click to copy one in the expression) such as mathematical, conditional, logical, statistics, indices, and custom
	open a text file (.txt) containing custom expressions to be listed in Functions

A text file can be loaded for adding expressions to the Functions. The text must contain an expression for each line; each line must be in the form expression_name; expression (separated by ;) where the expression_name is the expression name that is displayed in the Functions. Opening an empty text file will remove custom expressions from the Functions. Following an example of text content:

NDVI; ( "#NIR#" - "#RED#" ) / ( "#NIR#" + "#RED#" ) @NDVI
EVI; 2.5 * ( "#NIR#" - "#RED#" ) / ( "#NIR#" + 6 * "#RED#" - 7.5 * "#BLUE#" + 1) @EVI
SR; ( "#NIR#" / "#RED#" ) @SR

3.4.7.3. Output raster 

The output raster is a .tif file, with the same spatial resolution and projection of input rasters; if input rasters have different spatial resolutions, then the highest resolution (i.e. minimum pixel size) is used for output raster.

Порада

If multiple lines are entered in Expression or output name are defined in line, a directory selection instead of a file selection is prompted for output.

Tool symbol and name	Description
Output data type	select the output data type as Float32 (default), Int32, Int16, UInt32, UInt16, Byte; it can be different from Calculation data type
Output NoData value	set the value of `NoData` pixels in output raster
NoData mask	manage NoData at pixel level; if True, then output is NoData if any input is NoData; if False, then output is NoData if all the inputs are NoData; if None, then NoData is not applied to output
Set scale	if checked, set a scale in output raster (and output values are divided by scale)
Set offset	if checked, set an offset in output raster (and offset is subtracted to output values)
Extent UL X UL Y LR X LR Y	set the extent of the output raster among: „Union“: the extent union of input rasters „Map extent“: the extent of the map currently displayed „Intersection“: the extent intersection of input raster extents (i.e. minimum extent) „Custom“: coordinates defined in UL X UL Y LR X LR Y Layer name: the extent of the selected layer
Align	align the output raster to a specific Layer name or „Default“ for automatic alignment to input rasters
Pixel size	set pixel size
RUN	run this function; it is disabled if the expression syntax is not correct

3.4.7.4. Input variables 

The following variables related to the Band set are available (please note that the character " is always required):

bandset#b BAND_NUMBER: bands in the active Band set can be referenced directly; the following example refers to band 1 of the active Band set:
```
"bandset#b1"
```
bandset BANDSET_NUMBER b BAND_NUMBER: bands in the Band set can be referenced directly; the following example refers to band 1 of the Band set 1:
```
"bandset1b1"
```
bandset{ BANDSET_NUMBER_LIST }b BAND_NUMBER: list of all the bands X of all the Band sets matching a list between curly brackets (e.g. {1,2,3}) or range of Band sets separated by colon (e.g. {1:3}) or a list of ranges of Band sets (e.g. {1:3, 5:8}), which is equivalent to [bandset1bX, bandset2bX, ..., bandsetNbX]; this variable can be used in expressions that accept band lists such as the sum:
```
sum("bandset{1,3}b1")
```
bandset#b*: list of all the bands of active Band set, which is equivalent to [bandset#b1, bandset#b2, ..., bandset#bX]; to be used in expressions that accept band lists such as the maximum value:
```
max("bandset#b*")
```
bandset BANDSET_NUMBER b*: list of all the bands of Band set N, which is equivalent to [bandsetNb1, bandsetNb2, ..., bandsetNbX]; to be used in expressions that accept band lists such as the minimum value:
```
min("bandset1b*")
```
bandset*b BAND_NUMBER: list of all the bands X of all the Band sets, which is equivalent to [bandset1bX, bandset2bX, ..., bandsetNbX]; to be used in expressions that accept band lists such as the mean value:
```
mean("bandset*b1")
```
bandset{ DATE }b BAND_NUMBER: list of all the bands X of all the Band sets matching a list of dates (format yyyy-mm-dd) between curly brackets (e.g. {2019-01-01,2019-07-31}) or range of dates separated by colon (e.g. {2019-01-01:2019-07-31}) or a list of ranges of dates (e.g. {2019-01-01:2019-01-31, 2019-04-01:2019-07-31}), which is equivalent to [bandset2bX, bandset5bX, ..., bandsetNbX]; Band sets dates are defined in Band set definition; this variable can be used in expressions that accept band lists such as the median value:
```
median("bandset{2019-01-01,2019-07-31}b1")
```
«#BLUE#»: the band with the center wavelength closest to 0.475 \(\mu m\);
«#GREEN#»: the band with the center wavelength closest to 0.56 \(\mu m\);
«#RED#»: the band with the center wavelength closest to 0.65 \(\mu m\);
«#NIR#»: the band with the center wavelength closest to 0.85 \(\mu m\); for example:
```
( "#NIR#" - "#RED#" ) / ( "#NIR#" + "#RED#" )
```

3.4.7.5. Output variables 

Output names can be defined in the expression line entering the symbol @ followed by the name, such as the following example:

"raster1" * 2 @first_calculation

If the output name is defined in the expression, an output directory will be selected after clicking the button RUN.

Попередження

It is recommended to avoid the use of characters # and @ in the output raster name.

It is possible to set the output path directly by defining the output name with this structure @path@name, such as:

"raster1" * 2 @/home/user@first_calculation

The directory will be created if it does not exist.

It is possible to create a temporary output (saved in the temporary directory) with @temp@ followed by output name, such as:

"raster1" * 2 @temp@first_calculation

The output name of calculation can be used as input variable for the following calculations; for example:

"raster1" * 2 @first_calculation
"first_calculation" + 5 @temp@second_calculation
"second_calculation" - "raster1" @/home/user@third_calculation

It is possible to add the calculation result to a Band set using the symbol % followed by the Band set number such as:

"raster1" @first_calculation%1

It is possible to add the calculation result to the active Band set using the symbol % followed by the symbol # such as:

"raster1" @first_calculation%#

Also, variables for output name are available:

#BANDSET#: the name of the first band in the Band set;
#DATE#: the current date and time (e.g. 20161110_113846527764);

Using the symbol @ followed by the variable #BANDSET# can save the raster calculation inside the directory containing the first band of the active band set, such as:

"raster1" @#BANDSET#@first_calculation

If the output name is defined with the extension .vrt, the output will be a virtual raster referencing the single .tif files calculated by parallel processing. For instance, the following expression will calculate the raster with parallel processing and the output will be a .vrt:

"raster1" @first_calculation.vrt

Virtual file is useful to reduce calculation time of parallel processing by avoiding the writing of the entire output raster.

Попередження

A .vrt virtual file is a text file containing the reference to existing .tif files. Moving the .vrt virtual file or the .tif files in different directories can make the virtual file unusable.

3.4.7.6. Functions 

3.4.7.6.1. Conditional 

where: conditional expression according to the syntax where( condition , value if true, value if false) for example:
```
where("raster1" == 1, 2, "raster1")
```

Parenthesis are required for multiple conditions for instance to select pixel values between 1 and 3:

where( ("raster1" > 1) & ("raster1" < 3), 2, "raster1")

Nested conditions can be defined such as:

where( ("raster1" > 1) & ("raster1" < 3), 2, "raster1")

3.4.7.6.2. Logical 

AND: AND;
OR: OR;
XOR: XOR;
NOT: NOT;

3.4.7.6.3. Statistics 

A band list between square brackets or Input variables are required arguments.

max: maximum; for instance:
```
max(["raster1", "raster2", "raster3"])
```
min: minimum; for instance:
```
min(["bandset#b*"])
```
mean: mean; for instance:
```
mean("bandset*b1")
```

median: median; for instance:

median("bandset{2019-01-01,2019-07-31}b1")

percentile: percentile calculation; the expression must have this structure percentile([band_list], percentile_value); for instance, the following expression calculates the 10th percentile of active band set:
```
percentile("bandset#b*", 10)
```
std: standard deviation; for instance:
```
std("bandset{1,3}b1")
```
sum: sum; for instance:
```
sum("bandset{1:5}b1")
```

3.4.7.6.4. Operations 

sin: sine; for instance:
```
sin("raster1")
```
cos: cosine;
tan: tangent;
asin: inverse sine;
acos: inverse cosine;
atan: inverse tangent;
exp: natural exponential;
ln: natural logarithm;
log: base 10 logarithm;

3.4.7.6.5. Indices 

NDVI: if selected, the NDVI calculation is entered in the Expression:
```
( "#NIR#" - "#RED#" ) / ( "#NIR#" + "#RED#" ) @ NDVI
```

EVI: if selected, the EVI calculation is entered in the Expression:

2.5 * ( "#NIR#" - "#RED#" ) / ( "#NIR#" + 6 * "#RED#" - 7.5 * "#BLUE#" + 1) @ EVI

NBR: if selected, the NBR calculation is entered in the Expression:

( "#NIR#" - "#SWIR2#" ) / ( "#NIR#" + "#SWIR2#" ) @NBR

3.4.7.6.6. Variables 

nodata: NoData value of raster (e.g. nodata("raster1")); it can be used as value in the expression:
```
where("raster1" == nodata("raster1"), 0, "raster1")
```
forbandsets: it allows for the iteration over Band sets defined between square brackets; a range of Band sets separated by colon (e.g. forbandsets[1:3]) or a list separated by commas (e.g. forbandsets[1,2,3]; forbandsets must be entered in the first line of expressions (not compatible with forbandsinbandset), for instance:
```
forbandsets[1:3]
"bandset#b1" @#BANDSET#
```

During the iteration, the Input variables related to the active Band set are replaced by the iterator, therefore the expression:

forbandsets[1:3]
"bandset#b1" @#BANDSET#

is equivalent to:

"bandset1b1" @calc1
"bandset2b1" @calc2
"bandset3b1" @calc3

It is possible to enter a string (or a list of strings separated by comma ,) after the square bracket ] to filter Band sets by the name of first band in Band set; for instance, the following expression will iterate the first 3 Band sets selecting only the Band set whose name of the first band includes RT:

forbandsets[1,2,3]RT

Also, forbandsets: allows for the iteration over Band sets dates (format yyyy-mm-dd, defined in Band set definition) between square brackets, such as the following examples:

Iterating over a range of dates:

forbandsets[2020-01-01:2020-07-31]
"bandset#b1" @#BANDSET#

Iterating over a list of dates:

forbandsets[2020-02-01,2020-03-11,2020-04-21]
"bandset#b1" @#BANDSET#

Iterating over a list of ranges of dates:

forbandsets[2010-01-01:2010-06-31, 2010-08-01:2010-08-31, 2010-10-01:2010-12-31]
"bandset#b1" @#BANDSET#

During the iteration, the Input variables related to the active Band set are replaced by the iterator.

It is possible to enter a string (or a list of strings separated by comma ,) after the square bracket ] to filter Band sets by the name of first band in Band set; for instance, the following expression will iterate the Band sets in the range selecting only the Band set whose name of the first band includes RT:

forbandsets[2020-01-01:2020-07-31]RT

forbandsinbandset: it allows for the iteration over bands in a Band set or a range of Band sets between square brackets; forbandsinbandset must be entered in the first line of expressions (not compatible with forbandsets); the variable #BAND# must be used to refer to the iterated band such as the following examples:

Iterating over the bands of the first Band set (note the " in the expression):

forbandsinbandset[1]
where("#BAND#" > 1, 1, 2) @#BAND#)

Iterating over all the bands of Band sets from 1 to 3:

forbandsinbandset[1:3]
where("#BAND#" > 1, 1, 2) @#BAND#)

#BAND#:
#BANDSET#: the name of the first band in the Band set;
#DATE#: the current date and time (e.g. 20161110_113846527764);
@: character @;