Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
calculate_map [2011/07/24 23:52] hermann [Image Neighborhood Operators] |
calculate_map [2026/08/28 03:14] (current) hermann Sync from local documentation review |
||
|---|---|---|---|
| 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 of 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. Use this functor when the expression produces continuous or measured values; use [[Calculate Categorical Map]] instead when the expression produces integer class codes that downstream functors should treat as categories. |
| + | |||
| + | This is one of Dinamica EGO's five calculator functors. Its abbreviated (shorthand) syntax is ''#''. See [[ego_script#calculator_functor_shorthand|Calculator functor shorthand]] in the EGO Script documentation for the verbose and abbreviated forms, and [[Calculate Functors|Calculate Functors — Complete Operator Documentation]] for the full 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]] | 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 ^ Description ^ Default Value ^ |
| - | | Cell Type | [[Cell Type Type | Cell Type]] | Data cell type | Signed 32 Bit Integer | | + | | Cell Type | [[Cell Type Type]] | Data type for each output cell. | Signed 32 Bit Integer | |
| - | | Null Value | [[Int Type | Int]] | Null value | -2147483648 | | + | | Null Value | [[Null Value Type]] | Sentinel value representing "no data" in the output. | .default | |
| - | | 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]] | If true, only non-null cells are stored, saving memory at the expense of random-access speed. This is an advanced port. | No | |
| + | | Result Format | [[Map Type]] | Reference map whose spatial format (extent, resolution, projection) is applied to the output; its category information, if any, is ignored. Prefer this port over a Number Map hook when a map is needed only for format purposes, since a hook defines an identifier in the expression namespace and blocks abbreviated syntax if that identifier goes unused in the expression. This is an advanced port. | .none | | ||
| ===== Outputs ===== | ===== Outputs ===== | ||
| - | ^ Name ^ Type ^ Description ^ | + | ^ Name ^ Type ^ Description ^ |
| - | | Result | [[Map Type | Map]] | Output map. | | + | | Result | [[Map Type]] | Computed output map. Its dimensions come from the connected input maps, or from Result Format when given. | |
| ===== Group ===== | ===== Group ===== | ||
| Line 28: | Line 31: | ||
| ===== 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, in order of precedence that can be employed in the logic/algebraic expression. Operators separated by blank lines have the same precedence. | + | * 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. |
| - | ^ Operator ^ Description ^ Symbol ^ Usage Example ^ | + | ==== Spatial context and image virtualization ==== |
| - | | 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) | | + | |
| - | | Equal | | = \\ == | i1 = 2 \\ i1 == 2 | | + | |
| - | | Not Equal | | != \\ /= \\ <> | i1 != 2 \\ i1 /= 2 \\ i1 <> 2 | | + | |
| - | | Greater Than | | > | i1 > 2 | | + | |
| - | | Greater Than Or Equal | | >= | i1 >= 2 | | + | |
| - | | Less Than | | < | i1 < i2 | | + | |
| - | | Less Than Or Equal | | <nowiki><=</nowiki> | i1 <nowiki><=</nowiki> i2 | | + | |
| - | | Add | | + | i1 + i2 | | + | |
| - | | Subtract | | – | i1 – i1 / i2 | | + | |
| - | | Times | | * | i1 * i2 | | + | |
| - | | Divide | | / | i1 / i2 | | + | |
| - | | Mod | | % | i1 % 100 | | + | |
| - | | Power | | <nowiki>^</nowiki> | i1 <nowiki>^</nowiki> 3 | | + | |
| - | | Catch Error | Catch an algebraic error and replace it with the result of another expression | ? | (i1 / i2) ? (i1 – i2) | | + | |
| - | | Boolean Not | | ! \\ not | not isNull(i1) \\ ! isNull(i1) | | + | |
| - | | Value | | | 2 + i1 / -3.5e-2 | | + | |
| - | | Random | Generate a random value using the uniform probability distribution | rand | if rand > 0.5 then 1 else i2 | | + | |
| - | | Negate | | – | – ceil(i1 + 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 | | + | |
| - | | 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) | | + | |
| - | ==== Value Operators ==== | + | 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 |
| - | | Get Variable Value | Return the variable value | vX \\ where X is an integer value from 1 to 100 | v1 + t1[v2 + 4] | | + | * column — the column index of the current cell, starting at 1 |
| - | ==== Image 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 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. | + | ==== Available expression features ==== |
| - | It uses the following syntax: tX[N ] \\ where: X is a table identifier; N is the rule-operator. | + | 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. |
| - | ^ Operator ^ Description ^ Symbol ^ Usage Example ^ | + | ==== Null value handling ==== |
| - | | 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 Operators ==== | + | 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. |
| - | Neighborhood operators return the value of an operation within a defined neighborhood window. | + | ==== Performance ==== |
| - | 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. | + | 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. |
| - | Even-sided windows have the center displaced toward the top left corner. | ||
| - | |||
| - | 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) | ||
| - | |||
| - | ^ 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 ===== | ===== Internal Name ===== | ||
| CalculateMap | CalculateMap | ||
| + | |||
| + | ===== Usage examples ===== | ||
| + | |||
| + | * [[Calculate Functors#CalculateMap practical examples|CalculateMap practical examples]] in the Calculate Functors documentation | ||
| + | * [[lesson_5|Lesson 5: Implementing a simple map algebra]] | ||