=====================
Spatial grid indexing
=====================

Spatial grid indexing is the process of mapping a geometry (or a point) to one or more cells (or cell ID)
from the selected spatial grid.

The grid system can be specified by using the spark configuration :code:`spark.databricks.labs.mosaic.index.system`
before enabling Mosaic.

The valid values are:

    * :code:`H3` - Good all-rounder for any location on earth
    * :code:`BNG` - Local grid system Great Britain (EPSG:27700)
    * :code:`CUSTOM(minX,maxX,minY,maxY,splits,rootCellSizeX,rootCellSizeY)` - Can be used with any local or global CRS
        * :code:`minX`, :code:`maxX`, :code:`minY`, :code:`maxY` can be positive or negative integers defining the grid bounds
        * :code:`splits` defines how many splits are applied to each cell for an increase in resolution step (usually 2 or 10)
        * :code:`rootCellSizeX`, :code:`rootCellSizeY` define the size of the cells on resolution 0

Example

.. tabs::
   .. code-tab:: py

    spark.conf.set("spark.databricks.labs.mosaic.index.system", "H3") # Default
    # spark.conf.set("spark.databricks.labs.mosaic.index.system", "BNG")
    # spark.conf.set("spark.databricks.labs.mosaic.index.system", "CUSTOM(-180,180,-90,90,2,30,30)")

    import mosaic as mos
    mos.enable_mosaic(spark, dbutils)


grid_longlatascellid
********************

.. function:: grid_longlatascellid(lon, lat, resolution)

    Returns the :code:`resolution` grid index associated with
    the input :code:`lon` and :code:`lat` coordinates.

    :param lon: Longitude
    :type lon: Column: DoubleType
    :param lat: Latitude
    :type lat: Column: DoubleType
    :param resolution: Index resolution
    :type resolution: Column: Integer
    :rtype: Column: LongType

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{'lon': 30., 'lat': 10.}])
    df.select(grid_longlatascellid('lon', 'lat', lit(10))).show(1, False)
    +----------------------------------+
    |grid_longlatascellid(lon, lat, 10)|
    +----------------------------------+
    |                623385352048508927|
    +----------------------------------+

   .. code-tab:: scala

    val df = List((30.0, 10.0)).toDF("lon", "lat")
    df.select(grid_longlatascellid(col("lon"), col("lat"), lit(10))).show()
    +----------------------------------+
    |grid_longlatascellid(lon, lat, 10)|
    +----------------------------------+
    |                623385352048508927|
    +----------------------------------+

   .. code-tab:: sql

    SELECT grid_longlatascellid(30d, 10d, 10)
    +----------------------------------+
    |grid_longlatascellid(lon, lat, 10)|
    +----------------------------------+
    |                623385352048508927|
    +----------------------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(lon = 30.0, lat = 10.0))
    showDF(select(df, grid_longlatascellid(column("lon"), column("lat"), lit(10L))), truncate=F)
    +----------------------------------+
    |grid_longlatascellid(lon, lat, 10)|
    +----------------------------------+
    |                623385352048508927|
    +----------------------------------+

.. raw:: html

   <div class="figure-group">


.. figure:: ../images/grid_longlatascellid/h3.png
   :figclass: doc-figure-float-left

   Fig 1. Point to grid cell in H3(9)


.. figure:: ../images/grid_longlatascellid/bng.png
   :figclass: doc-figure-float-left

   Fig 2. Point to grid cell in BNG(4)


.. raw:: html

   </div>


grid_pointascellid
******************

.. function:: grid_pointascellid(geometry, resolution)

    Returns the :code:`resolution` grid index associated
    with the input point geometry :code:`geometry`.

    :param geometry: Geometry
    :type geometry: Column
    :param resolution: Index resolution
    :type resolution: Column: Integer
    :rtype: Column: LongType

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{'lon': 30., 'lat': 10.}])
    df.select(grid_pointascellid(st_point('lon', 'lat'), lit(10))).show(1, False)
    +------------------------------------------+
    |grid_pointascellid(st_point(lon, lat), 10)|
    +------------------------------------------+
    |623385352048508927                        |
    +------------------------------------------+

   .. code-tab:: scala

    val df = List((30.0, 10.0)).toDF("lon", "lat")
    df.select(grid_pointascellid(st_point(col("lon"), col("lat")), lit(10))).show()
    +------------------------------------------+
    |grid_pointascellid(st_point(lon, lat), 10)|
    +------------------------------------------+
    |623385352048508927                        |
    +------------------------------------------+

   .. code-tab:: sql

    SELECT grid_pointascellid(st_point(30d, 10d), 10)
    +------------------------------------------+
    |grid_pointascellid(st_point(lon, lat), 10)|
    +------------------------------------------+
    |623385352048508927                        |
    +------------------------------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(lon = 30.0, lat = 10.0))
    showDF(select(df, grid_pointascellid(st_point(column("lon"), column("lat")), lit(10L))), truncate=F)
    +------------------------------------------+
    |grid_pointascellid(st_point(lon, lat), 10)|
    +------------------------------------------+
    |623385352048508927                        |
    +------------------------------------------+

.. raw:: html

   <div class="figure-group">


.. figure:: ../images/grid_longlatascellid/h3.png
   :figclass: doc-figure-float-left

   Fig 1. Point to grid cell in H3(9)


