H3HexagonalIndexer
Computes and manipulates hexagonal hierarchical spatial indexes (Uber H3), and enables spatial data to be grouped into hexagonal grid cells for analysis and visualization.
Typical Uses
- Replace the point geometry of a feature with the H3 hexagon that contains it
- Calculate the H3 Index for a given point at a supplied H3 resolution
- Return all the H3 indices that are contained by an area, so that spatial containment can be done by comparing indices
- Return all the neighbor H3 indices of a given index
- Return the parent (lower resolution) H3 index of a given index
- Return all the child (higher resolution) H3 indexes of a given index.
How does it work?
The H3HexagonalIndexer provides easy access within an FME workflow to the key operations made available by the open source Uber H3 library. This library partitions the earth into a set of 16 different hexagonal grids, ranging in size from 122 cells covering the earth at level 0, all the way to the finest-grained cells at level 15 with edges approximately 0.5 m long.
The transformer operates on one feature at a time, doing the requested index operation, and optionally changing the geometry to the hexagon of the computed index or removing the geometry entirely. Operations which result in several indexes being returned (such as neighbor or child computation) copy the input feature for each resulting index, adding the computed index as a new attribute and optionally changing the geometry.
The most common operation is to compute an hexagonal index for an appropriate-for-use resolution and replace the geometry of the feature with this hexagon for downstream aggregation (typically by a StatisticsCalculator) for visualization.
Another common use case is to calculate the index and remove the geometry, so that downstream storage and analysis operate only on the index and thus can be done using relational rather than spatial computation.
This transformer is implemented such that there is always one feature per H3 Index. Only one index will be read per input feature and one output feature will be generated for every H3 Index that is output. The output features will be clones of the input feature except for the new data and any changes to geometry specified by the Geometry Handling parameter.
Note that features must have geographic coordinates (latitude/longitude).
H3 was designed for managing and understanding high volumes of GPS reported locations, and as such, exact accuracy in some of the operations is not possible. For example, child hexagons and a finer resolution are not all strictly contained in their parent. Further, the parent of a child hexagon containing a point may not be the same hexagon as if the index were computed at the parent level for the original point. If exact containment is needed, then spatial operations present in the PointOnAreaOverlayer or SpatialFilter/SpatialRelator maybe more appropriate.
Usage Notes
- Features must be in a geographic coordinate system (latitude/longitude). The Reprojector or its related transformers may be used to reproject from other coordinate systems.
Configuration
Input Ports
This transformer accepts features with geographic coordinates (latitude/longitude).
Output Ports
Features with added attributes and/or geometry as specified in parameters.
Features that could not be processed by the selected Operation will be output through this port.
Rejected features will have an fme_rejection_code attribute.
Rejected Feature Handling: can be set to either terminate the translation or continue running when it encounters a rejected feature. This setting is available both as a default FME option and as a workspace parameter.
Parameters
Get |
Specify the H3 computation to be performed on the input features. Choices include:
|
Available General parameters will vary according to the selected Get parameter.
Center Point From Index
Index |
Attribute that holds the input H3 Index |
Child Indexes
Parent Index |
Attribute that holds the input H3 Index |
Child Index Resolution |
The resolution of the child H3 Indexes that will be returned |
Geometry Handling |
Keep: Keep any geometry that is on the feature Remove: Remove any geometry that is on the feature Replace With Hexagon: Remove the geometry from the input feature and replace it with the hexagon represented by the child H3 Index on each of the output features |
Filling Indexes
Index Resolution |
Resolution of the H3 Indexes that will fill the Geometry |
Compact Indexes |
Recursively replace full child branches with their parent H3 Index. Results in the minimum number of H3 Indexes that perfectly cover the Geometry. The resulting indexes will be at different levels, but will have the least number of indexes to fully fill the area. |
Geometry Handling |
Keep: Keep any geometry that is on the feature Remove: Remove any geometry that is on the feature Replace With Hexagon: Remove the geometry from the input feature and replace it with the hexagon represented by the child H3 Index on each of the output features |
Hexagon From Index
Index |
H3 Index to get the H3 Hexagon for |
Index
Index Resolution |
Resolution of the H3 Index that contains the center point of the Geometry |
Geometry Handling |
Keep: Keep any geometry that is on the feature Remove: Remove any geometry that is on the feature Replace With Hexagon: Remove the geometry from the input feature and replace it with the hexagon represented by the child H3 Index on each of the output features |
Neighboring Hexagon Indexes
Index |
H3 Index to get the neighbors of |
Maximum Distance (Hexagons) |
Maximum distance (in hexagons) that neighboring H3 Indexes will be returned from |
Geometry Handling |
Keep: Keep any geometry that is on the feature Remove: Remove any geometry that is on the feature Replace With Hexagon: Remove the geometry from the input feature and replace it with the hexagon represented by the child H3 Index on each of the output features |
Parent Index
Child Index |
H3 Index to get the parent of |
Parent Index Resolution |
Resolution of the parent H3 Index |
Geometry Handling |
Keep: Keep any geometry that is on the feature Remove: Remove any geometry that is on the feature Replace With Hexagon: Remove the geometry from the input feature and replace it with the hexagon represented by the child H3 Index on each of the output features |
Resolution
Index |
H3 Index to get the resolution of |
Validity
Index |
H3 Index to check the validity of |
Available Output Attribute Names parameters will vary according to the selected Get parameter.
Child Indexes
Child Index |
Attribute that holds the output child H3 Indexes |
Filling Indexes
Polyfill Index |
Attribute that holds the output H3 Indexes that fill the Geometry |
Index
Index |
Attribute that holds the output H3 Index |
Neighboring Hexagon Indexes
Neighbor Index |
Attribute that holds the neighbor H3 Indexes |
Distance |
Attribute that holds the distance of the neighbor H3 Index from the input H3 Index |
Parent Index
Parent Index |
Attribute that holds the parent H3 Index |
Resolution
Index Resolution |
Attribute that holds the resolution of the input H3 Index |
Editing Transformer Parameters
Using a set of menu options, transformer parameters can be assigned by referencing other elements in the workspace. More advanced functions, such as an advanced editor and an arithmetic editor, are also available in some transformers. To access a menu of these options, click beside the applicable parameter. For more information, see Transformer Parameter Menu Options.
Defining Values
There are several ways to define a value for use in a Transformer. The simplest is to simply type in a value or string, which can include functions of various types such as attribute references, math and string functions, and workspace parameters. There are a number of tools and shortcuts that can assist in constructing values, generally available from the drop-down context menu adjacent to the value field.
Using the Text Editor
The Text Editor provides a convenient way to construct text strings (including regular expressions) from various data sources, such as attributes, parameters, and constants, where the result is used directly inside a parameter.
Using the Arithmetic Editor
The Arithmetic Editor provides a convenient way to construct math expressions from various data sources, such as attributes, parameters, and feature functions, where the result is used directly inside a parameter.
Conditional Values
Set values depending on one or more test conditions that either pass or fail.
Parameter Condition Definition Dialog
Content
Expressions and strings can include a number of functions, characters, parameters, and more.
When setting values - whether entered directly in a parameter or constructed using one of the editors - strings and expressions containing String, Math, Date/Time or FME Feature Functions will have those functions evaluated. Therefore, the names of these functions (in the form @<function_name>) should not be used as literal string values.
These functions manipulate and format strings. | |
Special Characters |
A set of control characters is available in the Text Editor. |
Math functions are available in both editors. | |
Date/Time Functions | Date and time functions are available in the Text Editor. |
These operators are available in the Arithmetic Editor. | |
These return primarily feature-specific values. | |
FME and workspace-specific parameters may be used. | |
Creating and Modifying User Parameters | Create your own editable parameters. |
Dialog Options - Tables
Transformers with table-style parameters have additional tools for populating and manipulating values.
Row Reordering
|
Enabled once you have clicked on a row item. Choices include:
|
Cut, Copy, and Paste
|
Enabled once you have clicked on a row item. Choices include:
Cut, copy, and paste may be used within a transformer, or between transformers. |
Filter
|
Start typing a string, and the matrix will only display rows matching those characters. Searches all columns. This only affects the display of attributes within the transformer - it does not alter which attributes are output. |
Import
|
Import populates the table with a set of new attributes read from a dataset. Specific application varies between transformers. |
Reset/Refresh
|
Generally resets the table to its initial state, and may provide additional options to remove invalid entries. Behavior varies between transformers. |
Note: Not all tools are available in all transformers.
Reference
Processing Behavior |
|
Feature Holding |
No |
Dependencies | |
Aliases | H3Indexer |
History |
FME Community
The FME Community is the place for demos, how-tos, articles, FAQs, and more. Get answers to your questions, learn from other users, and suggest, vote, and comment on new features.
Search for all results about the H3HexagonalIndexer on the FME Community.
Examples may contain information licensed under the Open Government Licence – Vancouver and/or the Open Government Licence – Canada.