Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
calculate_map [2011/07/25 01:04]
hermann 		calculate_map [2026/07/15 01:17] (current)
hermann
Line 3: Line 3:
 ===== Description ===== ===== Description =====
  
-This container calculates ​a map using algebraic/logical expression ​involving maps, tables ​and values.+Computes ​a new **continuous raster ​map** by evaluating an algebraic ​or logical expression ​independently for every cell in the output map. The expression result is always computed as a real (floating-point) value and then converted to the output map's chosen Cell Type. 
 + 
 +This functor is one of five in the [[calculate_functors|calculator family]]. Use it when the expression produces continuous or measured ​values. If the expression produces integer class codes that should be treated as categories by downstream functors, use [[Calculate Categorical Map]] instead. 
 + 
 +The **abbreviated syntax** (also called **shorthand**) for this functor is ''#''​. See [[ego_script#​calculator_functor_shorthand|Calculator functor shorthand]] in the EGO Script documentation for the full syntax of both the verbose and abbreviated forms, and [[calculate_functors|Calculate Functors — Complete Operator Documentation]] for the complete expression language reference.
  
 ===== Inputs ===== ===== Inputs =====
  
-^ Name       ​^ Type                                         ​^ Description ​                                                      ​^ +^ Name ^ Type ^ Description ^ 
-| Expression | [[Image Expression Type | Image Expression]] | Algebraic ​or logical ​expression ​used to calculate the output ​map. |+| Expression | [[Image Expression Type]] | The algebraic ​or logical ​formula ​used to compute each output ​cell. Must be enclosed in square brackets ''​[ ]''​ in EGO Script. |
  
 ===== Optional Inputs ===== ===== Optional Inputs =====
  
-^ Name             ​^ Type                           ​^ Description ​                                                                                                                                                                          ^ Default Value         ^ +^ Name ^ Type ^ Default ​^ Description ^ 
-| Cell Type        | [[Cell Type Type | Cell Type]] ​| Data cell type                                                                                                                                                                        ​| Signed 32 Bit Integer | +| Cell Type | [[Cell Type Type]] | Signed 32-bit Integer ​| Data type for each output cell (e.g., byte, int16, float32). ​| 
-| Null Value       ​| [[Int Type | Int]]             ​| Null value                                                                                                                                                                            ​| -2147483648 ​          | +| Null Value | [[Null Value Type]] | Based on Cell Type | Sentinel value representing "no data" in the output. ​| 
-| Result Is Sparse | [[Bool Type | Bool]]           ​| If true, the resulting map is created as a sparse image. Sparse images have the advantage of storing ​only the cells containing ​non-null ​values, ​but they have diminished ​access ​time. | False                 |+| Result Is Sparse | [[Boolean Value Type]] ​| False | If true, only non-null ​cells are stored in memory — saves memory ​but slows random ​access. | 
 +| Result Format | [[Map Type]] | None | Optional reference map whose spatial format (extent, resolution, projection) is applied to the output. Category information in the reference map is ignored. Prefer this port over a ''​Number Map''​ hook when the map is needed only for format purposes — a hook defines an identifier in the expression namespace and blocks abbreviated syntax if that identifier is unused in the expression. ​|
  
 ===== Outputs ===== ===== Outputs =====
  
-^ Name   ​^ Type               ​^ Description ^ +^ Name ^ Type ^ Description ^ 
-| Result | [[Map Type | Map]] | Output ​map. |+| Result | [[Map Type]] | The computed continuous output ​map. |
  
 ===== Group ===== ===== Group =====
Line 28: Line 33:
 ===== Notes ===== ===== Notes =====
  
-The expression result is calculated as a real value and converted to the data cell type of the output map.+==== Connecting ​data inputs ====
  
-If the calculation of the expression ​diverges or if the data cell type is not large enough, ​the corresponding cell is filled with the null value.+All maps, tables, and scalar values referenced in the expression ​must be connected to the functor'​s ports before writing ​the expression, using **hook** functors:
  
-List of mathematical and logical operators that can be employed ​in the logic/​algebraic ​expression.+  * Maps → [[Number Map]] → referenced ​in the expression ​as ''​i1'',​ ''​i2'',​ …, ''​i100''​ 
 +  * Tables and lookup tables → [[Number Table]] → referenced as ''​t1'',​ ''​t2'',​ …, ''​t100''​ 
 +  * Scalar values → [[Number Value]] → referenced as ''​v1'',​ ''​v2'',​ …, ''​v100''​
  