.. figure:: ../images/grid_longlatascellid/bng.png
   :figclass: doc-figure-float-left

   Fig 2. Point to grid cell in BNG(4)


.. raw:: html

   </div>


grid_polyfill
*************

.. function:: grid_polyfill(geometry, resolution)

    Returns the set of grid indices of which centroid is contained in the input :code:`geometry` at :code:`resolution`.

    When using `H3 <https://h3geo.org/>`_ index system, this is equivalent to the
    `H3 polyfill <https://h3geo.org/docs/api/regions/#polyfill>`_ method

    :param geometry: Geometry
    :type geometry: Column
    :param resolution: Index resolution
    :type resolution: Column: Integer
    :rtype: Column: ArrayType[LongType]

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{
        'wkt': 'MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))'
        }])
    df.select(grid_polyfill('wkt', lit(0))).show(1, False)
    +------------------------------------------------------------+
    |grid_polyfill(wkt, 0)                                       |
    +------------------------------------------------------------+
    |[577586652210266111, 578360708396220415, 577269992861466623]|
    +------------------------------------------------------------+

   .. code-tab:: scala

    val df = List(("MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))")).toDF("wkt")
    df.select(grid_polyfill(col("wkt"), lit(0))).show(false)
    +------------------------------------------------------------+
    |grid_polyfill(wkt, 0)                                       |
    +------------------------------------------------------------+
    |[577586652210266111, 578360708396220415, 577269992861466623]|
    +------------------------------------------------------------+

   .. code-tab:: sql

    SELECT grid_polyfill("MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))", 0)
    +------------------------------------------------------------+
    |grid_polyfill(wkt, 0)                                       |
    +------------------------------------------------------------+
    |[577586652210266111, 578360708396220415, 577269992861466623]|
    +------------------------------------------------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(wkt = "MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))"))
    showDF(select(df, grid_polyfill(column("wkt"), lit(0L))), truncate=F)
    +------------------------------------------------------------+
    |grid_polyfill(wkt, 0)                                       |
    +------------------------------------------------------------+
    |[577586652210266111, 578360708396220415, 577269992861466623]|
    +------------------------------------------------------------+

.. raw:: html

   <div class="figure-group">


.. figure:: ../images/grid_polyfill/h3.png
   :figclass: doc-figure-float-left

   Fig 1. Polyfill of a polygon in H3(8)


.. figure:: ../images/grid_polyfill/bng.png
   :figclass: doc-figure-float-left

   Fig 2. Polyfill of a polygon in BNG(4)


.. raw:: html

   </div>



grid_boundaryaswkb
******************

