User Tools

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

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

Operators

Arithmetic operators

Symbol Description Comments
+ addition
- subtraction
* multiplication
/ division
^ exponentiation
DIV integer division
%
MOD
modulo

Comparison operators

Symbol Description Comments
< less
less or equal
== equal
>= greater or equal
> greater
!=
<>
not equal

Logical operators

Symbol Description Comments
AND conjunction
OR disjunction
XOR exclusive disjunction
NOT negation

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

Other operators

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

Functions

Ordinary functions

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

Color creation functions

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

Other functions

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

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