-==== General Operators ====+In the abbreviated syntax, operands are referenced directly by the variable name they are bound to, prefixed with ''#''​ for maps, ''​%''​ for tables, and ''​$''​ for values — eliminating the hook block entirely.
  
-^ Precedence ^ Operator ^ Description ^ Symbol ^ Usage Example ^ +==== Spatial context and image virtualization ​====
-| 1 | Conditional | Execute the second or third term of the equation conditionally to the first | if@@@then@@@else | if not isNull(i1) and isNull(i2) then \\ @@@@@@i3 \\ else if isNull(i1) then \\ @@@@@@i1 – i1 / i2 \\ else  (i1 / i2) ? (i1 – i2) | +
-| 2 | Boolean Or | | or \\ <​nowiki>​||</​nowiki>​ | not isNull(i1) or isNull(i2) \\ not isNull(i1) <​nowiki>​||</​nowiki>​ isNull(i2) | +
-| ::: | Boolean And | | and \\ && | not isNull(i1) and isNull(i2) \\ not isNull(i1) && isNull(i2) | +
-| 3 | Equal | | = \\ == | i1 = 2 \\ i1 == 2 | +
-| ::: | Not Equal | | != \\ /= \\ <> | i1 != 2 \\ i1 /= 2 \\ i1 <> 2 | +
-| 4 | Greater Than | | > | i1 > 2 | +
-| ::: | Greater Than Or Equal | | >= | i1 >= 2 | +
-| ::: | Less Than | | < | i1 < i2 | +
-| ::: | Less Than Or Equal | | <​nowiki><​=</​nowiki>​ | i1 <​nowiki><​=</​nowiki>​ i2 | +
-| 5 | Add | | + | i1 + i2 | +
-| ::: | Subtract | | – | i1 – i1 / i2 | +
-| 6 | Times | | * | i1 * i2 | +
-| ::: | Divide | | / | i1 / i2 | +
-| ::: | Mod | | % | i1 % 100 | +
-| 7 | Power | | <​nowiki>​^</​nowiki>​ | i1 <​nowiki>​^</​nowiki>​ 3 | +
-| 8 | Catch Error | Catch an algebraic error and replace it with the result of another expression | ? | (i1 / i2) ? (i1 – i2) | +
-| 9 | Boolean Not | | ! \\ not | not isNull(i1) \\ ! isNull(i1) |  +
-| ::: | Negate | | – | – ceil(i1 + i2) |+
  
-==== General Functions ====+The expression is evaluated independently **once per cell** across the output map. Two spatial keywords are available inside the expression:
  
-^ Operator ^ Description ^ Symbol ^ Usage Example ^ +  * ''​line''​ — the row index of the current cell, starting at 1 
-| Value | | | 2 + i1 / -3.5e-2 | +  * ''​column''​ — the column index of the current cell, starting at 1
-| Random | Generate a random value using the uniform probability distribution | rand | if rand > 0.5 then 1 else i2 |  +
-| Squared Root | | sqrt() | sqrt(i1 / i4) | +
-| Sin | Sin (input in radians) | sin() | sin(i1 / i4) | +
-| Cos | Cos (input in radians) | cos() | cos(i1 + i2) | +
-| Tan | Tan (input in radians) | tan() | tan(i1 ​* i5 + 6) | +
-| Acos | Acos (output in radians) | acos() | acos(i1 + i2) | +
-| Asin | Asin (output in radians) | asin() | asin(i1 + i2) | +
-| Atan | Atan (output in radians) | atan() | atan(i1 + i2) | +
-| Ceil | | ceil() | ceil(i1 + i2) | +
-| Exp | | exp() | exp(i1[i1 + i2]) | +
-| Floor | | floor() | floor(i1 + i2) | +
-| Round | | round() | round(i1 / i4) | +
-| Abs | | abs() | abs(i1 + i2) | +
-| Ln | | ln() | ln(i1 / i4) | +
-| Log | | log() | log(i1 / i4) | +
-| Max | | max() | max(i1, i2) | +
-| Min | | min() | min(i1, i4) | +
-| Signal | Return +1, if the expression is positive, -1, if it is negative, and 0, otherwise. | signal() | signal(i1 - 4) | +
-| Abort | Abort the model execution | abort | if i1 > 0 then i1 * i2 + 4 else abort |+
  
