# TatukGIS Developer Kernel 11

### Site Tools

doc:rasteralgebra

# Raster Algebra

Documentation | Other Specifications | Raster Algebra

The raster/map algebra allows to manipulate and combine raster and vector layers to produce a new raster layer. This topic explains the syntax of algebraic expressions that can be executed with the TGIS_RasterAlgebra class. For convenience, two abbreviations will be used further in this text - LHS for left-hand side and RHS for righ-hand side.

Raster Algebra is avaliable since Version 11.37.0-Unstable2.
Work in progress.

## API overview

The TGIS_RasterAlgebra class exposes two methods - AddLayer and Execute. The AddLayer method is used to define the set of raster and vector layers which can be referenced (by name) in the algebraic expression. The Execute method performs the calculation of the expression for each pixel of the raster layer on the LHS of the equation.

## Syntax

The general structure of the expression is

`LHS = RHS`

where LHS must be a name of a raster layer followed by an optional band number, band symbol or color parameter symbol. If only the layer name is supplied then it represents the first band of a grid layer or a 32 bit ARGB color for a non-grid (pixel) layer. For pixel layers the order of the color bands is always RGBA (regardless of the actual structure of the source file). The symbols accepted for pixel layers include:

• `R` - red band,
• `G` - green band,
• `B` - blue band,
• `A` - alpha (opacity) band,
• `H` - hue in the HSL/HSV color model,
• `SL` - saturation in the HSL color model,
• `SV` - saturation in the HSV color model,
• `L` - lightness in the HSL color model,
• `V` - brightness (value) in the HSV color model.

The RHS of the equation can contain references to raster and vector layers. A reference to a vector layer consists of the layer name followed by an obligatory attribute field name (the field must be numeric, predefined fields are also accepted).

#### Examples

Assume the following set of layers

• `grd` - a 2 band grid layer,
• `pix` - a 5 bands pixel layer,
• `vec` - a vector layer with one numeric attribute field `NUM1`,

then

• `grd` is equivalent to `grd.1` and represents the first band of `grd`,
• `grd.2` represents the second band of `grd`,
• `pix` represents 32 bit ARGB color values of `pix`,
• `pix.R` is equivalent to `pix.1` and represents the red band, `pix.G` is equivalent to `pix.2` nad represents the green band etc.,
• `pix.H` represents the hue of `pix`,
• the fifth band of `pix` is represented only with `pix.5`,
• the value of the attribute `NUM1` of `vec` is represented with `vec.NUM1`,
• the value of the predefined attribute `GIS_COORD_Z` of `vec` is represented with `vec.GIS_COORD_Z`.

### Constants

PI 3.1415926535…
E Euler's number/Napier's constant (base of the natural logarithm)
NODATA value representing void (no data) for pixel (e.g. RGB) layers the NODATA constant represents transparent color

### Operators

#### Arithmetic operators

- subtraction
* multiplication
/ division
^ exponentiation
DIV integer division
%
MOD
modulo

#### Comparison operators

< less
less or equal
== equal
>= greater or equal
> greater
!=
<>
not equal

#### Logical operators

AND conjunction
OR disjunction
XOR exclusive disjunction
NOT negation

In boolean expressions, 1 is treated as true, and 0 as false.

#### Other operators

? void (no data) `x ? y` - if x is not void then returns x, otherwise y

### Functions

#### Ordinary functions

ABS(x) absolute value
MIN(x,y) minimum value
MAX(x.y) maximum value
FLOOR(x) floor
CEIL(x) ceiling
ROUND(x) rounding
SQR(x) square
POW(x,y) power xy
SQRT(x) square root
ROOT(x,y) root
EXP(x) natural exponential
LN(x) natural logarithm
LOG2(x) binary logarithm logarithm base 2 of x
LOG10(x) common logarithm logarithm base 10 of x
LOG(y,x) logarithm logarithm base y of x
SIN(x) sine
COS(x) cosine
TAN(x) tangent
COT(x) cotangent
SEC(x) secant
CSC(x) cosecant
ARCSIN(x) inverse sine
ARCCOS(x) inverse cosine
ARCTAN(x) inverse tangent
ARCTAN2(x,y) inverse tangent inverse tangent of x over y
ARCCOT(x) inverse cotangent
ARCSEC(x) inverse secant
ARCCSC(x) inverse cosecant
SINH(x) hyperbolic sine
COSH(x) hyperbolic cosine
TANH(x) hyperbolic tangent
COTH(x) hyperbolic cotangent
SECH(x) hyperbolic secant
CSCH(x) hyperbolic cosecant
ARCSINH(x) inverse hyperbolic sine
ARCCOSH(x) inverse hyperbolic cosine
ARCTANH(x) inverse hyperbolic tangent
ARCCOTH(x) inverse hyperbolic cotangent
ARCSECH(x) inverse hyperbolic secant
ARCCSCH(x) inverse hyperbolic cosecant

