Differences

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

--- calculate_map [2011/11/17 00:46]
hermann [Optional Inputs]
+++ calculate_map [2026/07/15 01:17] (current)
hermann
@@ Line 3: / Line 3: @@
 ===== 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 =====
-^ 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 =====
-^ 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  | [[Null Value Type | Null Value]]  | 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 =====
-^ Name   ^ Type               ^ Description ^
+^ Name ^ Type ^ Description ^
-| Result | [[Map Type | Map]] | Output map. |
+| Result | [[Map Type]] | The computed continuous output map. |
 ===== Group =====
@@ Line 28: / Line 33: @@
 ===== 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:
-The 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]].
+  * 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''
-The maps used by the "Calculate Map" must be provided by a corresponding [[Number Map]], the tables must be provided by a corresponding [[Number Table]] and the values must be provided by a corresponding [[Number Value]].
+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.
 ===== 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]]