Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
calculate_functors [2026/07/07 06:50] hermann |
calculate_functors [2026/07/23 03:55] (current) hermann |
||
|---|---|---|---|
| Line 35: | Line 35: | ||
| | Null Value | Null Value Type | No | Based on Cell Type | Sentinel value representing "no data" in the output. | | | Null Value | Null Value Type | No | Based on Cell Type | Sentinel value representing "no data" in the output. | | ||
| | Result Is Sparse | Boolean Value Type | No | False | If ''True'', only non-null cells are stored — saves memory but slows random access. | | | Result Is Sparse | Boolean Value Type | No | False | If ''True'', only non-null cells are stored — saves memory but slows random access. | | ||
| - | | Result Format | Map Type | No | None | Optional reference map whose spatial format (extent, resolution, projection) is applied to the output. Category information in the reference map is ignored. | | + | | Result Format | Map Type | No | 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 ''NumberMap'' 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. | |
| ==== Output ==== | ==== Output ==== | ||
| Line 61: | Line 61: | ||
| | Null Value | Null Value Type | No | Based on Cell Type | Sentinel value representing "no data" in the output. | | | Null Value | Null Value Type | No | Based on Cell Type | Sentinel value representing "no data" in the output. | | ||
| | Result Is Sparse | Boolean Value Type | No | False | If ''True'', only non-null cells are stored. | | | Result Is Sparse | Boolean Value Type | No | False | If ''True'', only non-null cells are stored. | | ||
| - | | Result Format | Map Type | No | None | Optional reference map whose spatial format is applied to the output. | | + | | Result Format | Map Type | No | None | Optional reference map whose spatial format is applied to the output. Prefer this port over a ''NumberMap'' 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. | |
| ==== Output ==== | ==== Output ==== | ||
| Line 110: | Line 110: | ||
| | Key Column Name | String | **Yes** | — | Name of the key column in the output lookup table. | | | Key Column Name | String | **Yes** | — | Name of the key column in the output lookup table. | | ||
| | Value Column Name | String | **Yes** | — | Name of the value column in the output lookup table. | | | Value Column Name | String | **Yes** | — | Name of the value column in the output lookup table. | | ||
| - | | Base Lookup Table | Lookup Table Type | No | ''.none'' | A lookup table whose key set drives iteration. When ''.none'', the ''NumberTable'' hook with the lowest list index that is connected to a **lookup table** (not a regular table) is used as the row source (verbose form), or the first lookup table named in the expression (shorthand form) — not a union of all connected tables. | | + | | Base Lookup Table | Lookup Table Type | No | ''.none'' | A lookup table whose key set drives iteration. When ''.none'', the ''NumberTable'' hook with the lowest list index that is connected to a **lookup table** (not a regular table) is used as the row source (verbose form), or the first lookup table named in the expression (shorthand form) — not a union of all connected tables. Prefer this port over a ''NumberTable'' hook when the table is needed only to define the row set and is not referenced in the expression, to keep abbreviated syntax available. | |
| ==== Output ==== | ==== Output ==== | ||
| Line 140: | Line 140: | ||
| | Key Column Name | String | **Yes** | — | Name of the key column in the output lookup table. | | | Key Column Name | String | **Yes** | — | Name of the key column in the output lookup table. | | ||
| | Value Column Name | String | **Yes** | — | Name of the value column in the output lookup table. | | | Value Column Name | String | **Yes** | — | Name of the value column in the output lookup table. | | ||
| - | | Base Lookup Table | Lookup Table Type | No | ''.none'' | A lookup table whose row set drives iteration. | | + | | Base Lookup Table | Lookup Table Type | No | ''.none'' | A lookup table whose row set drives iteration. Prefer this port over a ''NumberTable'' hook when the table is needed only to define the row set and is not referenced in the expression, to keep abbreviated syntax available. | |
| ==== Output ==== | ==== Output ==== | ||
| Line 209: | Line 209: | ||
| | 9 | **Boolean Not** | ''not EXPR'' / ''! EXPR'' | Inverts a boolean value. | ''not isNull(i1)'' | | | 9 | **Boolean Not** | ''not EXPR'' / ''! EXPR'' | Inverts a boolean value. | ''not isNull(i1)'' | | ||
| | 9 | **Negate** | ''-EXPR'' | Arithmetic negation. | ''-ceil(i1 + i2)'' | | | 9 | **Negate** | ''-EXPR'' | Arithmetic negation. | ''-ceil(i1 + i2)'' | | ||
| - | |||
| - | > **Note on null and equality:** Writing ''i1 == null'' does **not** test for null — because null participates in no arithmetic comparison, it always produces null itself, poisoning the expression. Always use ''isNull(i1)'' instead. See the [[#null_value_handling|Null Value Handling]] section for full details. | ||
| ---- | ---- | ||
| Line 241: | Line 239: | ||
| ===== Clamping Functions ===== | ===== Clamping Functions ===== | ||
| + | |||
| + | All clamping functions are available in all five calculator functors. | ||
| ^ Function ^ Syntax ^ Description ^ Example ^ | ^ Function ^ Syntax ^ Description ^ Example ^ | ||
| Line 248: | Line 248: | ||
| ===== Random / Stochastic Functions ===== | ===== Random / Stochastic Functions ===== | ||
| - | These functions generate a new random sample **for each evaluation unit** each time the expression is evaluated. In [[Calculate Map]] and [[Calculate Categorical Map]], this means one sample per cell, making them suitable for spatially stochastic models. In [[Calculate Lookup Table Values]] and [[Calculate Lookup Table Keys And Values]], one sample is drawn per table row. In [[Calculate Value]], a single sample is drawn for the whole expression. | + | All stochastic functions are available in all five calculator functors. They generate a new random sample **for each evaluation unit** each time the expression is evaluated. In [[Calculate Map]] and [[Calculate Categorical Map]], this means one sample per cell, making them suitable for spatially stochastic models. In [[Calculate Lookup Table Values]] and [[Calculate Lookup Table Keys And Values]], one sample is drawn per table row. In [[Calculate Value]], a single sample is drawn for the whole expression. |
| ^ Function ^ Syntax ^ Description ^ Example ^ | ^ Function ^ Syntax ^ Description ^ Example ^ | ||
| Line 259: | Line 259: | ||
| ^ Function ^ Syntax ^ Description ^ Example ^ | ^ Function ^ Syntax ^ Description ^ Example ^ | ||
| - | | Literal value | ''2'', ''-3.5e-2'', etc. | Any numeric literal, including scientific notation. | ''2 + i1 / -3.5e-2'' | | + | | Literal value | ''2'', ''-3.5e-2'', etc. | Any numeric literal, including scientific notation. Available in all five calculator functors. | ''2 + i1 / -3.5e-2'' | |
| - | | Abort | ''abort'' | Immediately halts model execution. Useful as a guard inside a conditional to catch unexpected states. | ''if i1 > 0 then i1 * i2 + 4 else abort'' | | + | | Abort | ''abort'' | Immediately halts model execution. Useful as a guard inside a conditional to catch unexpected states. Available in all five calculator functors. | ''if i1 > 0 then i1 * i2 + 4 else abort'' | |
| | Is Null | ''isNull(EXPR)'' | Returns 1 if the expression is null, 0 otherwise. Immune to the null poisoning rule — always resolves to 0 or 1. Available in all five calculator functors. | ''if not isNull(i1) then i1 else i2'' | | | Is Null | ''isNull(EXPR)'' | Returns 1 if the expression is null, 0 otherwise. Immune to the null poisoning rule — always resolves to 0 or 1. Available in all five calculator functors. | ''if not isNull(i1) then i1 else i2'' | | ||
| | Null | ''null'' | Makes the current evaluation unit null — the cell, row, or scalar result is marked as missing and any further arithmetic using it propagates null. This is an **abstract** null, not a numeric value; it cannot be used in arithmetic and has no numeric representation. Available in all five calculator functors. | ''if i1 > 2 then i1 else null'' | | | Null | ''null'' | Makes the current evaluation unit null — the cell, row, or scalar result is marked as missing and any further arithmetic using it propagates null. This is an **abstract** null, not a numeric value; it cannot be used in arithmetic and has no numeric representation. Available in all five calculator functors. | ''if i1 > 2 then i1 else null'' | | ||
| + | |||
| + | > **Note on null and equality:** Writing ''i1 == null'' does **not** test for null — because null participates in no arithmetic comparison, it always produces null itself, poisoning the expression. Always use ''isNull(i1)'' instead. See the [[#null_value_handling|Null Value Handling]] section for full details. | ||
| ---- | ---- | ||
| Line 373: | Line 375: | ||
| > **Availability:** [[Calculate Map]] and [[Calculate Categorical Map]] only. | > **Availability:** [[Calculate Map]] and [[Calculate Categorical Map]] only. | ||
| - | These operators compute a neighbourhood statistic and then use the result as an **index** to retrieve a value from either a lookup table or a second image. | + | These operators compute a neighbourhood statistic and then use the result as an **index** to retrieve a value from either a connected Lookup Table or a second image. ''TABLE'' below always refers to a **Lookup Table** specifically — see section 5 for the operators that query one directly. |
| + | |||
| + | > If ''TABLE'' is bound to a multi-column Table (not a Lookup Table), an error is reported. See section 6 for multi-column tables. | ||
| **Full syntax:** \\ | **Full syntax:** \\ | ||
| Line 383: | Line 387: | ||
| ''nbN(IMAGE, h, w, IMAGE2)'' | ''nbN(IMAGE, h, w, IMAGE2)'' | ||
| - | When a **TABLE** is provided: the statistic is used as a key to query the lookup table. \\ | + | When a **TABLE** (Lookup Table) is provided: the statistic is used as a key to query it, equivalent to ''TABLE[statistic]'' from section 5. \\ |
| When an **IMAGE2** is provided: the statistic is used as a pixel coordinate to sample ''IMAGE2''. | When an **IMAGE2** is provided: the statistic is used as a pixel coordinate to sample ''IMAGE2''. | ||
| ^ Operator ^ Syntax ^ Description ^ Example ^ | ^ Operator ^ Syntax ^ Description ^ Example ^ | ||
| - | | MinRef | ''nbMinRef(...)'' | Finds the minimum in the window, then uses it as an index. | ''nbMinRef(i4, 2, 3, t1, line, column)'' | | + | | MinRef | ''nbMinRef(...)'' | Finds the minimum in the window, then uses it as an index into the Lookup Table (or a coordinate into IMAGE2). | ''nbMinRef(i4, 2, 3, t1, line, column)'' | |
| - | | MaxRef | ''nbMaxRef(...)'' | Finds the maximum in the window, then uses it as an index. | ''nbMaxRef(i4, 2, 3, i1, line, column)'' | | + | | MaxRef | ''nbMaxRef(...)'' | Finds the maximum in the window, then uses it as an index into the Lookup Table (or a coordinate into IMAGE2). | ''nbMaxRef(i4, 2, 3, i1, line, column)'' | |
| ---- | ---- | ||
| Line 399: | Line 403: | ||
| **Syntax:** ''nbConvol(IMAGE, TABLE, h, w)'' / ''nbConvol(IMAGE, TABLE, h, w, y, x)'' | **Syntax:** ''nbConvol(IMAGE, TABLE, h, w)'' / ''nbConvol(IMAGE, TABLE, h, w, y, x)'' | ||
| + | |||
| + | > If ''TABLE'' is bound to a multi-column Table (not a Lookup Table), an error is reported. See section 6 for multi-column tables. | ||
| ^ Parameter ^ Meaning ^ | ^ Parameter ^ Meaning ^ | ||
| | ''IMAGE'' | The image to convolve (''iX'') | | | ''IMAGE'' | The image to convolve (''iX'') | | ||
| - | | ''TABLE'' | A Table whose entries are the kernel coefficients, indexed 1 to h*w, mapped **left-to-right, top-to-bottom** | | + | | ''TABLE'' | A **Lookup Table** whose entries are the kernel coefficients, indexed 1 to h*w, mapped **left-to-right, top-to-bottom**. | |
| | ''h'' | Number of kernel rows | | | ''h'' | Number of kernel rows | | ||
| | ''w'' | Number of kernel columns | | | ''w'' | Number of kernel columns | | ||
| | ''y'', ''x'' | Anchor position (optional; defaults to window centre) | | | ''y'', ''x'' | Anchor position (optional; defaults to window centre) | | ||
| - | Each cell in the window is assigned a unique integer key, starting at 1 and advancing left-to-right, then top-to-bottom. The ''TABLE'' argument must contain one row per window cell, where the key is that cell's index and the value is its convolution coefficient. The result of ''nbConvol'' is the weighted sum of all pixel values in the window, each multiplied by the coefficient stored at the corresponding key in the table. | + | Each cell in the window is assigned a unique integer key, starting at 1 and advancing left-to-right, then top-to-bottom. The ''TABLE'' argument must be a Lookup Table containing one row per window cell, where the key is that cell's index and the value is its convolution coefficient. The result of ''nbConvol'' is the weighted sum of all pixel values in the window, each multiplied by the coefficient stored at the corresponding key in the table. |
| The grids below illustrate the index mapping for some common window sizes: | The grids below illustrate the index mapping for some common window sizes: | ||
| Line 889: | Line 895: | ||
| | Calculate Lookup Table Values | ''CalculateLookupTableValues'' | | | Calculate Lookup Table Values | ''CalculateLookupTableValues'' | | ||
| | Calculate Lookup Table Keys and Values | ''CalculateLookupTableKeysAndValues'' | | | Calculate Lookup Table Keys and Values | ''CalculateLookupTableKeysAndValues'' | | ||
| - | |||