leaf_engine.utils.h3
====================

.. py:module:: leaf_engine.utils.h3

.. autoapi-nested-parse::

   This module contains various pure functions for manipulating H3 indices.



Attributes
----------

.. autoapisummary::

   leaf_engine.utils.h3.H3_POLYFILL_BUFFER
   leaf_engine.utils.h3.H3_RESOLUTION


Functions
---------

.. autoapisummary::

   leaf_engine.utils.h3.geometry_to_h3_indices
   leaf_engine.utils.h3.get_contiguous_areas
   leaf_engine.utils.h3.get_k_ring
   leaf_engine.utils.h3.h3_index_to_geometry
   leaf_engine.utils.h3.h3_index_to_lat_lon
   leaf_engine.utils.h3.h3_indices_to_geometry
   leaf_engine.utils.h3.is_contiguous_area
   leaf_engine.utils.h3.lat_lon_to_geometry
   leaf_engine.utils.h3.lat_lon_to_h3_index
   leaf_engine.utils.h3.polygon_to_h3_indices


Module Contents
---------------

.. py:function:: geometry_to_h3_indices(geometry: Union[str, shapely.geometry.Polygon], resolution: int = H3_RESOLUTION) -> Iterable

.. py:function:: get_contiguous_areas(indices: set) -> list[set]

   Given a set of H3 indices, returns a list of H3 indices representing
   contiguous areas in the provided list of indices.

   :param indices: Set of H3 indices at arbitrary resolution. All indices must be at
   :type indices: set
   :param same resolution.:

   :returns: List of sets of H3 indices, each set representing a contiguous area in the
             input. Sets are sorted by number of indices (ascending).
   :rtype: list


.. py:function:: get_k_ring(index: str, k: int, exclude_k: int | None = None) -> set

   Returns the k-ring of a given H3 index (i.e., the k-"disk"). Optionally,
   allows the specification of an internal k-ring to exclude from the return
   set (which will return a k-"doughnut" instead of a k-"disk").

   :param index: H3 index of arbitrary resolution.
   :type index: str
   :param k: k-ring to return.
   :type k: int
   :param exclude_k: Internal k-ring to exclude. Defaults to None.
   :type exclude_k: int, optional

   :returns: H3 indices comprising the k-ring.
   :rtype: set


.. py:function:: h3_index_to_geometry(h3_index: str, as_string=False) -> Union[str, shapely.geometry.Polygon]

.. py:function:: h3_index_to_lat_lon(h3_index: str) -> Tuple[float, float]

.. py:function:: h3_indices_to_geometry(indices: Iterable, as_string: bool = False) -> Union[str, shapely.geometry.Polygon]

   Converts a set of H3 indices to shapely Polygon or WKT. Raises an exception
   if the conversion produces a MultiPolygon instead of contiguous Polygon.

   :param indices: Set of H3 indices.
   :type indices: Iterable
   :param as_string: Return WKT instead of Polygon object. Defaults to False.
   :type as_string: bool, optional

   :returns: Polygon or WKT.
   :rtype: Union[str, Polygon]


.. py:function:: is_contiguous_area(indices: set) -> bool

   Returns whether area defined by a set of H3 indices is contiguous.


.. py:function:: lat_lon_to_geometry(lat: float, lon: float) -> str

.. py:function:: lat_lon_to_h3_index(lat: float, lon: float, resolution=H3_RESOLUTION) -> str

.. py:function:: polygon_to_h3_indices(polygon: shapely.geometry.Polygon, resolution=H3_RESOLUTION)

.. py:data:: H3_POLYFILL_BUFFER

.. py:data:: H3_RESOLUTION
   :value: 5