-==== Value Operators ====+When the expression references more than one map, all of them are evaluated at the **same current cell** — ''​i1''​ and ''​i2''​ always refer to the same spatial location. Connected maps do **not** need matching extent, resolution, or pixel dimensions: Dinamica EGO reconciles this automatically through **image virtualization**,​ transparently wrapping each input in a virtual version sharing a common extent and the highest resolution among the inputs. The one requirement that virtualization does not relax is **projection** — all connected maps must share the same projection.
  
-^ Operator ^ Description ^ Symbol ^ Usage Example ^ +The ''​iX[LINE,​ COL]''​ form samples a map at an explicit coordinate rather than the current cell. Coordinates outside the image boundary are **mirrored** back into range. For a row coordinate ''​cellLine''​ in an image of N rows, ''​cellLine''​ is normally expected ​to be in the range [1, N]. When ''​cellLine''​ is outside this range, it is mirrored back: if ''​cellLine''​ ≤ 0, the effective row is ''​1 − cellLine''​ (for instance, ''​cellLine''​ = 0 → row 1, ''​cellLine''​ = −1 → row 2, ''​cellLine''​ = −2 → row 3); if ''​cellLine''​ > N, the effective row is ''​2N + 1 − cellLine''​ (for instance, ''​cellLine''​ = N+1 → row N, ''​cellLine''​ = N+2 → row N−1, ''​cellLine''​ = N+3 → row N−2). The same formula applies independently to the column coordinate ''​cellCol''​. If the target cell is null, the result is 0 rather than null.
-| Get Variable Value | Return ​the variable value | vX \\ where X is an integer value from 1 to 100 | v1 + t1[v2 + 4] |+
  
-==== Image Operators and Functions ​====+==== Available expression features ​====
  
