1. Spatial GeoRaster Developer's Guide
  2. Raster Algebra and Analytics
  3. Raster Algebra Language

5.1 Raster Algebra Language

Raster algebra is commonly used in raster data analysis and GIS modeling. In GeoRaster, raster algebra is supported by the GeoRaster raster algebra language.

The GeoRaster raster algebra language is an extension to the Oracle PL/SQL language. PL/SQL provides declarations of variables and constants, general mathematical expressions, basic functions, statements, and programming capabilities. GeoRaster provides a raster algebra expression language and a set of raster algebra functions for raster layer operations. The raster algebra expression language includes general arithmetic, casting, logical, and relational operators and allows any combination of them. The raster algebra functions enable the usage of the expressions and support cell value-based conditional queries, mathematical modeling, classify operations, and cell value-based updates or edits over one or many raster layers from one or many GeoRaster objects.

This combination of the PL/SQL language and GeoRaster algebraic expressions and functions provides an easy-to-use, powerful way to define raster analyses as algebraic expressions, so that users can easily apply algebraic functions on raster data to derive new results. For example, a simple raster operation can use two or more raster layers with the same dimension sizes to produce a new raster layer by using algebraic operations (addition, subtraction, and so on), or a sophisticated raster operation to generate a Normalized Difference Vegetation Index (NDVI) from multiple bands of satellite imagery.

GeoRaster supports raster algebra local operations, so the raster algebra operations work on individual raster cells, or pixels.

The following is the GeoRaster raster algebra expression language definition:

<arithmeticExpr> ::=
                <unaryArithmeticExpr>
              | <binaryArithmeticExpr>
              | <functionalArithmeticExpr>
              | <conditionalExpr>
              | <castingExpr>
              | <booleanExpr>
              | <constantNumber>
              | <identifier>
              | ( <arithmeticExpr> )

<unaryArithmeticExpr> ::=
                ( <unaryArithmeticOp> <arithmeticExpr> ) 

<unaryArithmeticOp> ::=                  
                +
              | -

<binaryArithmeticExpr> ::=
                <arithmeticExpr> <binaryArithmeticOp> <arithmeticExpr> 

<binaryArithmeticOp> ::=
                +
              | -
              | *
              | /
              | %

<functionalArithmeticExpr> ::=
                <statisticalFunction> ( )
              | <numericFunction_with_1_param> ( <arithmeticExpr> )
              | <numericFunction_with_2_param> ( <arithmeticExpr> , <arithmeticExpr> )
              | <numericFunction_with_3_param> ( <arithmeticExpr> , <arithmeticExpr> , <arithmeticExpr> )

<statisticalFunction> ::=
                min
              | max
              | mean
              | median
              | std
              | minority
              | majority
              | sum
              | variety

<numericFunction_with_1_param> ::=
                abs
              | sqrt
              | exp
              | exp2
              | exp10
              | log
              | ln
              | log2
              | sin
              | cos
              | tan
              | sinh
              | cosh
              | tanh
              | arcsin
              | arccos
              | arctan
              | arcsinh
              | arccosh
              | arctanh
              | ceil
              | floor
              | factorial

<numericFunction_with_2_param> ::=
                power
              | max2
              | min2

<numericFunction_with_3_param> ::=
                max3
              | min3

<conditionalExpr> ::=
          <conditionalFunction> ( <booleanExpr> , <arithmeticExpr> , <arithmeticExpr> )

<conditionalFunction> ::=
                condition
 
<castingExpr> ::=
                <castingFunction> ( <arithmeticExpr> )

<castingFunction> ::=  
                castint
              | castonebit               
              | casttwobit
              | castfourbit
              | casteightbit
              | castBoolean

<booleanExpr> ::=
                <unaryBooleanExpr>
              | <binaryBooleanExpr>
              | ( <booleanExpr> )

<unaryBooleanExpr> ::=
                <unaryBooleanOp> <booleanExpr>

<unaryBooleanOp> ::=
                !

<binaryBooleanExpr> ::=
                <booleanExpr> <binaryBooleanOp> <booleanExpr>
              | <arithmeticExpr> <comparisonOp> <arithmeticExpr>

<binaryBooleanOp> ::=
                &
              | |
              | ^   

<comparisonOp> ::=
                =
              | <
              | >
              | >=
              | <=
              | !=
                   
<constantNumber> ::=
                <double number>

<identifier> ::=
                { <ID> , <band> }
              | { <band> }

<ID> ::=
                <integer number>

<band> ::=
                <integer number>

The precedence of the algebraic operators (+, -, *, /, and so on) in the expression language complies with general conventions. However, in any case where the expression might be misinterpreted, you should use parentheses to clarify which interpretation is intended.

The booleanExpr can be used as arithmeticExpr, as defined in the GeoRaster raster algebra expression language. In this case, the TRUE and FALSE evaluation results of booleanExpr are cast to numeric values 1 and 0, respectively.

The identifier in the expression refers to a raster layer of a GeoRaster object. It is either a single band number if there is only one GeoRaster object involved, or a pair of (ID, band) where ID refers to one of GeoRaster objects in the expression and band refers to a specific layer of that GeoRaster object. The band number in this language refers to the ordinate number of a layer along the band dimension in the cell space, so it always starts with 0 (zero). The GeoRaster ID number always starts with 0 (zero).

The following procedures provide the main support for raster algebra operations:

