Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision | |||
|
calculate_map [2026/07/15 01:17] hermann |
calculate_map [2026/08/28 03:14] (current) hermann Sync from local documentation review |
||
|---|---|---|---|
| Line 3: | Line 3: | ||
| ===== Description ===== | ===== Description ===== | ||
| - | 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. | + | 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 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. | + | 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. |
| - | + | ||
| - | 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]] | The algebraic or logical formula used to compute each output cell. Must be enclosed in square brackets ''[ ]'' in EGO Script. | | + | | 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 ^ Default ^ Description ^ | + | ^ Name ^ Type ^ Description ^ Default Value ^ |
| - | | Cell Type | [[Cell Type Type]] | Signed 32-bit Integer | Data type for each output cell (e.g., byte, int16, float32). | | + | | Cell Type | [[Cell Type Type]] | Data type for each output cell. | Signed 32 Bit Integer | |
| - | | Null Value | [[Null Value Type]] | Based on Cell Type | Sentinel value representing "no data" in the output. | | + | | Null Value | [[Null Value Type]] | Sentinel value representing "no data" in the output. | .default | |
| - | | Result Is Sparse | [[Boolean Value Type]] | False | If true, only non-null cells are stored in memory — saves memory but slows random access. | | + | | 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]] | 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. | | + | | 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]] | The computed continuous 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 35: | Line 33: | ||
| ==== Connecting data inputs ==== | ==== Connecting data inputs ==== | ||
| - | 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: | + | 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'' | + | * Maps → [[Number Map]] → referenced in the expression as i1, i2, …, i100 |
| - | * Tables and lookup tables → [[Number Table]] → referenced as ''t1'', ''t2'', …, ''t100'' | + | * Tables and lookup tables → [[Number Table]] → referenced as t1, t2, …, t100 |
| - | * Scalar values → [[Number Value]] → referenced as ''v1'', ''v2'', …, ''v100'' | + | * 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. | 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. | ||
| Line 45: | Line 43: | ||
| ==== Spatial context and image virtualization ==== | ==== 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: | + | 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 | + | * line — the row index of the current cell, starting at 1 |
| - | * ''column'' — the column 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. | + | 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. | + | 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 ==== | ==== 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. | + | 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 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. | + | 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 ==== | ==== Performance ==== | ||
| Line 68: | Line 66: | ||
| ===== Internal Name ===== | ===== Internal Name ===== | ||
| - | ''CalculateMap'' | + | CalculateMap |
| ===== Usage examples ===== | ===== Usage examples ===== | ||
| - | * [[calculate_functors#calculatemap_examples|CalculateMap practical examples]] in the Calculate Functors documentation | + | * [[Calculate Functors#CalculateMap practical examples|CalculateMap practical examples]] in the Calculate Functors documentation |
| * [[lesson_5|Lesson 5: Implementing a simple map algebra]] | * [[lesson_5|Lesson 5: Implementing a simple map algebra]] | ||
| - | |||