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:10]
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: 
 + 
 +  * 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''​ 
 + 
 +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. 
 + 
 +==== Spatial context and image virtualization ==== 
 + 
 +The expression is evaluated independently **once per cell** across the output map. Two spatial keywords are available inside the expression:​ 
 + 
 +  * ''​line''​ — the row index of the current cell, starting at 1 
 +  * ''​column''​ — the column index of the current cell, starting at 1 
 + 
 +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. 
 + 
 +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. 
 + 
 +==== Available expression features ==== 
 + 
 +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. 
 + 
 +==== Null value handling ==== 
 + 
 +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. 
 + 
 +==== Performance ==== 
 + 
 +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.
  
-A list of mathematical and logical operators that can be employed in the logic/​algebraic expression can be found in the [[Image Expression Type | image expression reference]]. 
-  
 ===== Internal Name ===== ===== Internal Name =====
  
-CalculateMap+''​CalculateMap''​ 
 + 
 +===== Usage examples ===== 
 + 
 +  * [[calculate_functors#​calculatemap_examples|CalculateMap practical examples]] in the Calculate Functors documentation 
 +  * [[lesson_5|Lesson 5: Implementing a simple map algebra]]