Differences

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

--- calculate_categorical_map [2015/10/13 20:20]
admin
+++ calculate_categorical_map [2026/08/28 03:11] (current)
hermann Sync from local documentation review
@@ 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 of the output map. Functionally identical to [[Calculate Map]] — the same inputs, parameters, and expression language apply — except that its output is typed as a categorical map, preserving category semantics for downstream functors that distinguish categorical maps from continuous ones (e.g. [[Calc Areas]], [[For Each Category]]). Use this functor when the expression produces integer class codes; use [[Calculate Map]] instead for continuous or measured values.
+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 — Complete Operator Documentation]] for the full expression language reference.
 ===== Inputs =====
 ^ Name  ^ Type  ^ Description  ^
-| Expression  | [[Image Expression Type]]  | Algebraic or logical expression used to calculate the output map.  |
+| Expression  | [[Image Expression Type]]  | 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  ^
-| Cell Type  | [[Cell Type 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  | [[Null Value Type]]  | Null value  | Default((Based on the value of the Cell Type input.))  |
+| Null Value  | [[Null Value Type]]  | Sentinel value representing "no data" in the output.  | .default  |
-| 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]]  | 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]]  | 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]]  | 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 =====
 ^ Name  ^ Type  ^ Description  ^
-| Result  | [[Categorical Map Type]]  | Output map of classes or categories  |
+| Result  | [[Categorical Map Type]]  | Computed categorical output map. Its dimensions come from the connected input maps, or from Result Format when given.  |
 ===== Group =====
@@ Line 29: / Line 31: @@
 ===== Notes =====
-The expression result is calculated as a real value and converted to the data cell type of the output map.
+All behavior — hook functor wiring, shared-cell evaluation and image virtualization across connected maps, null propagation, and the requirement that at least one map or Result Format be provided — is identical to [[Calculate Map]]. See that functor's Notes 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|?]]''.
+See [[Calculate Functors — Complete Operator Documentation]] for the complete expression language, null-value handling rules, and worked examples.
-The examples below illustrates:
-^ 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]].
 ===== Internal Name =====
 CalculateCategoricalMap