-
Notifications
You must be signed in to change notification settings - Fork 64
Map Algebra Overview
Map algebra is a language used within MrGeo to perform algebraic operations on inputs (e.g. images ingested into MrGeo) to produce an output. The operations will be performed for each pixel of the inputs, utilizing the Hadoop cluster to distribute the computations.
It includes raster math operations like addition, subtraction, division, multiplication, trigonometric functions as well as more complex operations like slope and cost distance. A map algebra script can be as simple as executing a single function on a single input, or it can make use of multiple inputs or chain a series of operations together to execute more complicated computations. The semi-colon (;) character is required at the end of each map algebra statement.
Map algebra can be executed on the command line or through a request to a web service once the MrGeo WAR is deployed to a web server.
For developers needing additional capability, new map algebra functions can be written using Java and included via a plugin mechanism.
Please refer to the map algebra reference for information on available map algebra functions.
When using a MrsPyramid image as an input, the image name should be surrounded in square brackets as in:
[myimage] + 1;
which produces an image in which each pixels is one larger than the corresponding pixel from the "myimage" input image.
GeoWave can be used as an input source for vector data, and the MrGeo data provider for GeoWave includes some specialized capability only for the GeoWave data sources. Within map algebra, when defining an input source, special syntax for GeoWave sources allows query information to be included, reducing the amount of data processed using GeoWave indices.
The syntax is as follows:
[geowave:myinput;spatial="<WKT>";startTime=<ISO date/time>;endTime=<ISO date/time>;cql="<CQL query>"]
Note that none of the fields are required, and if none are provided, all data from the specified input source ("myinput" in this case) will be processed. Notes follow on the individual fields.
-
spatial
Allows the user to define a well-known text (WKT) region that limits data processing to only features within that region. This should only be used for GeoWave sources that have spatial or spatial-temporal indices defined. If the WKT value contains either semi-colons or embedded double-quotes, the value itself should be double-quoted. In that case, embedded double quotes should be "escaped" with a preceeding backslash (i.e. "My value "here"").
-
startTime
Defines the starting time for a time range of data. This date/time must be in ISO 8601 format such as 2015-08-24T13:59:59-05:00. The time portion is optional. When specifying a startTime, an endTime is required, and based on how the GeoWave index was set up, specifying a time range that is too wide can result in an OutOfMemory exception from GeoWave.
-
endTime
Defines the ending time for a time range of data. It is the same format as startTime, and when endTime is specified, startTime also must be specified.
-
cql
Allows a CQL query to be included to filter the data processed beyond the spatial, startTime and endTime query limits. This does not reduce the amount of data that is physically read from the GeoWave source, but it allows data to be ignored as it is read. CQL filtering can be performed on any of the attributes defined for the data source. Follow the CQL/ECQL syntax supported by the Geotools open source project.
You can use variable assignment to retain intermediate results and subsequently pass those results into subsequent operations. For example:
s1 = [myimage] + 1;
d1 = s1 / 2;
The last operation in a map algebra script is the result that is persisted to the specified output image name. The results of other operations used as inputs to that final operation are not kept (unless the "save" map algebra function is explicitly used). For example, in the above example in the "Variables" section, the result assigned to the variable "d1" is saved as the final result to the user-specified output image name, but the result assigned to "s1" is not kept.
Internally, a map algebra script is broken down into an execution tree with the final operation in the script serving as the root of that tree. Inputs to that operation become children of the root, and inputs to those operations become grandchildren of the root, and so on.
The operations are executed beginning with the lowest operations in the execution tree since they must be resolved in order to be used as inputs to the operations higher up in the execution tree.