doc:rasteralgebra

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.

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.

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). If a layer name contains spaces it must be surrounded with single or double quotes.

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`

.

Symbol | Description | Comments |
---|---|---|

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 |

Symbol | Description | Comments |
---|---|---|

+ | addition | |

- | subtraction | |

* | multiplication | |

/ | division | |

^ | exponentiation | |

DIV | integer division | |

% MOD | modulo |

Symbol | Description | Comments |
---|---|---|

< | less | |

⇐ | less or equal | |

== | equal | |

>= | greater or equal | |

> | greater | |

!= <> | not equal |

Symbol | Description | Comments |
---|---|---|

AND | conjunction | |

OR | disjunction | |

XOR | exclusive disjunction | |

NOT | negation |

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

Symbol | Description | Comments |
---|---|---|

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

Symbol | Description | Comments |
---|---|---|

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 | x^{y} |

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 |

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)`

.

Symbol | Description | Comments |
---|---|---|

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.

Symbol | Description | Comments |
---|---|---|

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 |

Symbol | Description | Comments |
---|---|---|

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 |

RAD2DEG(x) | converts radians to degrees | |

DEG2RAD(x) | converts degrees to radians |

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))

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)

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))

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.

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 )

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)

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))

2021/06/21 18:50