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.
Jump to Configuration
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
Input
This transformer accepts features with geographic coordinates (latitude/longitude).
Output Ports
Output
Features with added attributes and/or geometry as specified in parameters.
<Rejected>
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
Operation
Get
|
Specify the H3 computation to be performed on the input features.
Choices include:
Center Point from Index
|
Get the center point of the H3 Hexagon defined by the provided H3 Index.
|
Child Indexes
|
Get all child H3 Indexes of the provided index at the provided resolution.
Each index is output on a separate copy of the input feature.
|
Filling Indexes
|
Get all H3 Indexes that fill the provided geometry at the given resolution.
If the input feature is a line or a point, the H3 indexes will cover the line or point. If the input feature is an area, the H3 indexes will fill the area (but may leave some gaps around the area’s boundary)
Each index is output on a separate copy of the input feature.
|
Hexagon From Index
|
Replaces the geometry of the feature with the H3 Hexagon that is represented by the provided H3 Index.
|
Index
|
Get the H3 Index for the H3 Hexagon that contains the center point of the provided geometry at the specified H3 resolution
|
Neighboring Hexagon Indexes
|
Get all neighboring H3 Indexes of the provided H3 Index out to the provided distance (which is measured in H3 cells). For example, a distance of 1 is all the direct neighbours of the input cell.
Each index is output on a separate copy of the input feature.
|
Parent Index
|
Returns the parent (at the provided resolution) H3 Index of the provided H3 Index
|
Resolution
|
Returns the resolution of the provided H3 Index
|
Validity
|
Confirms the validity of the provided H3 Index. Invalid H3 Indexes are rejected.
|
|
General
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
|
Output Attribute Names
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.
How to Set Parameter Values
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.
Text Editor
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.
Arithmetic Editor
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.
Dialog Options - Tables
Transformers with table-style parameters have additional tools for populating and manipulating values.
Table Tools
Row Reordering
|
Enabled once you have clicked on a row item. Choices include:
- Add a row
- Remove a row
- Move current row up one
- Move current row down one
- Move current row to top
- Move current row to bottom
|
Cut, Copy, and Paste
|
Enabled once you have clicked on a row item. Choices include:
- Cut a row - delete and copy to clipboard
- Copy a row to the clipboard
- Paste a row from the clipboard
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-Based
|
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.