Differences

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

--- calculate_categorical_map [2022/08/19 23:48]
admin [Notes]
+++ calculate_categorical_map [2026/07/15 01:19] (current)
hermann
@@ Line 3: / Line 3: @@
 ===== Description =====
-This container calculates a categorical map using algebraic/logical expression involving maps, tables and values.
+Computes a new **categorical raster map** by evaluating an algebraic or logical expression independently for every cell in the output map. Functionally identical to [[Calculate Map]] — the same inputs, parameters, and expression language apply — but the output is typed as a categorical map, which preserves category semantics for downstream functors that distinguish categorical maps from continuous maps (e.g. [[Calc Areas]], [[For Each Category]]).
+Use this functor when the expression produces integer class codes rather than measured or continuous values. If the expression produces continuous or measured values, use [[Calculate 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]]  | 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's category code. 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]]  | Data cell type  | Signed 32 Bit Integer  |
+| Cell Type | [[Cell Type Type]] | Signed 32-bit Integer | Data type for each output cell. |
-| Null Value  | [[Null Value Type]]  | Null value  | Default((Based on the value of the Cell Type input.))  |
+| Null Value | [[Null Value Type]] | Based on Cell Type | Sentinel value representing "no data" in the output. |
-| Result Is Sparse  | [[Boolean Value Type]]  | 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]]  | Map representing the output format. Any category information presents in the given map is not used as part of the map format.  | None  |
+| 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  | [[Categorical Map Type]]  | Output map of classes or categories  |
+| Result | [[Categorical Map Type]] | The computed categorical output map. |
 ===== Group =====
@@ Line 29: / Line 33: @@
 ===== Notes =====
-The expression result is calculated as a real value and converted to the data cell type of the output map.
+All behaviour — hook functor wiring, spatial context, image virtualization, available expression features, null value handling, and performance — is identical to [[Calculate Map]]. See the [[Calculate Map#notes|Notes]] section of that page for full details.
-If the calculation of the expression diverges, the corresponding cell is filled with the null value. In practice, it means that every time a null value is found in a expression calculation, the calculation results in null value, unless the occurrence of the null value is isolated from the rest of the expression by a special operator like ''[[image_expression_type#image_operators_and_functions|isNull()]]'' or ''[[image_expression_type#general_operators|?]]''.
+===== Internal Name =====
-The examples below illustrates:
+''CalculateCategoricalMap''
-^ Example  ^ Analysis  ^
-| <code cpp>i1 / 0</code>  | The expression always results in null value (division by zero).  |
-| <code cpp>i1 + i2 / i3 ^ 3</code>  | If the current cell of any of the images involved in the calculation is null value, the expression results in null value .  |
-| <code cpp>if isNull(i1) then
-else
-</code>  | The expression never results in null value.  |
-| <code cpp>if isNull(i1) then
-    i2
-else
-    i3
-</code>  | The expression might result in null value depending on the the value of i2 and i3.  |
-| <code cpp>(100 / i2) ? 0</code>  | The expression never results in null value.  |
-| <code cpp>(100 / i2) ? i1</code>  | The expression might result in null value depending on the the value of i1.  |
-If the data cell type is not large enough, the corresponding cell is also filled with the null value.
-The category information for the resulting map is automatically derived from its cell values.
-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]].
-The maps used by the "Calculate Categorical 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]].
-For additional information about how the null values are handled during image and value calculation, see [[Image Expression Null Value Handling|this reference]].
-===== Internal Name =====
-CalculateCategoricalMap