.. function:: grid_boundaryaswkb(cellid)

    Returns the boundary of the grid cell as a WKB.

    :param cellid: Grid cell id
    :type cellid: Column: Union(LongType, StringType)

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{'cellid': 613177664827555839}])
    df.select(grid_boundaryaswkb("cellid").show(1, False)
    +--------------------------+
    |grid_boundaryaswkb(cellid)|
    +--------------------------+
    |[01 03 00 00 00 00 00 00..|
    +--------------------------+

   .. code-tab:: scala

    val df = List((613177664827555839)).toDF("cellid")
    df.select(grid_boundaryaswkb(col("cellid")).show()
    +--------------------------+
    |grid_boundaryaswkb(cellid)|
    +--------------------------+
    |[01 03 00 00 00 00 00 00..|
    +--------------------------+

   .. code-tab:: sql

    SELECT grid_boundaryaswkb(613177664827555839)
    +--------------------------+
    |grid_boundaryaswkb(cellid)|
    +--------------------------+
    |[01 03 00 00 00 00 00 00..|
    +--------------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(cellid = 613177664827555839))
    showDF(select(df, grid_boundaryaswkb(column("cellid")), truncate=F)
    +--------------------------+
    |grid_boundaryaswkb(cellid)|
    +--------------------------+
    |[01 03 00 00 00 00 00 00..|
    +--------------------------+



grid_boundary
******************

.. function:: grid_boundary(cellid, format)

    Returns the boundary of the grid cell as a geometry in specified format.

    :param cellid: Grid cell id
    :type cellid: Column: Union(LongType, StringType)
    :param format: Geometry format
    :type format: Column: StringType

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{'cellid': 613177664827555839}])
    df.select(grid_boundary("cellid", "WKT").show(1, False)
    +--------------------------+
    |grid_boundary(cellid, WKT)|
    +--------------------------+
    |          "POLYGON (( ..."|
    +--------------------------+

   .. code-tab:: scala

    val df = List((613177664827555839)).toDF("cellid")
    df.select(grid_boundary(col("cellid"), lit("WKT").show()
    +--------------------------+
    |grid_boundary(cellid, WKT)|
    +--------------------------+
    |          "POLYGON (( ..."|
    +--------------------------+

   .. code-tab:: sql

    SELECT grid_boundary(613177664827555839, "WKT")
    +--------------------------+
    |grid_boundary(cellid, WKT)|
    +--------------------------+
    |          "POLYGON (( ..."|
    +--------------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(cellid = 613177664827555839))
    showDF(select(df, grid_boundary(column("cellid"), lit("WKT")), truncate=F)
    +--------------------------+
    |grid_boundary(cellid, WKT)|
    +--------------------------+
    |          "POLYGON (( ..."|
    +--------------------------+

grid_tessellate
***************

.. function:: grid_tessellate(geometry, resolution, <keep_core_geometries>)

    Cuts the original :code:`geometry` into several pieces along the grid index borders at the specified :code:`resolution`.

    Returns an array of Mosaic chips **covering** the input :code:`geometry` at :code:`resolution`.

    A Mosaic chip is a struct type composed of:

    - :code:`is_core`: Identifies if the chip is fully contained within the geometry: Boolean

    - :code:`index_id`: Index ID of the configured spatial indexing (default H3): Integer

    - :code:`wkb`: Geometry in WKB format equal to the intersection of the index shape and the original :code:`geometry`: Binary

    In contrast to :ref:`grid_tessellateexplode`, :ref:`grid_tessellate` does not explode the list of shapes.

    In contrast to :ref:`grid_polyfill`, :ref:`grid_tessellate` fully covers the original :code:`geometry` even if the index centroid
    falls outside of the original geometry. This makes it suitable to index lines as well.

    :param geometry: Geometry
    :type geometry: Column
    :param resolution: Index resolution
    :type resolution: Column (IntegerType)
    :param keep_core_geometries: Whether to keep the core geometries or set them to null, default true
    :type keep_core_geometries: Column (BooleanType)
    :rtype: Column: ArrayType[MosaicType]

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{'wkt': 'MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))'}])
    df.select(grid_tessellate('wkt', lit(0))).printSchema()
    root
     |-- grid_tessellate(wkt, 0): mosaic (nullable = true)
     |    |-- chips: array (nullable = true)
     |    |    |-- element: mosaic_chip (containsNull = true)
     |    |    |    |-- is_core: boolean (nullable = true)
     |    |    |    |-- index_id: long (nullable = true)
     |    |    |    |-- wkb: binary (nullable = true)


    df.select(grid_tessellate('wkt', lit(0))).show()
    +-----------------------+
    |grid_tessellate(wkt, 0)|
    +-----------------------+
    |   {[{false, 5774810...|
    +-----------------------+

   .. code-tab:: scala

    val df = List(("MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))")).toDF("wkt")
    df.select(grid_tessellate(col("wkt"), lit(0))).printSchema
    root
     |-- grid_tessellate(wkt, 0): mosaic (nullable = true)
     |    |-- chips: array (nullable = true)
     |    |    |-- element: mosaic_chip (containsNull = true)
     |    |    |    |-- is_core: boolean (nullable = true)
     |    |    |    |-- index_id: long (nullable = true)
     |    |    |    |-- wkb: binary (nullable = true)

    df.select(grid_tessellate(col("wkt"), lit(0))).show()
    +-----------------------+
    |grid_tessellate(wkt, 0)|
    +-----------------------+
    |   {[{false, 5774810...|
    +-----------------------+

   .. code-tab:: sql

    SELECT grid_tessellate("MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))", 0)
    +-----------------------+
    |grid_tessellate(wkt, 0)|
    +-----------------------+
    |   {[{false, 5774810...|
    +-----------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(wkt = "MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))"))
    schema(select(df, grid_tessellate(column("wkt"), lit(0L))))
    root
     |-- grid_tessellate(wkt, 0): mosaic (nullable = true)
     |    |-- chips: array (nullable = true)
     |    |    |-- element: mosaic_chip (containsNull = true)
     |    |    |    |-- is_core: boolean (nullable = true)
     |    |    |    |-- index_id: long (nullable = true)
     |    |    |    |-- wkb: binary (nullable = true)
    showDF(select(df, grid_tessellate(column("wkt"), lit(0L))))
    +-----------------------+
    |grid_tessellate(wkt, 0)|
    +-----------------------+
    |   {[{false, 5774810...|
    +-----------------------+

.. raw:: html

   <div class="figure-group">


.. figure:: ../images/grid_tessellate/h3.png
   :figclass: doc-figure-float-left

   Fig 1. Tessellation of a polygon in H3(8)


.. figure:: ../images/grid_tessellate/bng.png
   :figclass: doc-figure-float-left

   Fig 2. Tessellation of a polygon in BNG(4)


.. raw:: html

   </div>



grid_tessellateexplode
**********************

.. function:: grid_tessellateexplode(geometry, resolution, <keep_core_geometries>)

    Cuts the original :code:`geometry` into several pieces along the grid index borders at the specified :code:`resolution`.

    Returns the set of Mosaic chips **covering** the input :code:`geometry` at :code:`resolution`.

    A Mosaic chip is a struct type composed of:

    - :code:`is_core`: Identifies if the chip is fully contained within the geometry: Boolean

    - :code:`index_id`: Index ID of the configured spatial indexing (default H3): Integer

    - :code:`wkb`: Geometry in WKB format equal to the intersection of the index shape and the original :code:`geometry`: Binary

    In contrast to :ref:`grid_tessellate`, :ref:`grid_tessellateexplode` generates one result row per chip.

    In contrast to :ref:`grid_polyfill`, :ref:`grid_tessellateexplode` fully covers the original :code:`geometry` even if the index centroid
    falls outside of the original geometry. This makes it suitable to index lines as well.

    :param geometry: Geometry
    :type geometry: Column
    :param resolution: Index resolution
    :type resolution: Column (IntegerType)
    :param keep_core_geometries: Whether to keep the core geometries or set them to null, default true
    :type keep_core_geometries: Column (BooleanType)
    :rtype: Column: MosaicType

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{'wkt': 'MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))'}])
    df.select(grid_tessellateexplode('wkt', lit(0))).show()
    +-----------------------------------------------+
    |is_core|          index_id|                 wkb|
    +-------+------------------+--------------------+
    |  false|577481099093999615|[01 03 00 00 00 0...|
    |  false|578044049047420927|[01 03 00 00 00 0...|
    |  false|578782920861286399|[01 03 00 00 00 0...|
    |  false|577023702256844799|[01 03 00 00 00 0...|
    |  false|577938495931154431|[01 03 00 00 00 0...|
    |  false|577586652210266111|[01 06 00 00 00 0...|
    |  false|577269992861466623|[01 03 00 00 00 0...|
    |  false|578360708396220415|[01 03 00 00 00 0...|
    +-------+------------------+--------------------+

   .. code-tab:: scala

    val df = List(("MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))")).toDF("wkt")
    df.select(grid_tessellateexplode(col("wkt"), lit(0))).show()
    +-----------------------------------------------+
    |is_core|          index_id|                 wkb|
    +-------+------------------+--------------------+
    |  false|577481099093999615|[01 03 00 00 00 0...|
    |  false|578044049047420927|[01 03 00 00 00 0...|
    |  false|578782920861286399|[01 03 00 00 00 0...|
    |  false|577023702256844799|[01 03 00 00 00 0...|
    |  false|577938495931154431|[01 03 00 00 00 0...|
    |  false|577586652210266111|[01 06 00 00 00 0...|
    |  false|577269992861466623|[01 03 00 00 00 0...|
    |  false|578360708396220415|[01 03 00 00 00 0...|
    +-------+------------------+--------------------+

   .. code-tab:: sql

    SELECT grid_tessellateexplode("MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))", 0)
    +-----------------------------------------------+
    |is_core|          index_id|                 wkb|
    +-------+------------------+--------------------+
    |  false|577481099093999615|[01 03 00 00 00 0...|
    |  false|578044049047420927|[01 03 00 00 00 0...|
    |  false|578782920861286399|[01 03 00 00 00 0...|
    |  false|577023702256844799|[01 03 00 00 00 0...|
    |  false|577938495931154431|[01 03 00 00 00 0...|
    |  false|577586652210266111|[01 06 00 00 00 0...|
    |  false|577269992861466623|[01 03 00 00 00 0...|
    |  false|578360708396220415|[01 03 00 00 00 0...|
    +-------+------------------+--------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(wkt = 'MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))'))
    showDF(select(df, grid_tessellateexplode(column("wkt"), lit(0L))))
    +-----------------------------------------------+
    |is_core|          index_id|                 wkb|
    +-------+------------------+--------------------+
    |  false|577481099093999615|[01 03 00 00 00 0...|
    |  false|578044049047420927|[01 03 00 00 00 0...|
    |  false|578782920861286399|[01 03 00 00 00 0...|
    |  false|577023702256844799|[01 03 00 00 00 0...|
    |  false|577938495931154431|[01 03 00 00 00 0...|
    |  false|577586652210266111|[01 06 00 00 00 0...|
    |  false|577269992861466623|[01 03 00 00 00 0...|
    |  false|578360708396220415|[01 03 00 00 00 0...|
    +-------+------------------+--------------------+

.. raw:: html

   <div class="figure-group">


.. figure:: ../images/grid_tessellate/h3.png
   :figclass: doc-figure-float-left

   Fig 1. Tessellation of a polygon in H3(8)


.. figure:: ../images/grid_tessellate/bng.png
   :figclass: doc-figure-float-left

   Fig 2. Tessellation of a polygon in BNG(4)


.. raw:: html

   </div>


grid_cellarea
*************

.. function:: grid_cellarea(cellid)

    Returns the area of a given cell in km^2.

    :param cellid: Grid cell ID
    :type cellid: Column: Long
    :rtype: Column: DoubleType

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{'grid_cellid': 613177664827555839}])
    df.withColumn(grid_cellarea('grid_cellid').alias("area")).show()
    +------------------------------------+
    |         grid_cellid|           area|
    +--------------------+---------------+
    |  613177664827555839|     0.78595419|
    +--------------------+---------------+

   .. code-tab:: scala

    val df = List((613177664827555839)).toDF("grid_cellid")
    df.select(grid_cellarea('grid_cellid').alias("area")).show()
    +------------------------------------+
    |         grid_cellid|           area|
    +--------------------+---------------+
    |  613177664827555839|     0.78595419|
    +--------------------+---------------+

   .. code-tab:: sql

    SELECT grid_cellarea(613177664827555839)
    +------------------------------------+
    |         grid_cellid|           area|
    +--------------------+---------------+
    |  613177664827555839|     0.78595419|
    +--------------------+---------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(grid_cellid = 613177664827555839))
    showDF(select(df, grid_cellarea(column("grid_cellid"))))
    +------------------------------------+
    |         grid_cellid|           area|
    +--------------------+---------------+
    |  613177664827555839|     0.78595419|
    +--------------------+---------------+


grid_cellkring
**************

.. function:: grid_cellkring(cellid, k)

    Returns the k-ring of a given cell.

    :param cellid: Grid cell ID
    :type cellid: Column: Long
    :param k: K-ring size
    :type k: Column: Integer
    :rtype: Column: ArrayType(Long)

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{'grid_cellid': 613177664827555839}])
    df.select(grid_cellkring('grid_cellid', lit(2)).alias("kring")).show()
    +-------------------------------------------------------------------+
    |         grid_cellid|                                         kring|
    +--------------------+----------------------------------------------+
    |  613177664827555839|[613177664827555839, 613177664825458687, ....]|
    +--------------------+----------------------------------------------+

   .. code-tab:: scala

    val df = List((613177664827555839)).toDF("grid_cellid")
    df.select(grid_cellkring('grid_cellid', lit(2)).alias("kring")).show()
    +-------------------------------------------------------------------+
    |         grid_cellid|                                         kring|
    +--------------------+----------------------------------------------+
    |  613177664827555839|[613177664827555839, 613177664825458687, ....]|
    +--------------------+----------------------------------------------+

   .. code-tab:: sql

    SELECT grid_cellkring(613177664827555839, 2)
    +-------------------------------------------------------------------+
    |         grid_cellid|                                         kring|
    +--------------------+----------------------------------------------+
    |  613177664827555839|[613177664827555839, 613177664825458687, ....]|
    +--------------------+----------------------------------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(grid_cellid = 613177664827555839))
    showDF(select(df, grid_cellkring(column("grid_cellid"), lit(2L))))
    +-------------------------------------------------------------------+
    |         grid_cellid|                                         kring|
    +--------------------+----------------------------------------------+
    |  613177664827555839|[613177664827555839, 613177664825458687, ....]|
    +--------------------+----------------------------------------------+


.. raw:: html

   <div class="figure-group">


.. figure:: ../images/grid_cellkring/h3.png
   :figclass: doc-figure-float-left

   Fig 1. Cell based kring(2) in H3(8)


.. figure:: ../images/grid_cellkring/bng.png
   :figclass: doc-figure-float-left

   Fig 2. Cell based kring(2) in BNG(4)


.. raw:: html

   </div>


grid_cellkringexplode
*********************

.. function:: grid_cellkringexplode(cellid, k)

    Returns the k-ring of a given cell exploded.

    :param cellid: Grid cell ID
    :type cellid: Column: Long
    :param k: K-ring size
    :type k: Column: Integer
    :rtype: Column: Long

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{'grid_cellid': 613177664827555839}])
    df.select(grid_cellkringexplode('grid_cellid', lit(2)).alias("kring")).show()
    +------------------+
    |             kring|
    +------------------+
    |613177664827555839|
    |613177664825458687|
    |613177664831750143|
    |613177664884178943|
    |               ...|
    +------------------+


   .. code-tab:: scala

    val df = List((613177664827555839)).toDF("grid_cellid")
    df.select(grid_cellkringexplode('grid_cellid', lit(2)).alias("kring")).show()
    +------------------+
    |             kring|
    +------------------+
    |613177664827555839|
    |613177664825458687|
    |613177664831750143|
    |613177664884178943|
    |               ...|
    +------------------+

   .. code-tab:: sql

    SELECT grid_cellkringexplode(613177664827555839, 2)
    +------------------+
    |             kring|
    +------------------+
    |613177664827555839|
    |613177664825458687|
    |613177664831750143|
    |613177664884178943|
    |               ...|
    +------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(grid_cellid = 613177664827555839))
    showDF(select(df, grid_cellkringexplode(column("grid_cellid"), lit(2L))))
    +------------------+
    |             kring|
    +------------------+
    |613177664827555839|
    |613177664825458687|
    |613177664831750143|
    |613177664884178943|
    |               ...|
    +------------------+


.. raw:: html

   <div class="figure-group">


.. figure:: ../images/grid_cellkring/h3.png
   :figclass: doc-figure-float-left

   Fig 1. Cell based kring(2) in H3(8)


.. figure:: ../images/grid_cellkring/bng.png
   :figclass: doc-figure-float-left

   Fig 2. Cell based kring(2) in BNG(4)


.. raw:: html

   </div>

grid_cell_intersection
**************

.. function:: grid_cell_intersection(left_chip, right_chip)

    Returns the chip representing the intersection of two chips based on the same grid cell.
    Also, see :ref:`grid_cell_intersection_agg` function.

    :param left_chip: Chip
    :type left_chip: Column: ChipType(LongType)
    :param left_chip: Chip
    :type left_chip: Column: ChipType(LongType)
    :rtype: Column: ChipType(LongType)

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{"chip": {"is_core": False, "index_id": 590418571381702655, "wkb": ...}})])
    df.select(grid_cell_intersection("chip", "chip").alias("intersection")).show()
    ---------------------------------------------------------+
    |                                           intersection |
    +--------------------------------------------------------+
    |{is_core: false, index_id: 590418571381702655, wkb: ...}|
    +--------------------------------------------------------+

   .. code-tab:: scala

    val df = List((...)).toDF("chip")
    df.select(grid_cell_intersection("chip", "chip").alias("intersection")).show()
    ---------------------------------------------------------+
    |                                           intersection |
    +--------------------------------------------------------+
    |{is_core: false, index_id: 590418571381702655, wkb: ...}|
    +--------------------------------------------------------+

   .. code-tab:: sql

    SELECT grid_cell_intersection({"is_core": False, "index_id": 590418571381702655, "wkb": ...})
    ---------------------------------------------------------+
    |                                           intersection |
    +--------------------------------------------------------+
    |{is_core: false, index_id: 590418571381702655, wkb: ...}|
    +--------------------------------------------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(...))
    showDF(select(df, grid_cell_intersection(column("chip"))))
    ---------------------------------------------------------+
    |                                           intersection |
    +--------------------------------------------------------+
    |{is_core: false, index_id: 590418571381702655, wkb: ...}|
    +--------------------------------------------------------+

grid_cell_union
**************

.. function:: grid_cell_union(left_chip, right_chip)

    Returns the chip representing the union of two chips based on the same grid cell.
    Also, see :ref:`grid_cell_union_agg` function.

    :param left_chip: Chip
    :type left_chip: Column: ChipType(LongType)
    :param left_chip: Chip
    :type left_chip: Column: ChipType(LongType)
    :rtype: Column: ChipType(LongType)

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{"chip": {"is_core": False, "index_id": 590418571381702655, "wkb": ...}})])
    df.select(grid_cell_union("chip", "chip").alias("union")).show()
    ---------------------------------------------------------+
    |                                           union        |
    +--------------------------------------------------------+
    |{is_core: false, index_id: 590418571381702655, wkb: ...}|
    +--------------------------------------------------------+

   .. code-tab:: scala

    val df = List((...)).toDF("chip")
    df.select(grid_cell_union("chip", "chip").alias("union")).show()
    ---------------------------------------------------------+
    |                                           union        |
    +--------------------------------------------------------+
    |{is_core: false, index_id: 590418571381702655, wkb: ...}|
    +--------------------------------------------------------+

   .. code-tab:: sql

    SELECT grid_cell_union({"is_core": False, "index_id": 590418571381702655, "wkb": ...})
    ---------------------------------------------------------+
    |                                           union        |
    +--------------------------------------------------------+
    |{is_core: false, index_id: 590418571381702655, wkb: ...}|
    +--------------------------------------------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(...))
    showDF(select(df, grid_cell_union(column("chip"))))
    ---------------------------------------------------------+
    |                                           union        |
    +--------------------------------------------------------+
    |{is_core: false, index_id: 590418571381702655, wkb: ...}|
    +--------------------------------------------------------+


grid_cellkloop
**************

.. function:: grid_cellkloop(cellid, k)

    Returns the k loop (hollow ring) of a given cell.

    :param cellid: Grid cell ID
    :type cellid: Column: Long
    :param k: K-loop size
    :type k: Column: Integer
    :rtype: Column: ArrayType(Long)

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{'grid_cellid': 613177664827555839}])
    df.select(grid_cellkloop('grid_cellid', lit(2)).alias("kloop")).show()
    +-------------------------------------------------------------------+
    |         grid_cellid|                                         kloop|
    +--------------------+----------------------------------------------+
    |  613177664827555839|[613177664827555839, 613177664825458687, ....]|
    +--------------------+----------------------------------------------+

   .. code-tab:: scala

    val df = List((613177664827555839)).toDF("grid_cellid")
    df.select(grid_cellkloop('grid_cellid', lit(2)).alias("kloop")).show()
    +-------------------------------------------------------------------+
    |         grid_cellid|                                         kloop|
    +--------------------+----------------------------------------------+
    |  613177664827555839|[613177664827555839, 613177664825458687, ....]|
    +--------------------+----------------------------------------------+

   .. code-tab:: sql

    SELECT grid_cellkloop(613177664827555839, 2)
    +-------------------------------------------------------------------+
    |         grid_cellid|                                         kloop|
    +--------------------+----------------------------------------------+
    |  613177664827555839|[613177664827555839, 613177664825458687, ....]|
    +--------------------+----------------------------------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(grid_cellid = 613177664827555839))
    showDF(select(df, grid_cellkloop(column("grid_cellid"), lit(2L))))
    +-------------------------------------------------------------------+
    |         grid_cellid|                                         kloop|
    +--------------------+----------------------------------------------+
    |  613177664827555839|[613177664827555839, 613177664825458687, ....]|
    +--------------------+----------------------------------------------+


.. raw:: html

   <div class="figure-group">


.. figure:: ../images/grid_cellkloop/h3.png
   :figclass: doc-figure-float-left

   Fig 1. Cell based kring(2) in H3(8)


.. figure:: ../images/grid_cellkloop/bng.png
   :figclass: doc-figure-float-left

   Fig 2. Cell based kring(2) in BNG(4)


.. raw:: html

   </div>


grid_cellkloopexplode
*********************

.. function:: grid_cellkloopexplode(cellid, k)

    Returns the k loop (hollow ring) of a given cell exploded.

    :param cellid: Grid cell ID
    :type cellid: Column: Long
    :param k: K-loop size
    :type k: Column: Integer
    :rtype: Column: Long

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{'grid_cellid': 613177664827555839}])
    df.select(grid_cellkloopexplode('grid_cellid', lit(2)).alias("kloop")).show()
    +------------------+
    |             kloop|
    +------------------+
    |613177664827555839|
    |613177664825458687|
    |613177664831750143|
    |613177664884178943|
    |               ...|
    +------------------+


   .. code-tab:: scala

    val df = List((613177664827555839)).toDF("grid_cellid")
    df.select(grid_cellkloopexplode('grid_cellid', lit(2)).alias("kloop")).show()
    +------------------+
    |             kloop|
    +------------------+
    |613177664827555839|
    |613177664825458687|
    |613177664831750143|
    |613177664884178943|
    |               ...|
    +------------------+

   .. code-tab:: sql

    SELECT grid_cellkloopexplode(613177664827555839, 2)
    +------------------+
    |             kloop|
    +------------------+
    |613177664827555839|
    |613177664825458687|
    |613177664831750143|
    |613177664884178943|
    |               ...|
    +------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(grid_cellid = 613177664827555839))
    showDF(select(df, grid_cellkloopexplode(column("grid_cellid"), lit(2L))))
    +------------------+
    |             kloop|
    +------------------+
    |613177664827555839|
    |613177664825458687|
    |613177664831750143|
    |613177664884178943|
    |               ...|
    +------------------+


.. raw:: html

   <div class="figure-group">


.. figure:: ../images/grid_cellkloop/h3.png
   :figclass: doc-figure-float-left

   Fig 1. Cell based kring(2) in H3(8)


.. figure:: ../images/grid_cellkloop/bng.png
   :figclass: doc-figure-float-left

   Fig 2. Cell based kring(2) in BNG(4)


.. raw:: html

   </div>



grid_geometrykring
******************

.. function:: grid_geometrykring(geometry, resolution, k)

    Returns the k-ring of a given geometry respecting the boundary shape.

    :param geometry: Geometry to be used
    :type geometry: Column
    :param resolution: Resolution of the index used to calculate the k-ring
    :type resolution: Column: Integer
    :param k: K-ring size
    :type k: Column: Integer
    :rtype: Column: ArrayType(Long)

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{'geometry': "MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))"}])
    df.select(grid_geometrykring('geometry', lit(8), lit(1)).alias("kring")).show()
    +-------------------------------------------------------------------+
    |            geometry|                                         kring|
    +--------------------+----------------------------------------------+
    |  "MULTIPOLYGON(..."|[613177664827555839, 613177664825458687, ....]|
    +--------------------+----------------------------------------------+

   .. code-tab:: scala

    val df = List((613177664827555839)).toDF("geometry")
    df.select(grid_geometrykring('geometry', lit(8), lit(1)).alias("kring")).show()
    +-------------------------------------------------------------------+
    |            geometry|                                         kring|
    +--------------------+----------------------------------------------+
    |  "MULTIPOLYGON(..."|[613177664827555839, 613177664825458687, ....]|
    +--------------------+----------------------------------------------+

   .. code-tab:: sql

    SELECT grid_geometrykring('MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))', 8, 1)
    +-------------------------------------------------------------------+
    |            geometry|                                         kring|
    +--------------------+----------------------------------------------+
    |  "MULTIPOLYGON(..."|[613177664827555839, 613177664825458687, ....]|
    +--------------------+----------------------------------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(geometry = 613177664827555839))
    showDF(select(df, grid_geometrykring('geometry', lit(8L), lit(1L))))
    +-------------------------------------------------------------------+
    |            geometry|                                         kring|
    +--------------------+----------------------------------------------+
    |  "MULTIPOLYGON(..."|[613177664827555839, 613177664825458687, ....]|
    +--------------------+----------------------------------------------+


.. raw:: html

   <div class="figure-group">


.. figure:: ../images/grid_geometrykring/h3.png
   :figclass: doc-figure-float-left

   Fig 1. Geometry based kring(1) in H3(8)


.. figure:: ../images/grid_geometrykring/bng.png
   :figclass: doc-figure-float-left

   Fig 2. Geometry based kring(1) in BNG(4)


.. raw:: html

   </div>


grid_geometrykringexplode
*************************

.. function:: grid_geometrykringexplode(geometry, resolution, k)

    Returns the k-ring of a given geometry exploded.

    :param geometry: Geometry to be used
    :type geometry: Column
    :param resolution: Resolution of the index used to calculate the k-ring
    :type resolution: Column: Integer
    :param k: K-ring size
    :type k: Column: Integer
    :rtype: Column: Long

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{'geometry': "MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))"}])
    df.select(grid_geometrykringexplode('geometry', lit(8), lit(2)).alias("kring")).show()
    +------------------+
    |             kring|
    +------------------+
    |613177664827555839|
    |613177664825458687|
    |613177664831750143|
    |613177664884178943|
    |               ...|
    +------------------+


   .. code-tab:: scala

    val df = List(("MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))")).toDF("geometry")
    df.select(grid_geometrykringexplode('geometry', lit(8), lit(2)).alias("kring")).show()
    +------------------+
    |             kring|
    +------------------+
    |613177664827555839|
    |613177664825458687|
    |613177664831750143|
    |613177664884178943|
    |               ...|
    +------------------+

   .. code-tab:: sql

    SELECT grid_geometrykringexplode("MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))", 8, 2)
    +------------------+
    |             kring|
    +------------------+
    |613177664827555839|
    |613177664825458687|
    |613177664831750143|
    |613177664884178943|
    |               ...|
    +------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(geometry = "MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))"))
    showDF(select(df, grid_cellkringexplode(column("geometry"), lit(8L), lit(2L))))
    +------------------+
    |             kring|
    +------------------+
    |613177664827555839|
    |613177664825458687|
    |613177664831750143|
    |613177664884178943|
    |               ...|
    +------------------+


.. raw:: html

   <div class="figure-group">


.. figure:: ../images/grid_geometrykring/h3.png
   :figclass: doc-figure-float-left

   Fig 1. Cell based kring(2) in H3(8)


.. figure:: ../images/grid_geometrykring/bng.png
   :figclass: doc-figure-float-left

   Fig 2. Cell based kring(2) in BNG(4)


.. raw:: html

   </div>


grid_geometrykloop
******************

.. function:: grid_geometrykloop(geometry, resolution, k)

    Returns the k-loop (hollow ring) of a given geometry.

    :param geometry: Geometry to be used
    :type geometry: Column
    :param resolution: Resolution of the index used to calculate the k loop
    :type resolution: Column: Integer
    :param k: K-Loop size
    :type k: Column: Integer
    :rtype: Column: ArrayType(Long)

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{'geometry': "MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))"}])
    df.select(grid_geometrykloop('geometry', lit(2)).alias("kloop")).show()
    +-------------------------------------------------------------------+
    |            geometry|                                         kloop|
    +--------------------+----------------------------------------------+
    |  MULTIPOLYGON ((...|[613177664827555839, 613177664825458687, ....]|
    +--------------------+----------------------------------------------+

   .. code-tab:: scala

    val df = List(("MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))")).toDF("geometry")
    df.select(grid_cellkloop('geometry', lit(2)).alias("kloop")).show()
    +-------------------------------------------------------------------+
    |            geometry|                                         kloop|
    +--------------------+----------------------------------------------+
    |  MULTIPOLYGON ((...|[613177664827555839, 613177664825458687, ....]|
    +--------------------+----------------------------------------------+

   .. code-tab:: sql

    SELECT grid_cellkloop("MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))", 2)
    +-------------------------------------------------------------------+
    |            geometry|                                         kloop|
    +--------------------+----------------------------------------------+
    |  MULTIPOLYGON ((...|[613177664827555839, 613177664825458687, ....]|
    +--------------------+----------------------------------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(geometry = "MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))"))
    showDF(select(df, grid_cellkloop(column("geometry"), lit(2L))))
    +-------------------------------------------------------------------+
    |            geometry|                                         kloop|
    +--------------------+----------------------------------------------+
    |  MULTIPOLYGON ((...|[613177664827555839, 613177664825458687, ....]|
    +--------------------+----------------------------------------------+


.. raw:: html

   <div class="figure-group">


.. figure:: ../images/grid_geometrykloop/h3.png
   :figclass: doc-figure-float-left

   Fig 1. Cell based kring(2) in H3(8)


.. figure:: ../images/grid_geometrykloop/bng.png
   :figclass: doc-figure-float-left

   Fig 2. Cell based kring(2) in BNG(4)


.. raw:: html

   </div>


grid_geometrykloopexplode
*************************

.. function:: grid_geometrykloopexplode(geometry, resolution, k)

    Returns the k loop (hollow ring) of a given geometry exploded.

    :param geometry: Geometry to be used
    :type geometry: Column
    :param resolution: Resolution of the index used to calculate the k loop
    :type resolution: Column: Integer
    :param k: K-loop size
    :type k: Column: Integer
    :rtype: Column: Long

    :example:

.. tabs::
   .. code-tab:: py

    df = spark.createDataFrame([{'geometry': "MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))"}])
    df.select(grid_geometrykloopexplode('geometry', lit(8), lit(2)).alias("kloop")).show()
    +------------------+
    |             kloop|
    +------------------+
    |613177664827555839|
    |613177664825458687|
    |613177664831750143|
    |613177664884178943|
    |               ...|
    +------------------+


   .. code-tab:: scala

    val df = List(("MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))")).toDF("geometry")
    df.select(grid_geometrykloopexplode('geometry', lit(8), lit(2)).alias("kloop")).show()
    +------------------+
    |             kloop|
    +------------------+
    |613177664827555839|
    |613177664825458687|
    |613177664831750143|
    |613177664884178943|
    |               ...|
    +------------------+

   .. code-tab:: sql

    SELECT grid_geometrykloopexplode("MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))", 8, 2)
    +------------------+
    |             kloop|
    +------------------+
    |613177664827555839|
    |613177664825458687|
    |613177664831750143|
    |613177664884178943|
    |               ...|
    +------------------+

   .. code-tab:: r R

    df <- createDataFrame(data.frame(geometry = "MULTIPOLYGON (((30 20, 45 40, 10 40, 30 20)), ((15 5, 40 10, 10 20, 5 10, 15 5)))"))
    showDF(select(df, grid_geometrykloopexplode(column("geometry"), lit(8L), lit(2L))))
    +------------------+
    |             kloop|
    +------------------+
    |613177664827555839|
    |613177664825458687|
    |613177664831750143|
    |613177664884178943|
    |               ...|
    +------------------+


.. raw:: html

   <div class="figure-group">


.. figure:: ../images/grid_geometrykloop/h3.png
   :figclass: doc-figure-float-left

   Fig 1. Cell based kring(2) in H3(8)


.. figure:: ../images/grid_geometrykloop/bng.png
   :figclass: doc-figure-float-left

   Fig 2. Cell based kring(2) in BNG(4)


.. raw:: html

   </div>