====== Calculate Categorical Map ======

===== Description =====

This container calculates a categorical map using algebraic/logical expression involving maps, tables and values.

===== Inputs =====

^ Name  ^ Type  ^ Description  ^
| Expression  | [[Image Expression Type]]  | Algebraic or logical expression used to calculate the output map.  |

===== Optional Inputs =====

^ Name  ^ Type  ^ Description  ^ Default Value  ^
| Cell Type  | [[Cell Type Type]]  | Data cell type  | Signed 32 Bit Integer  |
| Null Value  | [[Null Value Type]]  | Null value  | Default((Based on the value of the Cell Type input.))  |
| 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 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  |

===== Outputs =====

^ Name  ^ Type  ^ Description  ^
| Result  | [[Categorical Map Type]]  | Output map of classes or categories  |

===== Group =====

[[Functor List#Map Algebra | Map Algebra]]

===== Notes =====

The expression result is calculated as a real value and converted to the data cell type of the output map.

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|?]]''.

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
    1
else
    2
</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