0
Fork 0
mirror of https://github.com/uber/h3-py.git synced 2026-11-16 07:44:46 +00:00
h3-py/docs/api_quick.md
AJ Friend f9c1a944d1
Bump h3lib to v4.4.1 and add new functions/errors (#470)
* bump h3lib to v4.4.0

* bump h3lib to v4.4.1

* tests pass with new version

* add new error codes and some helper functions around error codes

* jupyter-book<2

* is_valid_index

* tests for is_valid_index and get_index_digit

* linting

* good set of tests

* lint

* thank you, coverage tests for tests!

* int api test

* function docstrings

* maybe not

* changelog. don't expose error code helper functions (yet)

* ticks

* don't even mention 'em

* `list` rather than `tuple`, since users are likely to mutate result

* remove justfile

* failing tests

* tests should be passing

* more tests

* swap docs order
2025-11-22 08:17:21 -08:00

3.8 KiB

API Quick Reference

Function names changed significantly with `h3-py` `v4.0` to align with the C library: https://h3geo.org/docs/library/migration-3.x/functions

We list the functions that are shared between the provided APIs. The APIs differ only in their input/output types (e.g., int vs. str or list vs numpy.array).

These functions correspond to those explained in the H3 C library documentation, and should be generally aligned with the other language bindings.

Identification

.. currentmodule:: h3

.. autosummary::
   is_valid_cell
   is_pentagon
   is_res_class_III
   is_valid_directed_edge
   is_valid_vertex
   is_valid_index

Index representation

.. currentmodule:: h3

.. autosummary::
   int_to_str
   str_to_int

Cell properties

.. currentmodule:: h3

.. autosummary::
   get_res0_cells
   get_pentagons
   get_num_cells
   get_resolution
   get_base_cell_number
   get_index_digit
   construct_cell
   deconstruct_cell

Geographic coordinates

Functions relating H3 objects to geographic (lat/lng) coordinates.

.. currentmodule:: h3

.. autosummary::
   latlng_to_cell
   cell_to_latlng
   cell_area
   edge_length
   cell_to_boundary
   directed_edge_to_boundary
   great_circle_distance
   average_hexagon_area
   average_hexagon_edge_length

Hierarchical relationships

.. currentmodule:: h3

.. autosummary::
   cell_to_parent
   cell_to_children
   cell_to_center_child
   cell_to_children_size
   cell_to_child_pos
   child_pos_to_cell
   compact_cells
   uncompact_cells

Cell grid relationships

.. currentmodule:: h3

.. autosummary::
   grid_ring
   grid_disk
   grid_distance
   are_neighbor_cells
   grid_path_cells

Edges

.. currentmodule:: h3

.. autosummary::
   cells_to_directed_edge
   directed_edge_to_cells
   get_directed_edge_origin
   get_directed_edge_destination
   origin_to_directed_edges

Vertexes

.. currentmodule:: h3

.. autosummary::
   cell_to_vertex
   cell_to_vertexes
   vertex_to_latlng

Polygon interface

The LatLngPoly and LatLngMultiPoly objects and their related functions allow users to represent (multi)polygons of lat/lng points and convert back and forth between H3 cells.

The objects and functions also compatible with the popular __geo_interface__ protocol, which is used by Python geospatial libraries like GeoPandas and many plotting libraries.

See the polygon tutorial for a walkthrough.

As with other `h3-py` functions, the polygon interface expects coordinate pairs in **lat/lng** order.
Note that this is reversed from [``__geo_interface__``](https://gist.github.com/sgillies/2217756) objects, which are given in **lng/lat** order.

Polygon objects

.. currentmodule:: h3

.. autosummary::
   H3Shape
   LatLngPoly
   LatLngMultiPoly

Conversion functions

.. currentmodule:: h3

.. autosummary::
   h3shape_to_geo
   geo_to_h3shape
   h3shape_to_cells
   cells_to_h3shape
   geo_to_cells
   cells_to_geo

Additional functions

.. currentmodule:: h3

.. autosummary::
   polygon_to_cells
   polygon_to_cells_experimental
   h3shape_to_cells_experimental

Specialized functions

h3-py library

.. currentmodule:: h3

.. autosummary::
   versions

IJ-indexing

.. currentmodule:: h3

.. autosummary::
   get_icosahedron_faces
   cell_to_local_ij
   local_ij_to_cell