ST_H3Bin

ST_H3Bin takes a geometry column and a numeric H3 resolution and returns a bin column. The output column contains a single H3 bin at the specified resolution for each record in the input column. H3 is a hierarchical geospatial indexing system that partitions the world sphere into hexagonal and pentagonal tiles. H3 supports 16 resolutions ranging from 0 to 15, where 0 results in the largest bins and 15 the smallest. For detailed information on the number of bins and average bin areas at every resolution, refer to the H3 Tables of Cell Statistics Across Resolutions.

With ST_H3Bin, the centroid of the input geometry is guaranteed to intersect with the bin returned but is not necessarily coincident with the bin center. Use ST_BinGeometry to obtain the geometry of each result bin. This function can also be called with a long column representing the ID of the bin (see ST_BinId). The bin ID will be cast to a bin column.

ST_H3Bin requires the spatial reference to be set to World Geodetic System 1984 (EPSG:4326). If the input geometry is in a different spatial reference, the function automatically transforms the geometry into World Geodetic System 1984. To learn more about spatial references, see Coordinate systems and transformations.

Java bindings for H3 are required to run ST_H3Bins. For example, on Spark local mode, you can start a Spark session with the H3 Java bindings by adding --packages com.uber:h3:4.0.1 as shown below.

Windows

Linux

Use dark colors for code blocksCopy

pyspark --jars C:\engine\geoanalytics.jar ^
        --py-files C:\data\engine\geoanalytics.zip ^
        --conf spark.plugins=com.esri.geoanalytics.Plugin ^
        --conf spark.serializer=org.apache.spark.serializer.KryoSerializer ^
        --conf spark.kryo.registrator=com.esri.geoanalytics.KryoRegistrator ^
        --packages com.uber:h3:4.0.1

Function	Syntax
Python	`h3_bin(geometry, h3_resolution)`
SQL	`ST_H3Bin(geometry, h3_resolution)`
Scala	`h3Bin(geometry, h3Resolution)`

For more details, go to the GeoAnalytics Engine API reference for h3_bin.

Python and SQL Examples

Python

SQL

Use dark colors for code blocksCopy
from geoanalytics.sql import functions as ST

data = [
    ("POINT (-117.05 34.22)",),
    ("LINESTRING (-116.89 33.96, -116.71 34.01, -116.66 34.08)", ),
    ("POLYGON ((-117.27 34.05, -117.22 33.91, -116.96 33.64, -116.66 33.71, -117.08 33.91, -117.16 34.09, -117.27 34.05))", )
]

df = spark.createDataFrame(data, ["wkt"])\
          .withColumn("geometry", ST.geom_from_text("wkt", srid=4326))\
          .withColumn("bin", ST.bin_geometry(ST.h3_bin("geometry", 6)))

ax = df.st.plot("geometry", facecolor="none", edgecolor="red")
df.st.plot("bin", ax=ax, facecolor="none", edgecolor="blue")

Plotting example for ST_H3Bin — Plotted result for ST_H3Bin.

Scala Example

Scala
Use dark colors for code blocksCopy
import com.esri.geoanalytics.sql.{functions => ST}
import org.apache.spark.sql.{functions => F}

case class GeometryRow(wkt: String)
val data = Seq(GeometryRow("POINT (-117.05 34.22)"),
               GeometryRow("LINESTRING (-116.89 33.96, -116.71 34.01, -116.66 34.08)"),
               GeometryRow("POLYGON ((-117.27 34.05, -117.22 33.91, -116.96 33.64, -116.66 33.71, -117.08 33.91, -117.16 34.09, -117.27 34.05))"))

val df = spark.createDataFrame(data)
              .withColumn("geometry", ST.geomFromText($"wkt", F.lit(4326)))
              .withColumn("h3_bin", ST.h3Bin($"geometry", 6))

df.select("h3_bin").show(truncate = false)

Result
Use dark colors for code blocksCopy
+----------------------+
|h3_bin                |
+----------------------+
|bin#604214655010734079|
|bin#604214642662703103|
|bin#604214632193720319|
+----------------------+

Version table

Release	Notes
1.1.0	Python and SQL functions introduced
1.5.0	Scala function introduced

ST_H3Bin

Python and SQL Examples

Scala Example

Version table

Related topics