Differences
This shows you the differences between two versions of the page.
| Next revision | Previous revision | ||
|
calculate_lookup_table_keys_and_values [2025/12/02 03:24] admin created |
calculate_lookup_table_keys_and_values [2026/07/15 01:21] (current) hermann |
||
|---|---|---|---|
| Line 3: | Line 3: | ||
| ===== Description ===== | ===== Description ===== | ||
| - | This functor generates a new lookup table from other tables, using one expression to define the new keys and another to define the new values. | + | Generates a new lookup table by evaluating **two separate expressions** once per row of a base lookup table — one expression for the output key and one for the output value. This allows complete transformation of a table's key-value structure, or construction of an entirely new lookup table row by row. |
| + | |||
| + | This functor is one of five in the [[calculate_functors|calculator family]]. Use it when you need to recompute both the keys and the values of a lookup table. If only the values need to be recomputed and the keys should be inherited from the base table, use [[Calculate Lookup Table Values]] 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 ===== | ===== Inputs ===== | ||
| - | ^ Name ^ Type ^ Description ^ | + | ^ Name ^ Type ^ Description ^ |
| - | | Key Column Expression | [[Image Expression Type]] | Expression describing how the value of each new key should be calculated. | | + | | Key Column Expression | [[Image Expression Type]] | The formula evaluated for each row to produce the output key. Must be enclosed in square brackets ''[ ]'' in EGO Script. | |
| - | | Value Column Expression | [[Image Expression Type]] | Expression describing how each new value should be calculated. | | + | | Value Column Expression | [[Image Expression Type]] | The formula evaluated for each row to produce the output value. Must be enclosed in square brackets ''[ ]'' in EGO Script. | |
| ===== Optional Inputs ===== | ===== Optional Inputs ===== | ||
| - | ^ Name ^ Type ^ Description ^ Default Value ^ | + | ^ Name ^ Type ^ Default ^ Description ^ |
| - | | Key Column Name | [[Name Type]] | Name of the key column. If omitted, the corresponding name from the table used as format will be used. | None | | + | | Key Column Name | [[Name Type]] | None | Name of the key column in the output lookup table. If omitted, the corresponding name from the base table is used. | |
| - | | Value Column Name | [[Name Type]] | Name of the value column. If omitted, the corresponding name from the table used as format will be used. | None | | + | | Value Column Name | [[Name Type]] | None | Name of the value column in the output lookup table. If omitted, the corresponding name from the base table is used. | |
| - | | Base Lookup Table | [[Lookup Table Type]] | Lookup table that, if provided, determines for which entries the key and value generation expressions will be called. If this table is not provided, the first lookup table present in the list of input tables will be used. | None | | + | | Base Lookup Table | [[Lookup Table Type]] | None | The lookup table whose row set drives iteration. When not provided, the [[Number Table]] 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 referenced by name in the expression (abbreviated form) — not a union of all connected tables. Prefer this port over a ''Number Table'' 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 ===== | ||
| - | ^ Name ^ Type ^ Description ^ | + | ^ Name ^ Type ^ Description ^ |
| - | | Result | [[Lookup Table Type]] | Lookup table calculated from the input tables and values. | | + | | Result | [[Lookup Table Type]] | A lookup table with both keys and values computed by the respective expressions. | |
| ===== Group ===== | ===== Group ===== | ||
| Line 29: | Line 33: | ||
| ===== Notes ===== | ===== Notes ===== | ||
| - | For each key present in the input table used as format, a key-value pair will be created and inserted into the resulting table. If the generated key is equal to a previously generated key, the new generated value will be used to replace the existing value. | + | ==== Connecting data inputs ==== |
| - | The values of the key and value columns from the table used as format will be accessible during calculation as "line" and "column", respectively, in the expressions for calculating keys and values of the resulting lookup table. | + | |
| + | Tables, lookup tables, and scalar values referenced in either expression must be connected to the functor's ports before writing the expressions, using **hook** functors: | ||
| + | |||
| + | * Tables and lookup tables → [[Number Table]] → referenced in the expression as ''t1'', ''t2'', …, ''t100'' | ||
| + | * Scalar values → [[Number Value]] → referenced as ''v1'', ''v2'', …, ''v100'' | ||
| + | |||
| + | Maps cannot be connected — there is no cell context in this functor. In the abbreviated syntax, tables are referenced as ''%variableName'' and values as ''$variableName''. Both expressions share the same set of connected operands. | ||
| + | |||
| + | ==== Row iteration context ==== | ||
| + | |||
| + | Both expressions are evaluated once per row of the base lookup table. Two keywords reflect the current row inside each expression: | ||
| + | |||
| + | * ''line'' — the **key** of the current row | ||
| + | * ''column'' — the **value already associated with that key** in the base lookup table | ||
| + | |||
| + | If the key expression produces a key that already exists in the output table, the newly computed value replaces the existing one. | ||
| + | |||
| + | ==== Available expression features ==== | ||
| + | |||
| + | Identical to [[Calculate Lookup Table Values]]: arithmetic and logical operators, scalar references (''vX''), table and lookup table queries (''tX[...]'') in all single-key and multi-column forms, and the ''line'' and ''column'' row-context keywords are available. Image operators (''iX''), neighbourhood functions, neighbourhood indexing, and convolution are not available. See [[calculate_functors#the_expression_language|The Expression Language]] for the complete reference, or [[Image Expression Type]] for the navigable operator index. | ||
| + | |||
| + | ==== Null value handling ==== | ||
| + | |||
| + | Null propagation rules and defensive patterns are covered in [[calculate_functors#null_value_handling|Null Value Handling]] in the Calculate Functors documentation. | ||
| ===== Internal Name ===== | ===== Internal Name ===== | ||
| - | CalculateLookupTableKeysAndValues | + | ''CalculateLookupTableKeysAndValues'' |