#### Statistical functions

All statistical functions require one argument which can be one of the following:

• a raster layer name followed by an obligatory band number or band symbol e.g. `AVG(pix.R)`,
• a vector layer name followed by an obligatory attribute field name e.g. `MEDIAN(vec.NUM1)`.
AVG(x) average value
COUNT(x) number of valid values
COUNTNULL(x) number of void values
MAX(x) maximum value
MAJORITY(x) value that occurs most often
MEDIAN(x) middle value
MIN(x) minimum value
MINORITY(x) value that occurs least often
RANGE(x) difference between maximum and minimum values
STDEV(x) standard deviation
SUM(x) sum of all values
VARIANCE(x) variance
VARIETY(x) number of unique values

For more, see Statistics specification and TGIS_StatisticsAbstract class documentation.

#### Color creation functions

ARGB(a,r,g,b) color from alpha, red, green and blue values expected parameters value: 0..255
RGB(r,g,b,) color from red, green and blue values expected parameters value: 0..255
AHSL(a,h,s,l) color from alpha, hue, saturation and lightness values expected parameters value: 0.0..1.0
HSL(h,s,l) color from hue, saturation and lightness values expected parameters value: 0.0..1.0
AHSV(a,h,s,v) color from alpha, hue, saturation and brightness values expected parameters value: 0.0..1.0
HSV(hs,s,v) color from hue, saturation and brightness values expected parameters value: 0.0..1.0

#### Other functions

NODATA(x) returns true (1) if argument is void, otherwise returns false (0)
IF(x,y,z) conditional value if x is true (1) result is y, otherwise result is z

## Examples

#### Example 1

Assume `grd` is a one-band grid layer with multiple void areas. The task is to fill these areas with the minimum value of `grd`. The simplest solution is

`grd = grd ? MIN(grd)`

which is equivalent to

`grd.1 = grd.1 ? MIN(grd.1)`

However, the same can be achieved with

`grd = IF(NODATA(grd), MIN(grd), grd)`

or

`grd = IF(NOT NODATA(grd), grd, MIN(grd))`

#### Example 2

Assume `grd` is a one-band grid layer. The task is to fill all the areas where the value of `grd` is less than zero with void (value representing no data)

`grd = IF(grd > 0, grd, NODATA)`

#### Example 3

Assume `src1` and `src2` are two overlapping one-band grid layers. The task is to fill a third grid layer `dst` so that it is equal to `src1` where the value of `src1` is greater than `src2` and to `src2` otherwise

`dst = MAX(src1, src2)`

or equivalently

`dst = IF(src1 > src2, src1, src2)`

To make sure that `grd` will contain no void areas these expressions can be modified in many ways depending on the desired result e.g.

`dst = MAX(src1 ? MIN(src1), src2 ? MIN(src2))`

#### Example 4

Assume `srcR`, `srcG` and `srcB` are 8 bit monochrome pixel layers of the same extent which contain separate red, green and blue color bands. The task is to fill a 32 bit ARGB layer `dst` (8 bit per band) with reconstructed color values. This can be achieved by executing the following four expressions in sequence

```dst.A = 255
dst.R = srcR.1
dst.G = srcG.1
dst.B = srcB.1```

The first expression sets all the pixels to full opacity. However, an alternative approach can reduce the time needed for computations by executing ony one expression

`dst = RGB( srcR.1, srcG.1, srcB.1 )`

which automatically sets the alpha band to `255`. This is equivalent to

`dst = ARGB( 255, srcR.1, srcG.1, srcB.1 )`

If the destination layer's bit depth is different than 8 bit per band (RGB or ARGB) it is necessary to reconstruct each band separately.

#### Example 5

Assume `src` is a RGB pixel layer. The task is to make a negative of `src` and write the result to another RGB pixel layer `dst`

`dst = RGB( 255 - src.R, 255 - src.G, 255 - src.B )`

However, this can also be achieved in the HSL color space by rotating hue by 180 degrees (0.5 of the full angle) and negating lightness and shifting it by one

`dst = HSL(IF(src.H + 0.5 > 1, src.H - 0.5, src.H + 0.5), src.SL, 1 - src.L )`

#### Example 6

Assume `vec` is a polygonal vector layer with an attribute field `HEIGHT` describing the height of each polygon. The task is to elevate the values of a grid layer `grd` where the polygons are located by the values from the `HEIGHT` field and write the result to another grid layer `dst`

`dst = IF(NODATA(vec.HEIGHT), grd, grd + vec.HEIGHT)`

#### Example 7

Assume `vec` is a linear vector layer. The task is to perform a simple rasterization of `vec` by putting red pixels on an ARGB layer `dst` where the lines are located and leaving the rest of `dst` transparent

`dst = IF(NODATA(vec.GIS_UID), NODATA, RGB(255, 0, 0))`
2020/02/11 14:08

### Page Tools 