These raster algebra functions take many layers from one or many GeoRaster objects, apply booleanExpr and/or arithmeticExpr expressions over those layers, do the specific algebraic computation or modeling, and output a new GeoRaster object. The expressions can be defined in any way based on the syntax described earlier in this section.

Note:

All raster algebra functions require that the raster layers overlap each other and have the same dimension sizes and resolution if they are georeferenced, or have the same dimension sizes if they are not georeferenced. Before you apply raster algebra operations over two or more GeoRaster objects, you can use the SDO_GEOR_RA.isOverlap function to determine if the GeoRaster objects are of the same size and cover the same ground area.

Raster and image databases are generally very large. Querying and manipulating such databases are computationally intensive operations. To improve performance, all GeoRaster raster algebra functions are parallelized. You should always consider applying parallel processing when using multi-CPU or multicore servers.

Parent topic: Raster Algebra and Analytics

5.1.1 Examples of Raster Algebra Expressions

This section contains examples showing how to define raster algebra expressions.

Example 5-1 Finding Pixels Based on a Comparison (>)

Example 5-1 finds all pixels that meet the condition defined by algebra expression '{1}>200' , because there is only one GeoRaster object involved in the procedure, so {1} refers to the cell value of second layer ({0} would be for the first layer), and '{1}>200' means any pixels whose second layer value is greater than 200. The example assumes that the source GeoRaster object has at least two layers. 

DECLARE 
  geor       MDSYS.SDO_GEORASTER;
  geor1      MDSYS.SDO_GEORASTER;
BEGIN
  select georaster into geor from georaster_table where georid = 1;
  select georaster into geor1 from georaster_table where georid = 5 for update;
  sdo_geor_ra.findcells(geor, '{1}>200','blocking=optimalpadding, blocking=true, blocksize=(512,512,3)',geor1);
  update georaster_table set georaster = geor1 where georid = 5;
  commit;
END;
/

Example 5-2 Generating a GeoRaster Object Based on an Expressions Array

Example 5-2 generates a new GeoRaster object geor2 from two input GeoRaster objects geor and geor1 based on the algebra expressions array SDO_STRING2_ARRAY('{0,0}-0.5*{1,0}','{0,1}-0.5*{1,1}','{0,2}-0.5*{1,2}'). The example assumes that both of the source GeoRaster objects are images with three bands. 

DECLARE
  geor       MDSYS.SDO_GEORASTER;
  geor1      MDSYS.SDO_GEORASTER;
  geor2      MDSYS.SDO_GEORASTER;
  geo_array  MDSYS.SDO_GEORASTER_ARRAY;
BEGIN
  select georaster into geor from georaster_table where georid = 1;
  select georaster into geor1 from georaster_table where georid = 2;
  insert into georaster_table values (17, sdo_geor.init('rdt_1', 17)) returning georaster into geor2;
  geo_array:=MDSYS.SDO_GEORASTER_ARRAY(geor,geor1);
  sdo_geor_ra.rasterMathOp(geo_array,SDO_STRING2_ARRAY('{0,0}-0.5*{1,0}','{0,1}-0.5*{1,1}','{0,2}-0.5*{1,2}'),null,geor2);
  update georaster_table set georaster = geor2 where georid = 17;
  commit;
END;
/

In the algebra expressions array in Example 5-2:

  • {0,0} refers to the cell value of band 0 of the first input GeoRaster object geor.

  • {0,1} refers to the cell value of band 1 of the first input GeoRaster object geor.

  • {0,2} refers to the cell value of band 2 of the first input GeoRaster object geor.

  • {1,0} refers to the cell value of band 0 of the second input GeoRaster object geor1.

  • {1,1} refers to the cell value of band 1 of the second input GeoRaster object geor1.

  • {1,2} refers to the cell value of band 2 of the second input GeoRaster object geor1.

In Example 5-2, then, the target GeoRaster object geor2 will have three bands, and:

  • The cell value of band 0 of target GeoRaster object geor2 is: {0,0}-0.5*{1,0}

  • The cell value of band 1 of target GeoRaster object geor2 is: {0,1}-0.5*{1,1}

  • The cell value of band 2 of target GeoRaster object geor2 is: {0,2}-0.5*{1,2}

Example 5-3 Updating a GeoRaster Object Based on an Expressions Array

Example 5-3 updates cell values of the input GeoRaster object based on the algebra expression array SDO_STRING2_ARRAY('(abs({0}-{1})=48)&({2}-{1}=-101)','2*{0}-{1}/3=108'). The example assumes that the source GeoRaster object has three layers. 

DECLARE
  geor       MDSYS.SDO_GEORASTER;
  geor1      MDSYS.SDO_GEORASTER;
begin
  select georaster into geor from georaster_table where georid = 1;
  sdo_geor_ra.rasterUpdate(geor,0,SDO_STRING2_ARRAY('(abs({0}-{1})=48)&({2}-{1}=-101)','2*{0}-{1}/3=108'),SDO_STRING2_ARRAYSET(SDO_STRING2_ARRAY('123','54','89'),SDO_STRING2_ARRAY('98','56','123')));
END;
/

In Example 5-3, for each pixel:

  • If (abs({0}-{1})=48)&({2}-{1}=-101) is true, then the cell values of the three layers will be updated to ('123','54','89').

  • If 2*{0}-{1}/3=108 is true, then the cell values of the three layers will be updated to ('98','56','123').

Parent topic: Raster Algebra Language