-^ Operator ^ Description ^ Symbol ^ Usage Example ^ +All expression language features are available — there are no restrictions. For the full operator reference, see [[calculate_functors#​the_expression_language|The Expression Language]] in the Calculate Functors documentation,​ or the [[Image Expression Type]] page for the GUI editor and a navigable operator index.
-| Get Image Value | Return ​the image value at the current cell | iX \\ where X is an integer value from 1 to 100 | i2 | +
-| Get Image Value At Location | Return ​the image value on the specified cell coordinate | iX[ , ] \\ where X is an integer value from 1 to 100 | i1[line – 1, column – 2] | +
-| Get Image Null Value | Return ​the null value of the current image | null \\ null(iX) | if i1 > 2 then i1 else null \\ if null(i2) > 2 then 1 else null | +
-| Is Null | | isNull(iX) \\ where X is an integer value from 1 to 100 | if not isNull(i1) then i1 else i2 | +
-| Get Line Number | Return the line number of the current cell | line | line + 1 | +
-| Get Column Number | Return the column number of the current cell | column | if column / 2 > 50 then 1 else null |  +
-  +
-==== Table Operators ====+
  
-Table operators return the value corresponding to a given key according to a rule-operator. ​+==== Null value handling ====
  
-It uses the following syntax: \\ @@@@@@tX[N ] \\ where: \\ @@@@@@X is a table identifier; \\ @@@@@@N is the rule-operator. +Null propagation, ​the two map-calculator exceptions (''​iX[LINE, COL]''​ returning 0 and neighbourhood functions excluding nulls), and defensive patterns are covered in [[calculate_functors#​null_value_handling|Null Value Handling]] in the Calculate Functors documentation. If the computed result exceeds the range of the chosen Cell Type, that cell is also written as null rather than wrapping or clipping.
  
-^ Operator ^ Description ^ Symbol ^ Usage Example ^ +==== Performance ​====
-| Get Table Value | Return the table value in the X key position of the table | tX[ ] \\ where X is an integer value from 1 to 100 | t2[i1 + 2] | +
-| Get Table Equal Lower Bound Value | Return the table value in the greater key less than or equal to the X key position of the table. | tX[<​nowiki><​=</​nowiki>​ ] \\ tX{ } \\ where X is an integer value from 1 to 100 | 2[<​nowiki><​=</​nowiki>​ 14] \\ t2{14} | +
-| Get Table Lower Bound Value | Return the table value in the greater key less than the X key position of the table. | tX[< ] \\ where X is an integer value from 1 to 100 | t2[< i1 + 2] | +
-| Get Table Equal Upper Bound Value | Return the table value in the lesser key greater than or equal to the X key position of the table. | tX[>= ] \\ where X is an integer value from 1 to 100 | t2[>= i1 + i3]= | +
-| Get Table Upper Bound Value | Return the table value in the lesser key greater than the X key position of the table. | tX[> ] \\ where X is an integer value from 1 to 100 | t2[> i7] | +
-| Get Table Closest Value | Return the table value in the key closest to the X key position of the table. | tX[>< ] \\ where X is an integer value from 1 to 100 | t2[>< 3 + i7] | +
-| Get Table Interpoled Value | Return a linear interpoled value drawn through the neighbor keys of the X key position of the table. | tX[/ ] \\ where X is an integer value from 1 to 100 | t2[/ i2] | +
-| Test Table Key | Return 1, if expression corresponds to a key stored in the table, and 0, otherwise. | tX[? ] \\ tX[=? ] \\ tX[==? ] \\ where X is an integer value from 1 to 100 | t2[? i2] \\ t2[=? i2] | +
  
-==== Image Neighborhood Functions ====+Expression calculations can be compiled to native code automatically (requires the optional native expression support package), delivering near-C performance without any change to the model.
  
-Neighborhood operators return the value of an operation within a defined neighborhood window.  +===== Internal Name =====
-It uses the following syntax: \\ @@@@@@nbN(iX,​ h, w, y, x) \\ where: \\ @@@@@@N is the operator name; \\ @@@@@@X is an image identifier; \\ @@@@@@h is the number of window lines; \\ @@@@@@w is the number of window columns; \\ @@@@@@y is the line where the window center is anchored at the image; \\ @@@@@@x is the column where the window center is anchored at the image.+
  
-The calculation usually includes the center of the window.+''​CalculateMap''​
  
-Even-sided windows have the center displaced toward the top left corner.+===== Usage examples =====
  
-The window anchor (y and x) can be omitted when the window center is anchored at the current line and column. The shortened syntax is: \\ @@@@@@nbN(iX,​ h, w) +  * [[calculate_functors#​calculatemap_examples|CalculateMap practical examples]] in the Calculate Functors documentation 
- +  * [[lesson_5|Lesson ​5: Implementing ​a simple map algebra]]
-^ Operator ^ Description ^ Symbol ^ Usage Example ^ +
-| Min | Returns ​the minimum value of the neighbor non-null cells. | nbMin() | nbMin(i4, 2, 3, line-1, column) | +
-| Max | Returns the maximum value of the neighbor non-null cells. | nbMax() | nbMax(i1, 4, 4) - 1 | +
-| Sum | Returns the sum of the neighbor non-null cells. | nbSum() | nbSum(i3, ​5, 5) + 7 | +
-| Product | Returns the product of the neighbor non-null cells. | nbProd() | if not isNull(i1) then nbProd(i1, 2, 2, 0, column) else 0 | +
-| Count | Returns the number of neighbor non-null cells. | nbCount() | nbCount(i2, 3, 3) + nbCount(i1, 3, 3, line, column+3) | +
-| Average | Returns the arithmetic mean of the neighbor non-null cells. | nbAverage() | round(nbAverage(i1,​ 7, 7)) | +
-| Median | Returns the median value of the neighbor non-null cells. For an even number of values, the greater of the two median values is returned. | nbMedian() | nbMedian(i1,​ 5, 5) |  +
-| Mode | Returns the mode of the neighbor non-null cells. If a mode does not exist, null is returned. If there is more than one, the lesser one is returned. | nbMode() | nbMode(i1, 5, 5) | +
-| Variance | Returns the variance of the values of the neighbor non-null cells according to the expression: \\ @@@<m 10>​sigma^2 ​ = {1/​{n-1}}sum{i=1}{n}{(x_i-X)^2}</​m>​ \\ where \\ @@@x<​sub>​1</​sub>,​ x<​sub>​2</​sub>,​ ..., x<​sub>​i</​sub>​ are the neighbor cells; \\  @@@X is the mean of the neighbor cells. | nbVar() | nbVar(i4, 7, 7) / 25 | +
-| Standard Deviation | Returns the standard deviation of the neighbor non-null cells according to the expression: \\ @@@<m 8>sigma = sqrt{{1/​{n-1}}sum{i=1}{n}{(x_i-X)^2}}</​m>​ \\ where \\ @@@x<​sub>​1</​sub>,​ x<​sub>​2</​sub>,​ ..., x<​sub>​i</​sub>​ are the neighbor cells; \\ @@@X is the mean of the neighbor cells. | nbStdDev() | nbStdDev(i2,​ 3, 3, line-1, column) + nbStdDev(i2,​ 3, 3) + nbStdDev(i2,​ 3, 3, line+1, column) | +
-  +
-===== Internal Name =====+
  
-CalculateMap