Raster Algebra
Documentation | Other Specifications | Raster Algebra
The raster/map algebra allows manipulating and combining 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 the left-hand side and RHS for the right-hand side.
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 that can be referenced (by name) in the algebraic expression. The Execute method calculates 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). If a layer name contains spaces it must be surrounded with single or double quotes.
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 fieldNUM1,
then
grdis equivalent togrd.1and represents the first band ofgrd,grd.2represents the second band ofgrd,pixrepresents 32 bit ARGB color values ofpix,pix.Ris equivalent topix.1and represents the red band,pix.Gis equivalent topix.2nad represents the green band etc.,pix.Hrepresents the hue ofpix,- the fifth band of
pixis represented only withpix.5, - the value of the attribute
NUM1ofvecis represented withvec.NUM1, - the value of the predefined attribute
GIS_COORD_Zofvecis represented withvec.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))