From 298f17faae4d3466fd6fc3b6d64dad107181bb25 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 19 May 2022 19:48:25 -0400 Subject: [PATCH 001/177] WIP: Starting work on v4, The Sequel (#238) * cimport for h3fake2 doesn't seem to work * back to where we were * meh, close to what i was hoping for * h3fake2 in github actions * comment out current bindings that consume the h3c v3 library * don't need the coveragerc file at the moment; clear out c files in /tests * sdist needs h3fake2 * try CIBW_BEFORE_BUILD to get h3fake2 * need h3fake2 for cibuildwheel tests * update h3 C library * comment out most of h3lib.pxd * calling from v4 c lib works! (tests dont' work yet tho) * tests shall pass * starting to move over first few functions * little steps * util submodule fully moved over; some hackery with h3fake2 errors * getting even trickier with h3fake2 errors * few more simple functions * geo_to_h3 and h3_to_geo * grid_distance function * grid_disk * parents and kids * compact/uncompact * getNumCells * comment out sdist test temporarily * commenting out `make_sdist` seems to have turned off the other CI jobs * no, it was that we're pushing to the dev branch * keep the sdist job in there, but commented out --- .coveragerc | 3 - .github/workflows/coverage-lint.yml | 5 +- .github/workflows/tests.yml | 5 +- .github/workflows/wheels.yml | 53 ++-- makefile | 2 + src/h3/_cy/CMakeLists.txt | 1 - src/h3/_cy/__init__.py | 41 +++- src/h3/_cy/cells.pxd | 20 +- src/h3/_cy/cells.pyx | 356 +++++++++++++++------------ src/h3/_cy/edges.pxd | 20 +- src/h3/_cy/edges.pyx | 140 +++++------ src/h3/_cy/geo.pxd | 6 +- src/h3/_cy/geo.pyx | 365 ++++++++++++++-------------- src/h3/_cy/h3lib.pxd | 232 +++++++++--------- src/h3/_cy/to_multipoly.pyx | 104 ++++---- src/h3/_cy/unstable_vect.pyx | 89 ------- src/h3/_cy/util.pxd | 6 +- src/h3/_cy/util.pyx | 12 +- src/h3/_version.py | 37 +-- src/h3/unstable/__init__.py | 9 - src/h3/unstable/v4.py | 125 ---------- src/h3/unstable/vect.py | 105 -------- src/h3lib | 2 +- tests/cython_example.pyx | 28 +-- tests/h3fake2_errors.py | 15 ++ tests/test_cells_and_edges.py | 2 +- tests/test_cython.py | 40 +-- tests/test_length_area.py | 2 +- tests/test_polyfill.py | 6 +- tests/test_unstable_vect.py | 69 ------ 30 files changed, 804 insertions(+), 1096 deletions(-) delete mode 100644 .coveragerc delete mode 100644 src/h3/_cy/unstable_vect.pyx delete mode 100644 src/h3/unstable/__init__.py delete mode 100644 src/h3/unstable/v4.py delete mode 100644 src/h3/unstable/vect.py create mode 100644 tests/h3fake2_errors.py delete mode 100644 tests/test_unstable_vect.py diff --git a/.coveragerc b/.coveragerc deleted file mode 100644 index fbf9e0e..0000000 --- a/.coveragerc +++ /dev/null @@ -1,3 +0,0 @@ -[run] -omit = - */h3/unstable/* diff --git a/.github/workflows/coverage-lint.yml b/.github/workflows/coverage-lint.yml index e1d0bbd..5110236 100644 --- a/.github/workflows/coverage-lint.yml +++ b/.github/workflows/coverage-lint.yml @@ -2,9 +2,9 @@ name: coverage-lint on: push: - branches: [master] + branches: [master, dev_v4] pull_request: - branches: [master] + branches: [master, dev_v4] jobs: tests: @@ -23,6 +23,7 @@ jobs: - name: Install from source run: | pip install --upgrade pip setuptools wheel + pip install git+https://github.com/ajfriend/h3fake2.git pip install .[all] - name: Lint diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index f2c5682..0b9883d 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -2,9 +2,9 @@ name: tests on: push: - branches: [master] + branches: [master, dev_v4] pull_request: - branches: [master] + branches: [master, dev_v4] jobs: tests: @@ -44,6 +44,7 @@ jobs: - name: Install from source run: | pip install --upgrade pip setuptools wheel + pip install git+https://github.com/ajfriend/h3fake2.git pip install .[all] - name: Tests diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 5f75525..71f47d5 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -2,9 +2,9 @@ name: wheels on: push: - branches: [master] + branches: [master, dev_v4] pull_request: - branches: [master] + branches: [master, dev_v4] types: # Opened, synchronize, and reopened are the default types # We add ready_for_review to additionally trigger when converting from draft to non-draft @@ -18,33 +18,34 @@ on: - published jobs: - make_sdist: - name: SDist - if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }} - runs-on: ubuntu-latest + # make_sdist: + # name: SDist + # if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }} + # runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - with: - submodules: recursive + # steps: + # - uses: actions/checkout@v3 + # with: + # submodules: recursive - - name: Make sdist - run: | - pipx run build --sdist + # - name: Make sdist + # run: | + # pipx run build --sdist - - name: Install from sdist - run: | - pip install --upgrade pip setuptools wheel - cp dist/h3-*.tar.gz h3.tar.gz - pip install h3.tar.gz[all] + # - name: Install from sdist + # run: | + # pip install --upgrade pip setuptools wheel + # pip install git+https://github.com/ajfriend/h3fake2.git + # cp dist/h3-*.tar.gz h3.tar.gz + # pip install h3.tar.gz[all] - - name: Test sdist - run: pytest --cov=h3 --full-trace + # - name: Test sdist + # run: pytest --cov=h3 --full-trace - - name: Upload artifacts to GitHub - uses: actions/upload-artifact@v3 - with: - path: ./dist + # - name: Upload artifacts to GitHub + # uses: actions/upload-artifact@v3 + # with: + # path: ./dist make_cibw_v1_wheels: name: "cibuildwheel v1: ${{ matrix.name }}" @@ -74,6 +75,8 @@ jobs: CIBW_TEST_COMMAND: pytest {project}/tests CIBW_ARCHS_LINUX: auto aarch64 CIBW_BUILD: ${{ matrix.build }} + CIBW_BEFORE_BUILD: pip install git+https://github.com/ajfriend/h3fake2.git + CIBW_BEFORE_TEST: pip install git+https://github.com/ajfriend/h3fake2.git - name: Check with Twine run: | @@ -152,6 +155,8 @@ jobs: CIBW_ARCHS_MACOS: x86_64 arm64 CIBW_BUILD: ${{ matrix.build }} CIBW_SKIP: ${{ matrix.skip }} + CIBW_BEFORE_BUILD: pip install git+https://github.com/ajfriend/h3fake2.git + CIBW_BEFORE_TEST: pip install git+https://github.com/ajfriend/h3fake2.git - name: Check with Twine run: | diff --git a/makefile b/makefile index 6e44c02..7c2845e 100644 --- a/makefile +++ b/makefile @@ -12,6 +12,7 @@ init: purge git submodule update --init python -m venv env env/bin/pip install --upgrade pip wheel setuptools + env/bin/pip install git+https://github.com/ajfriend/h3fake2.git env/bin/pip install .[all] env/bin/pip install -r requirements.in @@ -23,6 +24,7 @@ clear: -@find . -type d -name '*.egg-info' | xargs rm -r -@find . -type f -name '*.pyc' | xargs rm -r -@find . -type d -name '*.ipynb_checkpoints' | xargs rm -r + -@find ./tests -type f -name '*.c' | xargs rm -r rebuild: clear env/bin/pip install .[all] diff --git a/src/h3/_cy/CMakeLists.txt b/src/h3/_cy/CMakeLists.txt index 0d7e78c..386557c 100644 --- a/src/h3/_cy/CMakeLists.txt +++ b/src/h3/_cy/CMakeLists.txt @@ -22,7 +22,6 @@ add_cython_file(geo) add_cython_file(cells) add_cython_file(edges) add_cython_file(to_multipoly) -add_cython_file(unstable_vect) # Include pyx and pxd files in distribution for use by Cython API install( diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index bb4dfc0..6b17b2d 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -18,27 +18,44 @@ from .cells import ( is_pentagon, get_base_cell, resolution, - parent, + is_res_class_iii, distance, disk, - ring, + parent, children, + center_child, compact, uncompact, num_hexagons, +) + +from h3fake2._cy import ( + # is_cell, + # is_pentagon, + # get_base_cell, + # resolution, + # parent, + # distance, + # disk, + ring, + # children, + # compact, + # uncompact, + # num_hexagons, mean_hex_area, cell_area, line, - is_res_class_iii, + # is_res_class_iii, get_pentagon_indexes, get_res0_indexes, - center_child, + # center_child, get_faces, experimental_h3_to_local_ij, experimental_local_ij_to_h3, ) -from .edges import ( +# from .edges import ( +from h3fake2._cy import ( are_neighbors, edge, is_edge, @@ -53,6 +70,17 @@ from .edges import ( from .geo import ( geo_to_h3, h3_to_geo, + # polyfill_polygon, + # polyfill_geojson, + # polyfill, + # cell_boundary, + # edge_boundary, + # point_dist, +) + +from h3fake2._cy import ( + # geo_to_h3, + # h3_to_geo, polyfill_polygon, polyfill_geojson, polyfill, @@ -61,7 +89,8 @@ from .geo import ( point_dist, ) -from .to_multipoly import ( +# from .to_multipoly import ( +from h3fake2._cy import ( h3_set_to_multi_polygon ) diff --git a/src/h3/_cy/cells.pxd b/src/h3/_cy/cells.pxd index 1071938..4e2d441 100644 --- a/src/h3/_cy/cells.pxd +++ b/src/h3/_cy/cells.pxd @@ -6,20 +6,20 @@ cpdef int get_base_cell(H3int h) except -1 cpdef int resolution(H3int h) except -1 cpdef int distance(H3int h1, H3int h2) except -1 cpdef H3int[:] disk(H3int h, int k) -cpdef H3int[:] _ring_fallback(H3int h, int k) -cpdef H3int[:] ring(H3int h, int k) +# cpdef H3int[:] _ring_fallback(H3int h, int k) +# cpdef H3int[:] ring(H3int h, int k) cpdef H3int parent(H3int h, res=*) except 0 cpdef H3int[:] children(H3int h, res=*) cpdef H3int center_child(H3int h, res=*) except 0 cpdef H3int[:] compact(const H3int[:] hu) cpdef H3int[:] uncompact(const H3int[:] hc, int res) cpdef int64_t num_hexagons(int resolution) except -1 -cpdef double mean_hex_area(int resolution, unit=*) except -1 -cpdef double cell_area(H3int h, unit=*) except -1 -cpdef H3int[:] line(H3int start, H3int end) +# cpdef double mean_hex_area(int resolution, unit=*) except -1 +# cpdef double cell_area(H3int h, unit=*) except -1 +# cpdef H3int[:] line(H3int start, H3int end) cpdef bool is_res_class_iii(H3int h) -cpdef H3int[:] get_pentagon_indexes(int res) -cpdef H3int[:] get_res0_indexes() -cpdef get_faces(H3int h) -cpdef (int, int) experimental_h3_to_local_ij(H3int origin, H3int h) except * -cpdef H3int experimental_local_ij_to_h3(H3int origin, int i, int j) except 0 +# cpdef H3int[:] get_pentagon_indexes(int res) +# cpdef H3int[:] get_res0_indexes() +# cpdef get_faces(H3int h) +# cpdef (int, int) experimental_h3_to_local_ij(H3int origin, H3int h) except * +# cpdef H3int experimental_local_ij_to_h3(H3int origin, int i, int j) except 0 diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 4206b81..265e4c3 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -24,15 +24,17 @@ cpdef bool is_cell(H3int h): ------- boolean """ - return h3lib.h3IsValid(h) == 1 + return h3lib.isValidCell(h) == 1 + cpdef bool is_pentagon(H3int h): - return h3lib.h3IsPentagon(h) == 1 + return h3lib.isPentagon(h) == 1 + cpdef int get_base_cell(H3int h) except -1: check_cell(h) - return h3lib.h3GetBaseCell(h) + return h3lib.getBaseCellNumber(h) cpdef int resolution(H3int h) except -1: @@ -41,96 +43,109 @@ cpdef int resolution(H3int h) except -1: """ check_cell(h) - return h3lib.h3GetResolution(h) + return h3lib.getResolution(h) cpdef int distance(H3int h1, H3int h2) except -1: - """ compute the hex-distance between two hexagons + """ Compute the grid distance between two cells """ + cdef: + int64_t distance + h3lib.H3Error err + check_cell(h1) check_cell(h2) - d = h3lib.h3Distance(h1,h2) - - if d < 0: + err = h3lib.gridDistance(h1, h2, &distance) + if err: + # todo: do error handling later s = 'Cells are too far apart to compute distance: {} and {}' s = s.format(hex(h1), hex(h2)) raise H3ValueError(s) - return d + return distance cpdef H3int[:] disk(H3int h, int k): """ Return cells at grid distance `<= k` from `h`. """ + cdef: + int64_t n + h3lib.H3Error err + check_cell(h) check_distance(k) - n = h3lib.maxKringSize(k) + # ignoring error for now + err = h3lib.maxGridDiskSize(k, &n) ptr = create_ptr(n) # todo: return a "smart" pointer that knows its length? - h3lib.kRing(h, k, ptr) + err = h3lib.gridDisk(h, k, ptr) # ignoring error again! mv = create_mv(ptr, n) return mv -cpdef H3int[:] _ring_fallback(H3int h, int k): - """ - `ring` tries to call `h3lib.hexRing` first; if that fails, we call - this function, which relies on `h3lib.kRingDistances`. +# cpdef H3int[:] _ring_fallback(H3int h, int k): +# """ +# `ring` tries to call `h3lib.hexRing` first; if that fails, we call +# this function, which relies on `h3lib.kRingDistances`. - Failures for `h3lib.hexRing` happen when the algortihm runs into a pentagon. - """ - check_cell(h) - check_distance(k) +# Failures for `h3lib.hexRing` happen when the algortihm runs into a pentagon. +# """ +# check_cell(h) +# check_distance(k) - n = h3lib.maxKringSize(k) - # array of h3 cells - ptr = create_ptr(n) +# n = h3lib.maxKringSize(k) +# # array of h3 cells +# ptr = create_ptr(n) - # array of cell distances from `h` - dist_ptr = stdlib.calloc(n, sizeof(int)) - if dist_ptr is NULL: - raise MemoryError() +# # array of cell distances from `h` +# dist_ptr = stdlib.calloc(n, sizeof(int)) +# if dist_ptr is NULL: +# raise MemoryError() - h3lib.kRingDistances(h, k, ptr, dist_ptr) +# h3lib.kRingDistances(h, k, ptr, dist_ptr) - distances = dist_ptr - distances.callback_free_data = stdlib.free +# distances = dist_ptr +# distances.callback_free_data = stdlib.free - for i,v in enumerate(distances): - if v != k: - ptr[i] = 0 +# for i,v in enumerate(distances): +# if v != k: +# ptr[i] = 0 - mv = create_mv(ptr, n) +# mv = create_mv(ptr, n) - return mv +# return mv -cpdef H3int[:] ring(H3int h, int k): - """ Return cells at grid distance `== k` from `h`. - Collection is "hollow" for k >= 1. - """ - check_cell(h) - check_distance(k) +# cpdef H3int[:] ring(H3int h, int k): +# """ Return cells at grid distance `== k` from `h`. +# Collection is "hollow" for k >= 1. +# """ +# check_cell(h) +# check_distance(k) - n = 6*k if k > 0 else 1 - ptr = create_ptr(n) +# n = 6*k if k > 0 else 1 +# ptr = create_ptr(n) - flag = h3lib.hexRing(h, k, ptr) +# flag = h3lib.hexRing(h, k, ptr) - # if we drop into the failure state, we might be tempted to not create - # this mv, but creating the mv is exactly what guarantees that we'll free - # the memory. context manager would be better here, if we can figure out - # how to do that - mv = create_mv(ptr, n) +# # if we drop into the failure state, we might be tempted to not create +# # this mv, but creating the mv is exactly what guarantees that we'll free +# # the memory. context manager would be better here, if we can figure out +# # how to do that +# mv = create_mv(ptr, n) - if flag != 0: - mv = _ring_fallback(h, k) +# if flag != 0: +# mv = _ring_fallback(h, k) - return mv +# return mv cpdef H3int parent(H3int h, res=None) except 0: + cdef: + H3int parent + h3lib.H3Error err + check_cell(h) if res is None: @@ -141,10 +156,17 @@ cpdef H3int parent(H3int h, res=None) except 0: raise H3ResolutionError(msg) check_res(res) + err = h3lib.cellToParent(h, res, &parent) + + return parent - return h3lib.h3ToParent(h, res) cpdef H3int[:] children(H3int h, res=None): + cdef: + H3int child + h3lib.H3Error err + int64_t N + check_cell(h) if res is None: @@ -155,16 +177,20 @@ cpdef H3int[:] children(H3int h, res=None): raise H3ResolutionError(msg) check_res(res) + err = h3lib.cellToChildrenSize(h, res, &N) - n = h3lib.maxH3ToChildrenSize(h, res) - - ptr = create_ptr(n) - h3lib.h3ToChildren(h, res, ptr) - mv = create_mv(ptr, n) + ptr = create_ptr(N) + err = h3lib.cellToChildren(h, res, ptr) + mv = create_mv(ptr, N) return mv + cpdef H3int center_child(H3int h, res=None) except 0: + cdef: + H3int child + h3lib.H3Error err + check_cell(h) if res is None: @@ -175,8 +201,9 @@ cpdef H3int center_child(H3int h, res=None) except 0: raise H3ResolutionError(msg) check_res(res) + err = h3lib.cellToCenterChild(h, res, &child) - return h3lib.h3ToCenterChild(h, res) + return child @@ -186,6 +213,9 @@ cpdef H3int[:] compact(const H3int[:] hu): # `&hu[0]` **requires** a dereference. For Cython, checking for array # length of zero and returning early seems like the easiest solution. # note: open to better ideas! + cdef: + h3lib.H3Error err + if len(hu) == 0: return empty_memory_view() @@ -193,14 +223,16 @@ cpdef H3int[:] compact(const H3int[:] hu): check_cell(h) ptr = create_ptr(len(hu)) - flag = h3lib.compact(&hu[0], ptr, len(hu)) + err = h3lib.compactCells(&hu[0], ptr, len(hu)) mv = create_mv(ptr, len(hu)) - if flag != 0: + if err: + # todo: additional error processing raise H3ValueError('Could not compact set of hexagons!') return mv + # todo: https://stackoverflow.com/questions/50684977/cython-exception-type-for-a-function-returning-a-typed-memoryview # apparently, memoryviews are python objects, so we don't need to do the except clause cpdef H3int[:] uncompact(const H3int[:] hc, int res): @@ -209,23 +241,30 @@ cpdef H3int[:] uncompact(const H3int[:] hc, int res): # `&hc[0]` **requires** a dereference. For Cython, checking for array # length of zero and returning early seems like the easiest solution. # note: open to better ideas! + cdef: + h3lib.H3Error err + int64_t N + if len(hc) == 0: return empty_memory_view() for h in hc: check_cell(h) - N = h3lib.maxUncompactSize(&hc[0], len(hc), res) + # ignoring error for now + err = h3lib.uncompactCellsSize(&hc[0], len(hc), res, &N) ptr = create_ptr(N) - flag = h3lib.uncompact( - &hc[0], len(hc), - ptr, N, + err = h3lib.uncompactCells( + &hc[0], + len(hc), + ptr, + N, res ) mv = create_mv(ptr, N) - if flag != 0: + if err: raise H3ValueError('Could not uncompact set of hexagons!') return mv @@ -233,143 +272,148 @@ cpdef H3int[:] uncompact(const H3int[:] hc, int res): cpdef int64_t num_hexagons(int resolution) except -1: check_res(resolution) + cdef: + h3lib.H3Error err + int64_t num_cells - return h3lib.numHexagons(resolution) + err = h3lib.getNumCells(resolution, &num_cells) + + return num_cells -cpdef double mean_hex_area(int resolution, unit='km^2') except -1: - check_res(resolution) +# cpdef double mean_hex_area(int resolution, unit='km^2') except -1: +# check_res(resolution) - area = h3lib.hexAreaKm2(resolution) +# area = h3lib.hexAreaKm2(resolution) - # todo: multiple units - convert = { - 'km^2': 1.0, - 'm^2': 1000*1000.0 - } +# # todo: multiple units +# convert = { +# 'km^2': 1.0, +# 'm^2': 1000*1000.0 +# } - try: - area *= convert[unit] - except: - raise H3ValueError('Unknown unit: {}'.format(unit)) +# try: +# area *= convert[unit] +# except: +# raise H3ValueError('Unknown unit: {}'.format(unit)) - return area +# return area -cpdef double cell_area(H3int h, unit='km^2') except -1: - check_cell(h) +# cpdef double cell_area(H3int h, unit='km^2') except -1: +# check_cell(h) - if unit == 'rads^2': - area = h3lib.cellAreaRads2(h) - elif unit == 'km^2': - area = h3lib.cellAreaKm2(h) - elif unit == 'm^2': - area = h3lib.cellAreaM2(h) - else: - raise H3ValueError('Unknown unit: {}'.format(unit)) +# if unit == 'rads^2': +# area = h3lib.cellAreaRads2(h) +# elif unit == 'km^2': +# area = h3lib.cellAreaKm2(h) +# elif unit == 'm^2': +# area = h3lib.cellAreaM2(h) +# else: +# raise H3ValueError('Unknown unit: {}'.format(unit)) - return area +# return area -cpdef H3int[:] line(H3int start, H3int end): - check_cell(start) - check_cell(end) +# cpdef H3int[:] line(H3int start, H3int end): +# check_cell(start) +# check_cell(end) - n = h3lib.h3LineSize(start, end) +# n = h3lib.h3LineSize(start, end) - if n < 0: - s = "Couldn't find line between cells {} and {}" - s = s.format(hex(start), hex(end)) - raise H3ValueError(s) +# if n < 0: +# s = "Couldn't find line between cells {} and {}" +# s = s.format(hex(start), hex(end)) +# raise H3ValueError(s) - ptr = create_ptr(n) - flag = h3lib.h3Line(start, end, ptr) - mv = create_mv(ptr, n) +# ptr = create_ptr(n) +# flag = h3lib.h3Line(start, end, ptr) +# mv = create_mv(ptr, n) - if flag != 0: - s = "Couldn't find line between cells {} and {}" - s = s.format(hex(start), hex(end)) - raise H3ValueError(s) +# if flag != 0: +# s = "Couldn't find line between cells {} and {}" +# s = s.format(hex(start), hex(end)) +# raise H3ValueError(s) - return mv +# return mv cpdef bool is_res_class_iii(H3int h): - return h3lib.h3IsResClassIII(h) == 1 + return h3lib.isResClassIII(h) == 1 -cpdef H3int[:] get_pentagon_indexes(int res): - check_res(res) +# cpdef H3int[:] get_pentagon_indexes(int res): +# check_res(res) - n = h3lib.pentagonIndexCount() +# n = h3lib.pentagonIndexCount() - ptr = create_ptr(n) - h3lib.getPentagonIndexes(res, ptr) - mv = create_mv(ptr, n) +# ptr = create_ptr(n) +# h3lib.getPentagonIndexes(res, ptr) +# mv = create_mv(ptr, n) - return mv +# return mv -cpdef H3int[:] get_res0_indexes(): - n = h3lib.res0IndexCount() +# cpdef H3int[:] get_res0_indexes(): +# n = h3lib.res0IndexCount() - ptr = create_ptr(n) - h3lib.getRes0Indexes(ptr) - mv = create_mv(ptr, n) +# ptr = create_ptr(n) +# h3lib.getRes0Indexes(ptr) +# mv = create_mv(ptr, n) - return mv +# return mv -cpdef get_faces(H3int h): - check_cell(h) +# cpdef get_faces(H3int h): +# check_cell(h) - n = h3lib.maxFaceCount(h) +# n = h3lib.maxFaceCount(h) - cdef int* ptr = stdlib.calloc(n, sizeof(int)) - if (n > 0) and (not ptr): - raise MemoryError() +# cdef int* ptr = stdlib.calloc(n, sizeof(int)) +# if (n > 0) and (not ptr): +# raise MemoryError() - h3lib.h3GetFaces(h, ptr) +# h3lib.h3GetFaces(h, ptr) - faces = ptr - faces = {f for f in faces if f >= 0} - stdlib.free(ptr) +# faces = ptr +# faces = {f for f in faces if f >= 0} +# stdlib.free(ptr) - return faces +# return faces -cpdef (int, int) experimental_h3_to_local_ij(H3int origin, H3int h) except *: - cdef: - int flag - h3lib.CoordIJ c +# cpdef (int, int) experimental_h3_to_local_ij(H3int origin, H3int h) except *: +# cdef: +# int flag +# h3lib.CoordIJ c - check_cell(origin) - check_cell(h) +# check_cell(origin) +# check_cell(h) - flag = h3lib.experimentalH3ToLocalIj(origin, h, &c) +# flag = h3lib.experimentalH3ToLocalIj(origin, h, &c) - if flag != 0: - s = "Couldn't find local (i,j) between cells {} and {}." - s = s.format(hex(origin), hex(h)) - raise H3ValueError(s) +# if flag != 0: +# s = "Couldn't find local (i,j) between cells {} and {}." +# s = s.format(hex(origin), hex(h)) +# raise H3ValueError(s) - return c.i, c.j +# return c.i, c.j -cpdef H3int experimental_local_ij_to_h3(H3int origin, int i, int j) except 0: - cdef: - int flag - h3lib.CoordIJ c - H3int out +# cpdef H3int experimental_local_ij_to_h3(H3int origin, int i, int j) except 0: +# cdef: +# int flag +# h3lib.CoordIJ c +# H3int out - check_cell(origin) +# check_cell(origin) - c.i, c.j = i, j +# c.i, c.j = i, j - flag = h3lib.experimentalLocalIjToH3(origin, &c, &out) +# flag = h3lib.experimentalLocalIjToH3(origin, &c, &out) - if flag != 0: - s = "Couldn't find cell at local ({},{}) from cell {}." - s = s.format(i, j, hex(origin)) - raise H3ValueError(s) +# if flag != 0: +# s = "Couldn't find cell at local ({},{}) from cell {}." +# s = s.format(i, j, hex(origin)) +# raise H3ValueError(s) - return out +# return out diff --git a/src/h3/_cy/edges.pxd b/src/h3/_cy/edges.pxd index 465b82d..cdcf4d0 100644 --- a/src/h3/_cy/edges.pxd +++ b/src/h3/_cy/edges.pxd @@ -1,11 +1,11 @@ -from .h3lib cimport bool, H3int +# from .h3lib cimport bool, H3int -cpdef bool are_neighbors(H3int h1, H3int h2) -cpdef H3int edge(H3int origin, H3int destination) except 1 -cpdef bool is_edge(H3int e) -cpdef H3int edge_origin(H3int e) except 1 -cpdef H3int edge_destination(H3int e) except 1 -cpdef (H3int, H3int) edge_cells(H3int e) except * -cpdef H3int[:] edges_from_cell(H3int origin) -cpdef double mean_edge_length(int resolution, unit=*) except -1 -cpdef double edge_length(H3int e, unit=*) except -1 +# cpdef bool are_neighbors(H3int h1, H3int h2) +# cpdef H3int edge(H3int origin, H3int destination) except 1 +# cpdef bool is_edge(H3int e) +# cpdef H3int edge_origin(H3int e) except 1 +# cpdef H3int edge_destination(H3int e) except 1 +# cpdef (H3int, H3int) edge_cells(H3int e) except * +# cpdef H3int[:] edges_from_cell(H3int origin) +# cpdef double mean_edge_length(int resolution, unit=*) except -1 +# cpdef double edge_length(H3int e, unit=*) except -1 diff --git a/src/h3/_cy/edges.pyx b/src/h3/_cy/edges.pyx index 6560006..27397d9 100644 --- a/src/h3/_cy/edges.pyx +++ b/src/h3/_cy/edges.pyx @@ -1,100 +1,100 @@ -cimport h3lib -from .h3lib cimport bool, H3int +# cimport h3lib +# from .h3lib cimport bool, H3int -from .util cimport ( - check_cell, - check_edge, - check_res, - create_ptr, - create_mv, -) +# from .util cimport ( +# check_cell, +# check_edge, +# check_res, +# create_ptr, +# create_mv, +# ) -from .util import H3ValueError +# from .util import H3ValueError -cpdef bool are_neighbors(H3int h1, H3int h2): - check_cell(h1) - check_cell(h2) +# cpdef bool are_neighbors(H3int h1, H3int h2): +# check_cell(h1) +# check_cell(h2) - return h3lib.h3IndexesAreNeighbors(h1, h2) == 1 +# return h3lib.h3IndexesAreNeighbors(h1, h2) == 1 -cpdef H3int edge(H3int origin, H3int destination) except 1: - check_cell(origin) - check_cell(destination) +# cpdef H3int edge(H3int origin, H3int destination) except 1: +# check_cell(origin) +# check_cell(destination) - if h3lib.h3IndexesAreNeighbors(origin, destination) != 1: - s = 'Cells are not neighbors: {} and {}' - s = s.format(hex(origin), hex(destination)) - raise H3ValueError(s) +# if h3lib.h3IndexesAreNeighbors(origin, destination) != 1: +# s = 'Cells are not neighbors: {} and {}' +# s = s.format(hex(origin), hex(destination)) +# raise H3ValueError(s) - return h3lib.getH3UnidirectionalEdge(origin, destination) +# return h3lib.getH3UnidirectionalEdge(origin, destination) -cpdef bool is_edge(H3int e): - return h3lib.h3UnidirectionalEdgeIsValid(e) == 1 +# cpdef bool is_edge(H3int e): +# return h3lib.h3UnidirectionalEdgeIsValid(e) == 1 -cpdef H3int edge_origin(H3int e) except 1: - # without the check, with an invalid input, the function will just return 0 - check_edge(e) +# cpdef H3int edge_origin(H3int e) except 1: +# # without the check, with an invalid input, the function will just return 0 +# check_edge(e) - return h3lib.getOriginH3IndexFromUnidirectionalEdge(e) +# return h3lib.getOriginH3IndexFromUnidirectionalEdge(e) -cpdef H3int edge_destination(H3int e) except 1: - check_edge(e) +# cpdef H3int edge_destination(H3int e) except 1: +# check_edge(e) - return h3lib.getDestinationH3IndexFromUnidirectionalEdge(e) +# return h3lib.getDestinationH3IndexFromUnidirectionalEdge(e) -cpdef (H3int, H3int) edge_cells(H3int e) except *: - check_edge(e) +# cpdef (H3int, H3int) edge_cells(H3int e) except *: +# check_edge(e) - return edge_origin(e), edge_destination(e) +# return edge_origin(e), edge_destination(e) -cpdef H3int[:] edges_from_cell(H3int origin): - """ Returns the 6 (or 5 for pentagons) directed edges - for the given origin cell - """ - check_cell(origin) +# cpdef H3int[:] edges_from_cell(H3int origin): +# """ Returns the 6 (or 5 for pentagons) directed edges +# for the given origin cell +# """ +# check_cell(origin) - ptr = create_ptr(6) - h3lib.getH3UnidirectionalEdgesFromHexagon(origin, ptr) - mv = create_mv(ptr, 6) +# ptr = create_ptr(6) +# h3lib.getH3UnidirectionalEdgesFromHexagon(origin, ptr) +# mv = create_mv(ptr, 6) - return mv +# return mv -cpdef double mean_edge_length(int resolution, unit='km') except -1: - check_res(resolution) +# cpdef double mean_edge_length(int resolution, unit='km') except -1: +# check_res(resolution) - length = h3lib.edgeLengthKm(resolution) +# length = h3lib.edgeLengthKm(resolution) - # todo: multiple units - convert = { - 'km': 1.0, - 'm': 1000.0 - } +# # todo: multiple units +# convert = { +# 'km': 1.0, +# 'm': 1000.0 +# } - try: - length *= convert[unit] - except: - raise H3ValueError('Unknown unit: {}'.format(unit)) +# try: +# length *= convert[unit] +# except: +# raise H3ValueError('Unknown unit: {}'.format(unit)) - return length +# return length -cpdef double edge_length(H3int e, unit='km') except -1: - check_edge(e) +# cpdef double edge_length(H3int e, unit='km') except -1: +# check_edge(e) - # todo: maybe kick this logic up to the python level - # it might be a little cleaner, because we can do the "switch statement" - # with a dict, but would require exposing more C functions +# # todo: maybe kick this logic up to the python level +# # it might be a little cleaner, because we can do the "switch statement" +# # with a dict, but would require exposing more C functions - if unit == 'rads': - length = h3lib.exactEdgeLengthRads(e) - elif unit == 'km': - length = h3lib.exactEdgeLengthKm(e) - elif unit == 'm': - length = h3lib.exactEdgeLengthM(e) - else: - raise H3ValueError('Unknown unit: {}'.format(unit)) +# if unit == 'rads': +# length = h3lib.exactEdgeLengthRads(e) +# elif unit == 'km': +# length = h3lib.exactEdgeLengthKm(e) +# elif unit == 'm': +# length = h3lib.exactEdgeLengthM(e) +# else: +# raise H3ValueError('Unknown unit: {}'.format(unit)) - return length +# return length diff --git a/src/h3/_cy/geo.pxd b/src/h3/_cy/geo.pxd index 1a2c1c3..37e32a0 100644 --- a/src/h3/_cy/geo.pxd +++ b/src/h3/_cy/geo.pxd @@ -2,6 +2,6 @@ from .h3lib cimport H3int cpdef H3int geo_to_h3(double lat, double lng, int res) except 1 cpdef (double, double) h3_to_geo(H3int h) except * -cpdef double point_dist( - double lat1, double lng1, - double lat2, double lng2, unit=*) except -1 +# cpdef double point_dist( +# double lat1, double lng1, +# double lat2, double lng2, unit=*) except -1 diff --git a/src/h3/_cy/geo.pyx b/src/h3/_cy/geo.pyx index dc2c1d7..fe6c93b 100644 --- a/src/h3/_cy/geo.pyx +++ b/src/h3/_cy/geo.pyx @@ -16,263 +16,268 @@ from .util import H3ValueError cpdef H3int geo_to_h3(double lat, double lng, int res) except 1: cdef: - h3lib.GeoCoord c + h3lib.LatLng c + H3int out + h3lib.H3Error err check_res(res) - c = deg2coord(lat, lng) - return h3lib.geoToH3(&c, res) + # todo: just ignoring the error for now, check in the future + err = h3lib.latLngToCell(&c, res, &out) + + return out cpdef (double, double) h3_to_geo(H3int h) except *: """Map an H3 cell into its centroid geo-coordinate (lat/lng)""" cdef: - h3lib.GeoCoord c + h3lib.LatLng c + h3lib.H3Error err check_cell(h) - h3lib.h3ToGeo(h, &c) + err = h3lib.cellToLatLng(h, &c) return coord2deg(c) -cdef h3lib.Geofence make_geofence(geos, bool lnglat_order=False) except *: - """ +# cdef h3lib.Geofence make_geofence(geos, bool lnglat_order=False) except *: +# """ - The returned `Geofence` must be freed with a call to `free_geofence`. - - Parameters - ---------- - geos : list or tuple - GeoFence: A sequence of >= 3 (lat, lng) pairs where the last - element may or may not be same as the first (to form a closed loop). - The order of the pairs may be either clockwise or counterclockwise. - lnglat_order : bool - If True, assume coordinate pairs like (lng, lat) - If False, assume coordinate pairs like (lat, lng) - """ - cdef: - h3lib.Geofence gf +# The returned `Geofence` must be freed with a call to `free_geofence`. + +# Parameters +# ---------- +# geos : list or tuple +# GeoFence: A sequence of >= 3 (lat, lng) pairs where the last +# element may or may not be same as the first (to form a closed loop). +# The order of the pairs may be either clockwise or counterclockwise. +# lnglat_order : bool +# If True, assume coordinate pairs like (lng, lat) +# If False, assume coordinate pairs like (lat, lng) +# """ +# cdef: +# h3lib.Geofence gf - gf.numVerts = len(geos) +# gf.numVerts = len(geos) - gf.verts = stdlib.calloc(gf.numVerts, sizeof(h3lib.GeoCoord)) +# gf.verts = stdlib.calloc(gf.numVerts, sizeof(h3lib.GeoCoord)) - if lnglat_order: - latlng = (g[::-1] for g in geos) - else: - latlng = geos +# if lnglat_order: +# latlng = (g[::-1] for g in geos) +# else: +# latlng = geos - for i, (lat, lng) in enumerate(latlng): - gf.verts[i] = deg2coord(lat, lng) +# for i, (lat, lng) in enumerate(latlng): +# gf.verts[i] = deg2coord(lat, lng) - return gf +# return gf -cdef free_geofence(h3lib.Geofence* gf): - stdlib.free(gf.verts) - gf.verts = NULL +# cdef free_geofence(h3lib.Geofence* gf): +# stdlib.free(gf.verts) +# gf.verts = NULL -cdef class GeoPolygon: - cdef: - h3lib.GeoPolygon gp +# cdef class GeoPolygon: +# cdef: +# h3lib.GeoPolygon gp - def __cinit__(self, outer, holes=None, bool lnglat_order=False): - """ +# def __cinit__(self, outer, holes=None, bool lnglat_order=False): +# """ - Parameters - ---------- - outer : list or tuple - GeoFence - A GeoFence is a sequence of >= 3 (lat, lng) pairs where the last - element may or may not be same as the first (to form a closed loop). - The order of the pairs may be either clockwise or counterclockwise. - holes : list or tuple - A sequence of GeoFences - lnglat_order : bool - If True, assume coordinate pairs like (lng, lat) - If False, assume coordinate pairs like (lat, lng) +# Parameters +# ---------- +# outer : list or tuple +# GeoFence +# A GeoFence is a sequence of >= 3 (lat, lng) pairs where the last +# element may or may not be same as the first (to form a closed loop). +# The order of the pairs may be either clockwise or counterclockwise. +# holes : list or tuple +# A sequence of GeoFences +# lnglat_order : bool +# If True, assume coordinate pairs like (lng, lat) +# If False, assume coordinate pairs like (lat, lng) - """ - if holes is None: - holes = [] +# """ +# if holes is None: +# holes = [] - self.gp.geofence = make_geofence(outer, lnglat_order) - self.gp.numHoles = len(holes) - self.gp.holes = NULL +# self.gp.geofence = make_geofence(outer, lnglat_order) +# self.gp.numHoles = len(holes) +# self.gp.holes = NULL - if len(holes) > 0: - self.gp.holes = stdlib.calloc(len(holes), sizeof(h3lib.Geofence)) - for i, hole in enumerate(holes): - self.gp.holes[i] = make_geofence(hole, lnglat_order) +# if len(holes) > 0: +# self.gp.holes = stdlib.calloc(len(holes), sizeof(h3lib.Geofence)) +# for i, hole in enumerate(holes): +# self.gp.holes[i] = make_geofence(hole, lnglat_order) - def __dealloc__(self): - free_geofence(&self.gp.geofence) +# def __dealloc__(self): +# free_geofence(&self.gp.geofence) - for i in range(self.gp.numHoles): - free_geofence(&self.gp.holes[i]) +# for i in range(self.gp.numHoles): +# free_geofence(&self.gp.holes[i]) - stdlib.free(self.gp.holes) +# stdlib.free(self.gp.holes) -def polyfill_polygon(outer, int res, holes=None, bool lnglat_order=False): - """ Set of hexagons whose center is contained in a polygon. +# def polyfill_polygon(outer, int res, holes=None, bool lnglat_order=False): +# """ Set of hexagons whose center is contained in a polygon. - The polygon is defined as in the GeoJson standard, with an exterior - LinearRing `outer` and a list of LinearRings `holes`, which define any - holes in the polygon. +# The polygon is defined as in the GeoJson standard, with an exterior +# LinearRing `outer` and a list of LinearRings `holes`, which define any +# holes in the polygon. - Each LinearRing may be in clockwise or counter-clockwise order - (right-hand rule or not), and may or may not be a closed loop (where the last - element is equal to the first). - The GeoJSON spec requires the right-hand rule, and a closed loop, but - this function will work with any input format. +# Each LinearRing may be in clockwise or counter-clockwise order +# (right-hand rule or not), and may or may not be a closed loop (where the last +# element is equal to the first). +# The GeoJSON spec requires the right-hand rule, and a closed loop, but +# this function will work with any input format. - Parameters - ---------- - outer : list or tuple - A LinearRing, a sequence of (lat/lng) or (lng/lat) pairs - res : int - The resolution of the output hexagons - holes : list or tuple - A collection of LinearRings, describing any holes in the polygon - lnglat_order : bool - If True, assume coordinate pairs like (lng, lat) - If False, assume coordinate pairs like (lat, lng) - """ +# Parameters +# ---------- +# outer : list or tuple +# A LinearRing, a sequence of (lat/lng) or (lng/lat) pairs +# res : int +# The resolution of the output hexagons +# holes : list or tuple +# A collection of LinearRings, describing any holes in the polygon +# lnglat_order : bool +# If True, assume coordinate pairs like (lng, lat) +# If False, assume coordinate pairs like (lat, lng) +# """ - check_res(res) - gp = GeoPolygon(outer, holes=holes, lnglat_order=lnglat_order) +# check_res(res) +# gp = GeoPolygon(outer, holes=holes, lnglat_order=lnglat_order) - n = h3lib.maxPolyfillSize(&gp.gp, res) - ptr = create_ptr(n) +# n = h3lib.maxPolyfillSize(&gp.gp, res) +# ptr = create_ptr(n) - h3lib.polyfill(&gp.gp, res, ptr) - mv = create_mv(ptr, n) +# h3lib.polyfill(&gp.gp, res, ptr) +# mv = create_mv(ptr, n) - return mv +# return mv -def polyfill_geojson(geojson, int res): - """ Set of hexagons whose center is contained in a GeoJson Polygon object. +# def polyfill_geojson(geojson, int res): +# """ Set of hexagons whose center is contained in a GeoJson Polygon object. - The polygon is defined exactly as in the GeoJson standard, so - `geojson` should be a dictionary like: - { - 'type': 'Polygon', - 'coordinates': [...] - } +# The polygon is defined exactly as in the GeoJson standard, so +# `geojson` should be a dictionary like: +# { +# 'type': 'Polygon', +# 'coordinates': [...] +# } - 'coordinates' should be a list of LinearRings, where the first ring describes - the exterior boundary of the Polygon, and any subsequent LinearRings - describe holes in the polygon. +# 'coordinates' should be a list of LinearRings, where the first ring describes +# the exterior boundary of the Polygon, and any subsequent LinearRings +# describe holes in the polygon. - Note that we don't provide an option for the order of the coordinates, - as the GeoJson standard requires them to be in lng/lat order. +# Note that we don't provide an option for the order of the coordinates, +# as the GeoJson standard requires them to be in lng/lat order. - Parameters - ---------- - geojson : dict - res : int - The resolution of the output hexagons - """ +# Parameters +# ---------- +# geojson : dict +# res : int +# The resolution of the output hexagons +# """ - # todo: this one could handle multipolygons... +# # todo: this one could handle multipolygons... - if geojson['type'] != 'Polygon': - raise ValueError('Only Polygon GeoJSON supported') +# if geojson['type'] != 'Polygon': +# raise ValueError('Only Polygon GeoJSON supported') - coords = geojson['coordinates'] +# coords = geojson['coordinates'] - out = polyfill_polygon(coords[0], res, holes=coords[1:], lnglat_order=True) +# out = polyfill_polygon(coords[0], res, holes=coords[1:], lnglat_order=True) - return out +# return out -def polyfill(dict geojson, int res, bool geo_json_conformant=False): - """ Light wrapper around `polyfill_geojson` to provide backward compatibility. - """ +# def polyfill(dict geojson, int res, bool geo_json_conformant=False): +# """ Light wrapper around `polyfill_geojson` to provide backward compatibility. +# """ - try: - gj_type = geojson['type'] - except KeyError: - raise KeyError("`geojson` dict must have key 'type'.") from None +# try: +# gj_type = geojson['type'] +# except KeyError: +# raise KeyError("`geojson` dict must have key 'type'.") from None - if gj_type != 'Polygon': - raise ValueError('Only Polygon GeoJSON supported') +# if gj_type != 'Polygon': +# raise ValueError('Only Polygon GeoJSON supported') - if geo_json_conformant: - out = polyfill_geojson(geojson, res) - else: - coords = geojson['coordinates'] - out = polyfill_polygon(coords[0], res, holes=coords[1:], lnglat_order=False) +# if geo_json_conformant: +# out = polyfill_geojson(geojson, res) +# else: +# coords = geojson['coordinates'] +# out = polyfill_polygon(coords[0], res, holes=coords[1:], lnglat_order=False) - return out +# return out -def cell_boundary(H3int h, bool geo_json=False): - """Compose an array of geo-coordinates that outlines a hexagonal cell""" - cdef: - h3lib.GeoBoundary gb +# def cell_boundary(H3int h, bool geo_json=False): +# """Compose an array of geo-coordinates that outlines a hexagonal cell""" +# cdef: +# h3lib.GeoBoundary gb - check_cell(h) +# check_cell(h) - h3lib.h3ToGeoBoundary(h, &gb) +# h3lib.h3ToGeoBoundary(h, &gb) - verts = tuple( - coord2deg(gb.verts[i]) - for i in range(gb.num_verts) - ) +# verts = tuple( +# coord2deg(gb.verts[i]) +# for i in range(gb.num_verts) +# ) - if geo_json: - #lat/lng -> lng/lat and last point same as first - verts += (verts[0],) - verts = tuple(v[::-1] for v in verts) +# if geo_json: +# #lat/lng -> lng/lat and last point same as first +# verts += (verts[0],) +# verts = tuple(v[::-1] for v in verts) - return verts +# return verts -def edge_boundary(H3int edge, bool geo_json=False): - """ Returns the GeoBoundary containing the coordinates of the edge - """ - cdef: - h3lib.GeoBoundary gb +# def edge_boundary(H3int edge, bool geo_json=False): +# """ Returns the GeoBoundary containing the coordinates of the edge +# """ +# cdef: +# h3lib.GeoBoundary gb - check_edge(edge) +# check_edge(edge) - h3lib.getH3UnidirectionalEdgeBoundary(edge, &gb) +# h3lib.getH3UnidirectionalEdgeBoundary(edge, &gb) - # todo: move this verts transform into the GeoBoundary object - verts = tuple( - coord2deg(gb.verts[i]) - for i in range(gb.num_verts) - ) +# # todo: move this verts transform into the GeoBoundary object +# verts = tuple( +# coord2deg(gb.verts[i]) +# for i in range(gb.num_verts) +# ) - if geo_json: - #lat/lng -> lng/lat and last point same as first - verts += (verts[0],) - verts = tuple(v[::-1] for v in verts) +# if geo_json: +# #lat/lng -> lng/lat and last point same as first +# verts += (verts[0],) +# verts = tuple(v[::-1] for v in verts) - return verts +# return verts -cpdef double point_dist( - double lat1, double lng1, - double lat2, double lng2, unit='km') except -1: +# cpdef double point_dist( +# double lat1, double lng1, +# double lat2, double lng2, unit='km') except -1: - a = deg2coord(lat1, lng1) - b = deg2coord(lat2, lng2) +# a = deg2coord(lat1, lng1) +# b = deg2coord(lat2, lng2) - if unit == 'rads': - d = h3lib.pointDistRads(&a, &b) - elif unit == 'km': - d = h3lib.pointDistKm(&a, &b) - elif unit == 'm': - d = h3lib.pointDistM(&a, &b) - else: - raise H3ValueError('Unknown unit: {}'.format(unit)) +# if unit == 'rads': +# d = h3lib.pointDistRads(&a, &b) +# elif unit == 'km': +# d = h3lib.pointDistKm(&a, &b) +# elif unit == 'm': +# d = h3lib.pointDistM(&a, &b) +# else: +# raise H3ValueError('Unknown unit: {}'.format(unit)) - return d +# return d diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index 5fa05cc..633af81 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -3,6 +3,7 @@ from cpython cimport bool from libc.stdint cimport int64_t ctypedef stdint.uint64_t H3int +ctypedef stdint.uint32_t H3Error ctypedef basestring H3str cdef extern from "h3api.h": @@ -12,157 +13,160 @@ cdef extern from "h3api.h": ctypedef stdint.uint64_t H3Index - ctypedef struct GeoCoord: + ctypedef struct LatLng: double lat # in radians - double lng "lon" # in radians + double lng # in radians - ctypedef struct GeoBoundary: - int num_verts "numVerts" - GeoCoord verts[10] # MAX_CELL_BNDRY_VERTS - - ctypedef struct Geofence: - int numVerts - GeoCoord *verts - - ctypedef struct GeoPolygon: - Geofence geofence - int numHoles - Geofence *holes - - ctypedef struct GeoMultiPolygon: - int numPolygons - GeoPolygon *polygons - - ctypedef struct LinkedGeoCoord: - GeoCoord data "vertex" - LinkedGeoCoord *next - - # renaming these for clarity - ctypedef struct LinkedGeoLoop: - LinkedGeoCoord *data "first" - LinkedGeoCoord *_data_last "last" # not needed in Cython bindings - LinkedGeoLoop *next - - ctypedef struct LinkedGeoPolygon: - LinkedGeoLoop *data "first" - LinkedGeoLoop *_data_last "last" # not needed in Cython bindings - LinkedGeoPolygon *next - - ctypedef struct CoordIJ: - int i - int j - - H3Index geoToH3(const GeoCoord *g, int res) nogil - - void h3ToGeo(H3Index h3, GeoCoord *g) nogil - - void h3ToGeoBoundary(H3Index h3, GeoBoundary *gp) - - int maxKringSize(int k) - - int hexRange(H3Index origin, int k, H3Index *out) - - int hexRangeDistances(H3Index origin, int k, H3Index *out, int *distances) - - int h3Distance(H3Index origin, H3Index h3) - - int hexRanges(H3Index *h3Set, int length, int k, H3Index *out) - - void kRing(H3Index origin, int k, H3Index *out) - - void kRingDistances(H3Index origin, int k, H3Index *out, int *distances) - - int hexRing(H3Index origin, int k, H3Index *out) - - int maxPolyfillSize(const GeoPolygon *geoPolygon, int res) - - void polyfill(const GeoPolygon *geoPolygon, int res, H3Index *out) - - void h3SetToLinkedGeo(const H3Index *h3Set, const int numHexes, LinkedGeoPolygon *out) - - void destroyLinkedPolygon(LinkedGeoPolygon *polygon) + int isValidCell(H3Index h) nogil + int isPentagon(H3Index h) nogil + int isResClassIII(H3Index h) nogil + int isValidDirectedEdge(H3Index edge) nogil double degsToRads(double degrees) nogil - double radsToDegs(double radians) nogil - stdint.int64_t numHexagons(int res) + int getResolution(H3Index h) nogil + int getBaseCellNumber(H3Index h) nogil - int h3GetResolution(H3Index h) nogil + H3Error latLngToCell(const LatLng *g, int res, H3Index *out) nogil + H3Error cellToLatLng(H3Index h, LatLng *) nogil + H3Error gridDistance(H3Index h1, H3Index h2, int64_t *distance) nogil - int h3GetBaseCell(H3Index h) + H3Error maxGridDiskSize(int k, int64_t *out) nogil # num/out/N? + H3Error gridDisk(H3Index h, int k, H3Index *out) nogil - H3Index stringToH3(const char *str) + H3Error cellToParent( H3Index h, int parentRes, H3Index *parent) nogil + H3Error cellToCenterChild(H3Index h, int childRes, H3Index *child) nogil - void h3ToString(H3Index h, char *str, size_t sz) + H3Error cellToChildrenSize(H3Index h, int childRes, int64_t *num) nogil # num/out/N? + H3Error cellToChildren( H3Index h, int childRes, H3Index *children) nogil - int h3IsValid(H3Index h) + H3Error compactCells( + const H3Index *cells_u, + H3Index *cells_c, + const int num_u + ) nogil + H3Error uncompactCellsSize( + const H3Index *cells_c, + const int64_t num_c, + const int res, + int64_t *num_u + ) nogil + H3Error uncompactCells( + const H3Index *cells_c, + const int num_c, + H3Index *cells_u, + const int num_u, + const int res + ) nogil - H3Index h3ToParent(H3Index h, int parentRes) nogil + H3Error getNumCells(int res, int64_t *out) - int maxH3ToChildrenSize(H3Index h, int childRes) + # ctypedef struct GeoBoundary: + # int num_verts "numVerts" + # GeoCoord verts[10] # MAX_CELL_BNDRY_VERTS - void h3ToChildren(H3Index h, int childRes, H3Index *children) + # ctypedef struct Geofence: + # int numVerts + # GeoCoord *verts - int compact(const H3Index *h3Set, H3Index *compactedSet, const int numHexes) + # ctypedef struct GeoPolygon: + # Geofence geofence + # int numHoles + # Geofence *holes - int maxUncompactSize(const H3Index *compactedSet, const int numHexes, const int res) + # ctypedef struct GeoMultiPolygon: + # int numPolygons + # GeoPolygon *polygons - int uncompact(const H3Index *compactedSet, const int numHexes, H3Index *h3Set, const int maxHexes, const int res) + # ctypedef struct LinkedGeoCoord: + # GeoCoord data "vertex" + # LinkedGeoCoord *next - int h3IsResClassIII(H3Index h) + # # renaming these for clarity + # ctypedef struct LinkedGeoLoop: + # LinkedGeoCoord *data "first" + # LinkedGeoCoord *_data_last "last" # not needed in Cython bindings + # LinkedGeoLoop *next - int h3IsPentagon(H3Index h) + # ctypedef struct LinkedGeoPolygon: + # LinkedGeoLoop *data "first" + # LinkedGeoLoop *_data_last "last" # not needed in Cython bindings + # LinkedGeoPolygon *next - int pentagonIndexCount() + # ctypedef struct CoordIJ: + # int i + # int j - void getPentagonIndexes(int res, H3Index *out) + # void h3ToGeoBoundary(H3Index h3, GeoBoundary *gp) - int res0IndexCount() + # int hexRange(H3Index origin, int k, H3Index *out) - void getRes0Indexes(H3Index *out) + # int hexRangeDistances(H3Index origin, int k, H3Index *out, int *distances) - H3Index h3ToCenterChild(H3Index h, int res) + # int hexRanges(H3Index *h3Set, int length, int k, H3Index *out) - int h3IndexesAreNeighbors(H3Index origin, H3Index destination) + # void kRingDistances(H3Index origin, int k, H3Index *out, int *distances) - H3Index getH3UnidirectionalEdge(H3Index origin, H3Index destination) + # int hexRing(H3Index origin, int k, H3Index *out) - int h3UnidirectionalEdgeIsValid(H3Index edge) + # int maxPolyfillSize(const GeoPolygon *geoPolygon, int res) - H3Index getOriginH3IndexFromUnidirectionalEdge(H3Index edge) + # void polyfill(const GeoPolygon *geoPolygon, int res, H3Index *out) - H3Index getDestinationH3IndexFromUnidirectionalEdge(H3Index edge) + # void h3SetToLinkedGeo(const H3Index *h3Set, const int numHexes, LinkedGeoPolygon *out) - void getH3IndexesFromUnidirectionalEdge(H3Index edge, H3Index *originDestination) + # void destroyLinkedPolygon(LinkedGeoPolygon *polygon) - void getH3UnidirectionalEdgesFromHexagon(H3Index origin, H3Index *edges) + # H3Index stringToH3(const char *str) - void getH3UnidirectionalEdgeBoundary(H3Index edge, GeoBoundary *gb) + # void h3ToString(H3Index h, char *str, size_t sz) - int h3LineSize(H3Index start, H3Index end) - int h3Line(H3Index start, H3Index end, H3Index *out) + # int pentagonIndexCount() - int maxFaceCount(H3Index h3) - void h3GetFaces(H3Index h3, int *out) + # void getPentagonIndexes(int res, H3Index *out) - int experimentalH3ToLocalIj(H3Index origin, H3Index h3, CoordIJ *out) - int experimentalLocalIjToH3(H3Index origin, const CoordIJ *ij, H3Index *out) + # int res0IndexCount() - double hexAreaKm2(int res) nogil - double hexAreaM2(int res) nogil + # void getRes0Indexes(H3Index *out) - double cellAreaRads2(H3Index h) nogil - double cellAreaKm2(H3Index h) nogil - double cellAreaM2(H3Index h) nogil + # int h3IndexesAreNeighbors(H3Index origin, H3Index destination) - double edgeLengthKm(int res) nogil - double edgeLengthM(int res) nogil + # H3Index getH3UnidirectionalEdge(H3Index origin, H3Index destination) - double exactEdgeLengthRads(H3Index edge) nogil - double exactEdgeLengthKm(H3Index edge) nogil - double exactEdgeLengthM(H3Index edge) nogil + # H3Index getOriginH3IndexFromUnidirectionalEdge(H3Index edge) - double pointDistRads(const GeoCoord *a, const GeoCoord *b) nogil - double pointDistKm(const GeoCoord *a, const GeoCoord *b) nogil - double pointDistM(const GeoCoord *a, const GeoCoord *b) nogil + # H3Index getDestinationH3IndexFromUnidirectionalEdge(H3Index edge) + + # void getH3IndexesFromUnidirectionalEdge(H3Index edge, H3Index *originDestination) + + # void getH3UnidirectionalEdgesFromHexagon(H3Index origin, H3Index *edges) + + # void getH3UnidirectionalEdgeBoundary(H3Index edge, GeoBoundary *gb) + + # int h3LineSize(H3Index start, H3Index end) + # int h3Line(H3Index start, H3Index end, H3Index *out) + + # int maxFaceCount(H3Index h3) + # void h3GetFaces(H3Index h3, int *out) + + # int experimentalH3ToLocalIj(H3Index origin, H3Index h3, CoordIJ *out) + # int experimentalLocalIjToH3(H3Index origin, const CoordIJ *ij, H3Index *out) + + # double hexAreaKm2(int res) nogil + # double hexAreaM2(int res) nogil + + # double cellAreaRads2(H3Index h) nogil + # double cellAreaKm2(H3Index h) nogil + # double cellAreaM2(H3Index h) nogil + + # double edgeLengthKm(int res) nogil + # double edgeLengthM(int res) nogil + + # double exactEdgeLengthRads(H3Index edge) nogil + # double exactEdgeLengthKm(H3Index edge) nogil + # double exactEdgeLengthM(H3Index edge) nogil + + # double pointDistRads(const GeoCoord *a, const GeoCoord *b) nogil + # double pointDistKm(const GeoCoord *a, const GeoCoord *b) nogil + # double pointDistM(const GeoCoord *a, const GeoCoord *b) nogil diff --git a/src/h3/_cy/to_multipoly.pyx b/src/h3/_cy/to_multipoly.pyx index 8e5ca55..296a932 100644 --- a/src/h3/_cy/to_multipoly.pyx +++ b/src/h3/_cy/to_multipoly.pyx @@ -1,75 +1,75 @@ -cimport h3lib -from h3lib cimport H3int -from .util cimport check_cell, coord2deg +# cimport h3lib +# from h3lib cimport H3int +# from .util cimport check_cell, coord2deg -# todo: it's driving me crazy that these three functions are all essentially the same linked list walker... -# grumble: no way to do iterators in with cdef functions! -cdef walk_polys(const h3lib.LinkedGeoPolygon* L): - out = [] - while L: - out += [walk_loops(L.data)] - L = L.next +# # todo: it's driving me crazy that these three functions are all essentially the same linked list walker... +# # grumble: no way to do iterators in with cdef functions! +# cdef walk_polys(const h3lib.LinkedGeoPolygon* L): +# out = [] +# while L: +# out += [walk_loops(L.data)] +# L = L.next - return out +# return out -cdef walk_loops(const h3lib.LinkedGeoLoop* L): - out = [] - while L: - out += [walk_coords(L.data)] - L = L.next +# cdef walk_loops(const h3lib.LinkedGeoLoop* L): +# out = [] +# while L: +# out += [walk_coords(L.data)] +# L = L.next - return out +# return out -cdef walk_coords(const h3lib.LinkedGeoCoord* L): - out = [] - while L: - out += [coord2deg(L.data)] - L = L.next +# cdef walk_coords(const h3lib.LinkedGeoCoord* L): +# out = [] +# while L: +# out += [coord2deg(L.data)] +# L = L.next - return out +# return out -# todo: tuples instead of lists? -def _to_multi_polygon(const H3int[:] hexes): - cdef: - h3lib.LinkedGeoPolygon polygon +# # todo: tuples instead of lists? +# def _to_multi_polygon(const H3int[:] hexes): +# cdef: +# h3lib.LinkedGeoPolygon polygon - for h in hexes: - check_cell(h) +# for h in hexes: +# check_cell(h) - h3lib.h3SetToLinkedGeo(&hexes[0], len(hexes), &polygon) +# h3lib.h3SetToLinkedGeo(&hexes[0], len(hexes), &polygon) - out = walk_polys(&polygon) +# out = walk_polys(&polygon) - # we're still responsible for cleaning up the passed in `polygon`, - # but not a problem here, since it is stack allocated - h3lib.destroyLinkedPolygon(&polygon) +# # we're still responsible for cleaning up the passed in `polygon`, +# # but not a problem here, since it is stack allocated +# h3lib.destroyLinkedPolygon(&polygon) - return out +# return out -def _geojson_loop(loop): - """ Swap lat/lng order and close loop. - """ - loop = [e[::-1] for e in loop] - loop += [loop[0]] +# def _geojson_loop(loop): +# """ Swap lat/lng order and close loop. +# """ +# loop = [e[::-1] for e in loop] +# loop += [loop[0]] - return loop +# return loop -def h3_set_to_multi_polygon(const H3int[:] hexes, geo_json=False): - # todo: gotta be a more elegant way to handle these... - if len(hexes) == 0: - return [] +# def h3_set_to_multi_polygon(const H3int[:] hexes, geo_json=False): +# # todo: gotta be a more elegant way to handle these... +# if len(hexes) == 0: +# return [] - multipoly = _to_multi_polygon(hexes) +# multipoly = _to_multi_polygon(hexes) - if geo_json: - multipoly = [ - [_geojson_loop(loop) for loop in poly] - for poly in multipoly - ] +# if geo_json: +# multipoly = [ +# [_geojson_loop(loop) for loop in poly] +# for poly in multipoly +# ] - return multipoly +# return multipoly diff --git a/src/h3/_cy/unstable_vect.pyx b/src/h3/_cy/unstable_vect.pyx deleted file mode 100644 index 316ac12..0000000 --- a/src/h3/_cy/unstable_vect.pyx +++ /dev/null @@ -1,89 +0,0 @@ -cimport h3lib -from h3lib cimport H3int -from .util cimport deg2coord - -from cython cimport boundscheck, wraparound -from libc.math cimport sqrt, sin, cos, asin - -cdef double haversineDistance(double th1, double ph1, double th2, double ph2) nogil: - cdef: - double dx, dy, dz - double R = 6371.0088 - - ph1 -= ph2 - - dz = sin(th1) - sin(th2) - dx = cos(ph1) * cos(th1) - cos(th2) - dy = sin(ph1) * cos(th1) - - return asin(sqrt(dx*dx + dy*dy + dz*dz) / 2)*2*R - - -@boundscheck(False) -@wraparound(False) -cpdef void haversine_vect( - const H3int[:] a, - const H3int[:] b, - double[:] out -) nogil: - - cdef h3lib.GeoCoord p1, p2 - - with nogil: - # todo: add these back in when cython 3.0 comes out - #assert len(a) == len(b) - #assert len(a) <= len(out) - - for i in range(len(a)): - h3lib.h3ToGeo(a[i], &p1) - h3lib.h3ToGeo(b[i], &p2) - out[i] = haversineDistance( - p1.lat, p1.lng, - p2.lat, p2.lng - ) - - -@boundscheck(False) -@wraparound(False) -cpdef void geo_to_h3_vect( - const double[:] lat, - const double[:] lng, - int res, - H3int[:] out -) nogil: - - cdef h3lib.GeoCoord c - - with nogil: - for i in range(len(lat)): - c = deg2coord(lat[i], lng[i]) - out[i] = h3lib.geoToH3(&c, res) - - -@boundscheck(False) -@wraparound(False) -cpdef void h3_to_parent_vect( - const H3int[:] h, - int[:] res, - H3int[:] out -) nogil: - - cdef Py_ssize_t i - - with nogil: - for i in range(len(h)): - out[i] = h3lib.h3ToParent(h[i], res[i]) - - -@boundscheck(False) -@wraparound(False) -cpdef void h3_get_resolution_vect( - const H3int[:] h, - int[:] out, -) nogil: - - cdef Py_ssize_t i - - with nogil: - for i in range(len(h)): - out[i] = h3lib.h3GetResolution(h[i]) diff --git a/src/h3/_cy/util.pxd b/src/h3/_cy/util.pxd index 06cc26a..6a34b75 100644 --- a/src/h3/_cy/util.pxd +++ b/src/h3/_cy/util.pxd @@ -1,7 +1,7 @@ -from .h3lib cimport H3int, H3str, GeoCoord +from .h3lib cimport H3int, H3str, LatLng -cdef GeoCoord deg2coord(double lat, double lng) nogil -cdef (double, double) coord2deg(GeoCoord c) nogil +cdef LatLng deg2coord(double lat, double lng) nogil +cdef (double, double) coord2deg(LatLng c) nogil cpdef H3int hex2int(H3str h) except? 0 cpdef H3str int2hex(H3int x) diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index dbf17da..bbb63e4 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -1,13 +1,13 @@ from libc cimport stdlib from cython.view cimport array -from .h3lib cimport H3int, H3str, h3IsValid, h3UnidirectionalEdgeIsValid +from .h3lib cimport H3int, H3str, isValidCell, isValidDirectedEdge cimport h3lib -cdef h3lib.GeoCoord deg2coord(double lat, double lng) nogil: +cdef h3lib.LatLng deg2coord(double lat, double lng) nogil: cdef: - h3lib.GeoCoord c + h3lib.LatLng c c.lat = h3lib.degsToRads(lat) c.lng = h3lib.degsToRads(lng) @@ -15,7 +15,7 @@ cdef h3lib.GeoCoord deg2coord(double lat, double lng) nogil: return c -cdef (double, double) coord2deg(h3lib.GeoCoord c) nogil: +cdef (double, double) coord2deg(h3lib.LatLng c) nogil: return ( h3lib.radsToDegs(c.lat), h3lib.radsToDegs(c.lng) @@ -77,11 +77,11 @@ cdef check_cell(H3int h): is incorrect, but in a format that is easily compared to `str` inputs. """ - if h3IsValid(h) == 0: + if isValidCell(h) == 0: raise H3CellError('Integer is not a valid H3 cell: {}'.format(hex(h))) cdef check_edge(H3int e): - if h3UnidirectionalEdgeIsValid(e) == 0: + if isValidDirectedEdge(e) == 0: raise H3EdgeError('Integer is not a valid H3 edge: {}'.format(hex(e))) cdef check_res(int res): diff --git a/src/h3/_version.py b/src/h3/_version.py index eb5cae0..41540d5 100644 --- a/src/h3/_version.py +++ b/src/h3/_version.py @@ -1,24 +1,25 @@ -__version__ = '3.7.4' +__version__ = '4.0.0' __description__ = 'Hierarchical hexagonal geospatial indexing system' __url__ = 'https://github.com/uber/h3-py' -__license__ = "Apache 2.0 License" +__license__ = 'Apache 2.0 License' __author__ = 'Uber Technologies' __author_email__ = 'AJ Friend ' __classifiers__ = [ - "Development Status :: 5 - Production/Stable", - "Intended Audience :: Developers", - "Intended Audience :: Science/Research", - "License :: OSI Approved :: Apache Software License", - "Programming Language :: C", - "Programming Language :: Cython", - "Programming Language :: Python :: 2.7", - "Programming Language :: Python :: 3.5", - "Programming Language :: Python :: 3.6", - "Programming Language :: Python :: 3.7", - "Programming Language :: Python :: 3.8", - "Programming Language :: Python :: 3.9", - "Operating System :: MacOS :: MacOS X", - "Operating System :: POSIX :: Linux", - "Operating System :: Microsoft :: Windows", - "Topic :: Scientific/Engineering :: GIS", + 'Development Status :: 5 - Production/Stable', + 'Intended Audience :: Developers', + 'Intended Audience :: Science/Research', + 'License :: OSI Approved :: Apache Software License', + 'Programming Language :: C', + 'Programming Language :: Cython', + 'Programming Language :: Python :: 2.7', + 'Programming Language :: Python :: 3.5', + 'Programming Language :: Python :: 3.6', + 'Programming Language :: Python :: 3.7', + 'Programming Language :: Python :: 3.8', + 'Programming Language :: Python :: 3.9', + 'Programming Language :: Python :: 3.10', + 'Operating System :: MacOS :: MacOS X', + 'Operating System :: POSIX :: Linux', + 'Operating System :: Microsoft :: Windows', + 'Topic :: Scientific/Engineering :: GIS', ] diff --git a/src/h3/unstable/__init__.py b/src/h3/unstable/__init__.py deleted file mode 100644 index 5c1839c..0000000 --- a/src/h3/unstable/__init__.py +++ /dev/null @@ -1,9 +0,0 @@ -# flake8: noqa - -import warnings -warnings.warn( - 'Modules under `h3.unstable` are experimental, and may change at any time.' -) - -from . import v4 -from . import vect diff --git a/src/h3/unstable/v4.py b/src/h3/unstable/v4.py deleted file mode 100644 index 833cd6e..0000000 --- a/src/h3/unstable/v4.py +++ /dev/null @@ -1,125 +0,0 @@ -# flake8: noqa - -from ..api.basic_str import ( - # todo: implement is_valid_index - - compact as - compact_cells, - - edge_length as - get_hexagon_edge_length_avg, - - geo_to_h3 as - point_to_cell, - - get_destination_h3_index_from_unidirectional_edge as - get_directed_edge_destination, - - get_h3_indexes_from_unidirectional_edge as - directed_edge_to_cells, - - get_h3_unidirectional_edge as - cells_to_directed_edge, - - get_h3_unidirectional_edge_boundary as - directed_edge_to_boundary, - - get_h3_unidirectional_edges_from_hexagon as - origin_to_directed_edges, - - get_origin_h3_index_from_unidirectional_edge as - get_directed_edge_origin, - - get_pentagon_indexes as - get_pentagons, - - get_res0_indexes as - get_res0_cells, - - h3_distance as - grid_distance, - - h3_get_base_cell as - get_base_cell_number, - - h3_get_faces as - get_icosahedron_faces, - - h3_get_resolution as - get_resolution, - - h3_indexes_are_neighbors as - are_neighbor_cells, - - h3_is_pentagon as - is_pentagon, - - h3_is_res_class_III as - is_res_class_III, - - h3_is_valid as - is_valid_cell, - - h3_line as - grid_path_cells, - - h3_set_to_multi_polygon as - cells_to_multipolygon, - - h3_to_center_child as - cell_to_center_child, - - h3_to_children as - cell_to_children, - - h3_to_geo as - cell_to_point, - - h3_to_geo_boundary as - cell_to_boundary, - - h3_to_parent as - cell_to_parent, - - h3_to_string as - int_to_str, - - h3_unidirectional_edge_is_valid as - is_valid_directed_edge, - - hex_area as - get_hexagon_area_avg, - - # hex_range as _, - # hex_range_distances as _, # not sure we want this one; easy for user to implement - # hex_ranges as _, - - hex_ring as - grid_ring, - - k_ring as - grid_disk, - - k_ring_distances as - grid_disk_distances, - - num_hexagons as - get_num_cells, - - polyfill as - polygon_to_cells, - - polyfill_geojson as - geojson_to_cells, # still need to figure out the final polyfill interface - - #polyfill_polygon as _, - - string_to_h3 as - str_to_int, - - uncompact as - uncompact_cells, - - versions as - versions, -) diff --git a/src/h3/unstable/vect.py b/src/h3/unstable/vect.py deleted file mode 100644 index 122c07d..0000000 --- a/src/h3/unstable/vect.py +++ /dev/null @@ -1,105 +0,0 @@ -from .._cy import unstable_vect as _vect - -import numpy as np - - -def h3_to_parent(h, res=None): - """ - Get parent of arrays of cells. - - Parameters - ---------- - h : array of H3Cells - res: int or None, optional - The resolution for the parent - If `None`, then `res = resolution(h) - 1` - - Returns - ------- - array of H3Cells - """ - h = np.array(h, dtype=np.uint64) - out = np.zeros(len(h), dtype=np.uint64) - - if res is None: - res = h3_get_resolution(h) - 1 - else: - res = np.full(h.shape, res, dtype=np.intc) - - _vect.h3_to_parent_vect(h, res, out) - - return out - - -def h3_get_resolution(h): - """ - Return the resolution of an array of H3 cells. - - Parameters - ---------- - h : H3Cell - - Returns - ------- - array of int - """ - h = np.array(h, dtype=np.uint64) - out = np.zeros(len(h), dtype=np.intc) - - _vect.h3_get_resolution_vect(h, out) - - return out - - -def geo_to_h3(lats, lngs, res): - """ - Convert arrays describing lat/lng pairs to cells. - - Parameters - ---------- - lats, lngs : arrays of floats - - res: int - Resolution for output cells. - - Returns - ------- - array of H3Cells - """ - lats = np.array(lats, dtype=np.float64) - lngs = np.array(lngs, dtype=np.float64) - - assert len(lats) == len(lngs) - - out = np.zeros(len(lats), dtype='uint64') - - _vect.geo_to_h3_vect(lats, lngs, res, out) - - return out - - -def cell_haversine(a, b): - """ - Compute haversine distance between the centers of cells given in - arrays a and b. - - - Parameters - ---------- - a, b : arrays of H3Cell - - Returns - ------- - float - Haversine distance in kilometers - """ - a = np.array(a, dtype=np.uint64) - b = np.array(b, dtype=np.uint64) - - assert len(a) == len(b) - - out = np.zeros(len(a), dtype='double') - - _vect.haversine_vect(a, b, out) - - return out diff --git a/src/h3lib b/src/h3lib index ee292a9..294c20e 160000 --- a/src/h3lib +++ b/src/h3lib @@ -1 +1 @@ -Subproject commit ee292a96906767162f2f530b46fc2428b2555748 +Subproject commit 294c20ed7d447122d5ab37260896d4ef7579ebfb diff --git a/tests/cython_example.pyx b/tests/cython_example.pyx index e8d2859..c19fe21 100644 --- a/tests/cython_example.pyx +++ b/tests/cython_example.pyx @@ -1,18 +1,18 @@ -from cython cimport boundscheck, wraparound +# from cython cimport boundscheck, wraparound -from h3._cy.h3lib cimport H3int -from h3._cy.geo cimport geo_to_h3 +# from h3._cy.h3lib cimport H3int +# from h3._cy.geo cimport geo_to_h3 -@boundscheck(False) -@wraparound(False) -cpdef void geo_to_h3_vect( - const double[:] lat, - const double[:] lng, - int res, - H3int[:] out -): +# @boundscheck(False) +# @wraparound(False) +# cpdef void geo_to_h3_vect( +# const double[:] lat, +# const double[:] lng, +# int res, +# H3int[:] out +# ): - cdef Py_ssize_t i +# cdef Py_ssize_t i - for i in range(len(lat)): - out[i] = geo_to_h3(lat[i], lng[i], res) +# for i in range(len(lat)): +# out[i] = geo_to_h3(lat[i], lng[i], res) diff --git a/tests/h3fake2_errors.py b/tests/h3fake2_errors.py new file mode 100644 index 0000000..da56887 --- /dev/null +++ b/tests/h3fake2_errors.py @@ -0,0 +1,15 @@ +# flake8: noqa +""" +Some of the tests expect to catch certain errors. +As we transition, we'll have errors of each type. +pytest functions can accept tuples of errors to check for either one. +""" + +import h3 +import h3fake2 + +H3ValueError = (h3.H3ValueError, h3fake2.H3ValueError) +H3CellError = (h3.H3CellError, h3fake2.H3CellError) +H3ResolutionError = (h3.H3ResolutionError, h3fake2.H3ResolutionError) +H3EdgeError = (h3.H3EdgeError, h3fake2.H3EdgeError) +H3DistanceError = (h3.H3DistanceError, h3fake2.H3DistanceError) diff --git a/tests/test_cells_and_edges.py b/tests/test_cells_and_edges.py index 173033a..014f519 100644 --- a/tests/test_cells_and_edges.py +++ b/tests/test_cells_and_edges.py @@ -1,7 +1,7 @@ import h3 import pytest -from h3 import ( +from .h3fake2_errors import ( H3ValueError, H3CellError, H3ResolutionError, diff --git a/tests/test_cython.py b/tests/test_cython.py index 30566b1..0acf307 100644 --- a/tests/test_cython.py +++ b/tests/test_cython.py @@ -1,28 +1,28 @@ -import numpy as np +# import numpy as np -# Avoid checking for import-error here because cython_example may not have -# been compiled yet. -try: - from .cython_example import geo_to_h3_vect # pylint: disable=import-error -except ImportError: - geo_to_h3_vect = None +# # Avoid checking for import-error here because cython_example may not have +# # been compiled yet. +# try: +# from .cython_example import geo_to_h3_vect # pylint: disable=import-error +# except ImportError: +# geo_to_h3_vect = None -np.random.seed(0) +# np.random.seed(0) -def test_cython_api(): - if geo_to_h3_vect is None: - print("Not running Cython test because cython example was not compiled") - return +# def test_cython_api(): +# if geo_to_h3_vect is None: +# print("Not running Cython test because cython example was not compiled") +# return - N = 100000 +# N = 100000 - lats, lngs = np.random.uniform(0, 90, N), np.random.uniform(0, 90, N) - res = 9 +# lats, lngs = np.random.uniform(0, 90, N), np.random.uniform(0, 90, N) +# res = 9 - lats = np.array(lats, dtype=np.float64) - lngs = np.array(lngs, dtype=np.float64) - out = np.zeros(len(lats), dtype="uint64") - geo_to_h3_vect(lats, lngs, res, out) +# lats = np.array(lats, dtype=np.float64) +# lngs = np.array(lngs, dtype=np.float64) +# out = np.zeros(len(lats), dtype="uint64") +# geo_to_h3_vect(lats, lngs, res, out) - assert out[0] == 617284541015654399 +# assert out[0] == 617284541015654399 diff --git a/tests/test_length_area.py b/tests/test_length_area.py index 8236199..2a1b5d7 100644 --- a/tests/test_length_area.py +++ b/tests/test_length_area.py @@ -1,7 +1,7 @@ import h3 import pytest -from h3 import H3ValueError +from .h3fake2_errors import H3ValueError def approx2(a, b): diff --git a/tests/test_polyfill.py b/tests/test_polyfill.py index 4739009..a02560d 100644 --- a/tests/test_polyfill.py +++ b/tests/test_polyfill.py @@ -2,6 +2,8 @@ import h3 import itertools import pytest +from .h3fake2_errors import H3ResolutionError + def reverse(loop): return list(reversed(loop)) @@ -209,10 +211,10 @@ def test_resolution(): 'coordinates': [[]], } - with pytest.raises(h3.H3ResolutionError): + with pytest.raises(H3ResolutionError): h3.polyfill(d, -1) - with pytest.raises(h3.H3ResolutionError): + with pytest.raises(H3ResolutionError): h3.polyfill(d, 16) diff --git a/tests/test_unstable_vect.py b/tests/test_unstable_vect.py deleted file mode 100644 index a556aae..0000000 --- a/tests/test_unstable_vect.py +++ /dev/null @@ -1,69 +0,0 @@ -import h3.api.numpy_int as h3 -import numpy as np # only run this test suite if numpy is installed -import pytest - -with pytest.warns( - UserWarning, - match = 'Modules under `h3.unstable` are experimental', -): - import h3.unstable.vect as h3_vect - - -def test_h3_to_parent(): - # At res 9 - h = np.array([617700169958555647, 617700169958555647], np.uint64) - - # Default to res - 1 - arr1 = h3_vect.h3_to_parent(h) - arr2 = h3_vect.h3_to_parent(h, 8) - assert np.array_equal(arr1, arr2) - - # Same as other h3 bindings - arr1 = h3_vect.h3_to_parent(h) - arr2 = np.array(list(map(h3.h3_to_parent, h)), dtype=np.uint64) - assert np.array_equal(arr1, arr2) - - # Test with a number passed to res - arr1 = h3_vect.h3_to_parent(h, 7) - arr2 = np.array([h3.h3_to_parent(c, 7) for c in h], dtype=np.uint64) - assert np.array_equal(arr1, arr2) - - # Test with an array passed to res - arr1 = h3_vect.h3_to_parent(h, np.array([7, 5], np.intc)) - arr2 = h3_vect.h3_to_parent(h, [7, 5]) - - arr3 = [] - for c, res in zip(h, [7, 5]): - arr3.append(h3.h3_to_parent(c, res)) - - assert np.array_equal(arr1, arr2) - assert np.array_equal(arr1, np.array(arr3, dtype=np.uint64)) - - # Test with array-like (but not np.array) cell input - arr1 = h3_vect.h3_to_parent(list(h)) - arr2 = np.array(list(map(h3.h3_to_parent, h)), dtype=np.uint64) - assert np.array_equal(arr1, arr2) - - -def test_h3_to_parent_multiple_res(): - h = np.array([617700169958555647, 613196570331971583], np.uint64) - - # Cells at res 9, 8 - assert list(h3_vect.h3_get_resolution(h)) == [9, 8] - - # Same as other h3 bindings - arr1 = h3_vect.h3_to_parent(h) - arr2 = np.array(list(map(h3.h3_to_parent, h)), dtype=np.uint64) - assert np.array_equal(arr1, arr2) - - # Parent cells are 8, 7 - parents = h3_vect.h3_to_parent(h) - assert list(h3_vect.h3_get_resolution(parents)) == [8, 7] - - -def test_h3_get_resolution(): - h = np.array([617700169958555647], np.uint64) - - arr1 = h3_vect.h3_get_resolution(h) - arr2 = np.array(list(map(h3.h3_get_resolution, h)), dtype=np.intc) - assert np.array_equal(arr1, arr2) From 4ec0a92f109821ad338f701542ab490f585993af Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Tue, 24 May 2022 20:18:44 -0700 Subject: [PATCH 002/177] ajfriend/more v4 funcs (#241) * get_pentagon_indexes and get_res0_indexes * line * cell area functions --- src/h3/_cy/__init__.py | 15 +++-- src/h3/_cy/cells.pxd | 10 +-- src/h3/_cy/cells.pyx | 123 +++++++++++++++++++--------------- src/h3/_cy/h3lib.pxd | 34 +++++----- tests/test_cells_and_edges.py | 10 +-- 5 files changed, 105 insertions(+), 87 deletions(-) diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index 6b17b2d..cfe34c7 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -27,6 +27,11 @@ from .cells import ( compact, uncompact, num_hexagons, + get_pentagon_indexes, + get_res0_indexes, + line, + mean_hex_area, + cell_area, ) from h3fake2._cy import ( @@ -42,12 +47,12 @@ from h3fake2._cy import ( # compact, # uncompact, # num_hexagons, - mean_hex_area, - cell_area, - line, + # mean_hex_area, + # cell_area, + # line, # is_res_class_iii, - get_pentagon_indexes, - get_res0_indexes, + # get_pentagon_indexes, + # get_res0_indexes, # center_child, get_faces, experimental_h3_to_local_ij, diff --git a/src/h3/_cy/cells.pxd b/src/h3/_cy/cells.pxd index 4e2d441..0dd3aa6 100644 --- a/src/h3/_cy/cells.pxd +++ b/src/h3/_cy/cells.pxd @@ -14,12 +14,12 @@ cpdef H3int center_child(H3int h, res=*) except 0 cpdef H3int[:] compact(const H3int[:] hu) cpdef H3int[:] uncompact(const H3int[:] hc, int res) cpdef int64_t num_hexagons(int resolution) except -1 -# cpdef double mean_hex_area(int resolution, unit=*) except -1 -# cpdef double cell_area(H3int h, unit=*) except -1 -# cpdef H3int[:] line(H3int start, H3int end) +cpdef double mean_hex_area(int resolution, unit=*) except -1 +cpdef double cell_area(H3int h, unit=*) except -1 +cpdef H3int[:] line(H3int start, H3int end) cpdef bool is_res_class_iii(H3int h) -# cpdef H3int[:] get_pentagon_indexes(int res) -# cpdef H3int[:] get_res0_indexes() +cpdef H3int[:] get_pentagon_indexes(int res) +cpdef H3int[:] get_res0_indexes() # cpdef get_faces(H3int h) # cpdef (int, int) experimental_h3_to_local_ij(H3int origin, H3int h) except * # cpdef H3int experimental_local_ij_to_h3(H3int origin, int i, int j) except 0 diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 265e4c3..9cfcbb2 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -281,87 +281,104 @@ cpdef int64_t num_hexagons(int resolution) except -1: return num_cells -# cpdef double mean_hex_area(int resolution, unit='km^2') except -1: -# check_res(resolution) +cpdef double mean_hex_area(int resolution, unit='km^2') except -1: + cdef: + h3lib.H3Error err + double area -# area = h3lib.hexAreaKm2(resolution) + check_res(resolution) -# # todo: multiple units -# convert = { -# 'km^2': 1.0, -# 'm^2': 1000*1000.0 -# } + err = h3lib.getHexagonAreaAvgKm2(resolution, &area) -# try: -# area *= convert[unit] -# except: -# raise H3ValueError('Unknown unit: {}'.format(unit)) + # todo: multiple units + convert = { + 'km^2': 1.0, + 'm^2': 1000*1000.0 + } -# return area + try: + area *= convert[unit] + except: + raise H3ValueError('Unknown unit: {}'.format(unit)) + + return area -# cpdef double cell_area(H3int h, unit='km^2') except -1: -# check_cell(h) +cpdef double cell_area(H3int h, unit='km^2') except -1: + cdef: + h3lib.H3Error err + double area -# if unit == 'rads^2': -# area = h3lib.cellAreaRads2(h) -# elif unit == 'km^2': -# area = h3lib.cellAreaKm2(h) -# elif unit == 'm^2': -# area = h3lib.cellAreaM2(h) -# else: -# raise H3ValueError('Unknown unit: {}'.format(unit)) + check_cell(h) -# return area + if unit == 'rads^2': + err = h3lib.cellAreaRads2(h, &area) + elif unit == 'km^2': + err = h3lib.cellAreaKm2(h, &area) + elif unit == 'm^2': + err = h3lib.cellAreaM2(h, &area) + else: + raise H3ValueError('Unknown unit: {}'.format(unit)) + + return area -# cpdef H3int[:] line(H3int start, H3int end): -# check_cell(start) -# check_cell(end) +cpdef H3int[:] line(H3int start, H3int end): + cdef: + h3lib.H3Error err + int64_t n -# n = h3lib.h3LineSize(start, end) + check_cell(start) + check_cell(end) -# if n < 0: -# s = "Couldn't find line between cells {} and {}" -# s = s.format(hex(start), hex(end)) -# raise H3ValueError(s) + err = h3lib.gridPathCellsSize(start, end, &n) -# ptr = create_ptr(n) -# flag = h3lib.h3Line(start, end, ptr) -# mv = create_mv(ptr, n) + if err: + s = "Couldn't find line between cells {} and {}" + s = s.format(hex(start), hex(end)) + raise H3ValueError(s) -# if flag != 0: -# s = "Couldn't find line between cells {} and {}" -# s = s.format(hex(start), hex(end)) -# raise H3ValueError(s) + ptr = create_ptr(n) + err = h3lib.gridPathCells(start, end, ptr) + mv = create_mv(ptr, n) -# return mv + if err: + s = "Couldn't find line between cells {} and {}" + s = s.format(hex(start), hex(end)) + raise H3ValueError(s) + + return mv cpdef bool is_res_class_iii(H3int h): return h3lib.isResClassIII(h) == 1 -# cpdef H3int[:] get_pentagon_indexes(int res): -# check_res(res) +cpdef H3int[:] get_pentagon_indexes(int res): + cdef: + h3lib.H3Error err -# n = h3lib.pentagonIndexCount() + check_res(res) -# ptr = create_ptr(n) -# h3lib.getPentagonIndexes(res, ptr) -# mv = create_mv(ptr, n) + n = h3lib.pentagonCount() -# return mv + ptr = create_ptr(n) + err = h3lib.getPentagons(res, ptr) + mv = create_mv(ptr, n) + + return mv -# cpdef H3int[:] get_res0_indexes(): -# n = h3lib.res0IndexCount() +cpdef H3int[:] get_res0_indexes(): + cdef: + h3lib.H3Error err -# ptr = create_ptr(n) -# h3lib.getRes0Indexes(ptr) -# mv = create_mv(ptr, n) + n = h3lib.res0CellCount() -# return mv + ptr = create_ptr(n) + err = h3lib.getRes0Cells(ptr) + mv = create_mv(ptr, n) + return mv # cpdef get_faces(H3int h): # check_cell(h) diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index 633af81..2061b43 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -60,7 +60,21 @@ cdef extern from "h3api.h": const int res ) nogil - H3Error getNumCells(int res, int64_t *out) + H3Error getNumCells(int res, int64_t *out) nogil + int pentagonCount() nogil + int res0CellCount() nogil + H3Error getPentagons(int res, H3Index *out) nogil + H3Error getRes0Cells(H3Index *out) nogil + + H3Error gridPathCellsSize(H3Index start, H3Index end, int64_t *size) nogil + H3Error gridPathCells(H3Index start, H3Index end, H3Index *out) nogil + + H3Error getHexagonAreaAvgKm2(int res, double *out) nogil + H3Error getHexagonAreaAvgM2(int res, double *out) nogil + + H3Error cellAreaRads2(H3Index h, double *out) nogil + H3Error cellAreaKm2(H3Index h, double *out) nogil + H3Error cellAreaM2(H3Index h, double *out) nogil # ctypedef struct GeoBoundary: # int num_verts "numVerts" @@ -122,14 +136,6 @@ cdef extern from "h3api.h": # void h3ToString(H3Index h, char *str, size_t sz) - # int pentagonIndexCount() - - # void getPentagonIndexes(int res, H3Index *out) - - # int res0IndexCount() - - # void getRes0Indexes(H3Index *out) - # int h3IndexesAreNeighbors(H3Index origin, H3Index destination) # H3Index getH3UnidirectionalEdge(H3Index origin, H3Index destination) @@ -144,22 +150,12 @@ cdef extern from "h3api.h": # void getH3UnidirectionalEdgeBoundary(H3Index edge, GeoBoundary *gb) - # int h3LineSize(H3Index start, H3Index end) - # int h3Line(H3Index start, H3Index end, H3Index *out) - # int maxFaceCount(H3Index h3) # void h3GetFaces(H3Index h3, int *out) # int experimentalH3ToLocalIj(H3Index origin, H3Index h3, CoordIJ *out) # int experimentalLocalIjToH3(H3Index origin, const CoordIJ *ij, H3Index *out) - # double hexAreaKm2(int res) nogil - # double hexAreaM2(int res) nogil - - # double cellAreaRads2(H3Index h) nogil - # double cellAreaKm2(H3Index h) nogil - # double cellAreaM2(H3Index h) nogil - # double edgeLengthKm(int res) nogil # double edgeLengthM(int res) nogil diff --git a/tests/test_cells_and_edges.py b/tests/test_cells_and_edges.py index 014f519..851dda5 100644 --- a/tests/test_cells_and_edges.py +++ b/tests/test_cells_and_edges.py @@ -269,11 +269,11 @@ def test_num_hexagons(): def test_hex_area(): expected_in_km2 = { - 0: 4250546.848, - 1: 607220.9782, - 2: 86745.85403, - 9: 0.1053325, - 15: 9e-07, + 0: 4357449.416078381, + 1: 609788.441794133, + 2: 86801.780398997, + 9: 0.105332513, + 15: 8.95311e-07, } out = { From f2253cfb30e8b3925f0b3df29e176c8508884a5a Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Wed, 25 May 2022 11:14:55 -0700 Subject: [PATCH 003/177] get_faces (#248) * initial pass * thoughts * the results of thinking * this commit is associated with the previous commits * nogil * i'm a bill * remove the typical nonsense --- src/h3/_cy/__init__.py | 3 ++- src/h3/_cy/cells.pxd | 2 +- src/h3/_cy/cells.pyx | 26 +++++++++++++++----------- src/h3/_cy/h3lib.pxd | 6 +++--- 4 files changed, 21 insertions(+), 16 deletions(-) diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index cfe34c7..d8460bf 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -32,6 +32,7 @@ from .cells import ( line, mean_hex_area, cell_area, + get_faces, ) from h3fake2._cy import ( @@ -54,7 +55,7 @@ from h3fake2._cy import ( # get_pentagon_indexes, # get_res0_indexes, # center_child, - get_faces, + # get_faces, experimental_h3_to_local_ij, experimental_local_ij_to_h3, ) diff --git a/src/h3/_cy/cells.pxd b/src/h3/_cy/cells.pxd index 0dd3aa6..8ca4313 100644 --- a/src/h3/_cy/cells.pxd +++ b/src/h3/_cy/cells.pxd @@ -20,6 +20,6 @@ cpdef H3int[:] line(H3int start, H3int end) cpdef bool is_res_class_iii(H3int h) cpdef H3int[:] get_pentagon_indexes(int res) cpdef H3int[:] get_res0_indexes() -# cpdef get_faces(H3int h) +cpdef get_faces(H3int h) # cpdef (int, int) experimental_h3_to_local_ij(H3int origin, H3int h) except * # cpdef H3int experimental_local_ij_to_h3(H3int origin, int i, int j) except 0 diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 9cfcbb2..fdc2e7e 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -380,22 +380,26 @@ cpdef H3int[:] get_res0_indexes(): return mv -# cpdef get_faces(H3int h): -# check_cell(h) +cpdef get_faces(H3int h): + cdef: + h3lib.H3Error err + int n -# n = h3lib.maxFaceCount(h) + check_cell(h) -# cdef int* ptr = stdlib.calloc(n, sizeof(int)) -# if (n > 0) and (not ptr): -# raise MemoryError() + err = h3lib.maxFaceCount(h, &n) #ignore error for now -# h3lib.h3GetFaces(h, ptr) + cdef int* ptr = stdlib.calloc(n, sizeof(int)) + if (n > 0) and (not ptr): + raise MemoryError() -# faces = ptr -# faces = {f for f in faces if f >= 0} -# stdlib.free(ptr) + err = h3lib.getIcosahedronFaces(h, ptr) # handle error? -# return faces + faces = ptr + faces = {f for f in faces if f >= 0} + stdlib.free(ptr) + + return faces # cpdef (int, int) experimental_h3_to_local_ij(H3int origin, H3int h) except *: diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index 2061b43..a5aeb77 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -76,6 +76,9 @@ cdef extern from "h3api.h": H3Error cellAreaKm2(H3Index h, double *out) nogil H3Error cellAreaM2(H3Index h, double *out) nogil + H3Error maxFaceCount(H3Index h, int *out) nogil + H3Error getIcosahedronFaces(H3Index h3, int *out) nogil + # ctypedef struct GeoBoundary: # int num_verts "numVerts" # GeoCoord verts[10] # MAX_CELL_BNDRY_VERTS @@ -150,9 +153,6 @@ cdef extern from "h3api.h": # void getH3UnidirectionalEdgeBoundary(H3Index edge, GeoBoundary *gb) - # int maxFaceCount(H3Index h3) - # void h3GetFaces(H3Index h3, int *out) - # int experimentalH3ToLocalIj(H3Index origin, H3Index h3, CoordIJ *out) # int experimentalLocalIjToH3(H3Index origin, const CoordIJ *ij, H3Index *out) From 7abaf49b195cea067e10e982b255d7996bc6ba53 Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Wed, 25 May 2022 17:09:36 -0700 Subject: [PATCH 004/177] v4: local ij functions to v4 cython (#240) * move local ij functions to v4 implementation * revert some changes and add gridPathCells * swap implementation * revert gridPathCells --- src/h3/_cy/__init__.py | 6 +++-- src/h3/_cy/cells.pxd | 4 ++-- src/h3/_cy/cells.pyx | 51 +++++++++++++++++++++--------------------- src/h3/_cy/h3lib.pxd | 23 +++++++++---------- 4 files changed, 42 insertions(+), 42 deletions(-) diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index d8460bf..d378be8 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -33,6 +33,8 @@ from .cells import ( mean_hex_area, cell_area, get_faces, + experimental_h3_to_local_ij, + experimental_local_ij_to_h3, ) from h3fake2._cy import ( @@ -56,8 +58,8 @@ from h3fake2._cy import ( # get_res0_indexes, # center_child, # get_faces, - experimental_h3_to_local_ij, - experimental_local_ij_to_h3, + # experimental_h3_to_local_ij, + # experimental_local_ij_to_h3, ) # from .edges import ( diff --git a/src/h3/_cy/cells.pxd b/src/h3/_cy/cells.pxd index 8ca4313..ee6c2a7 100644 --- a/src/h3/_cy/cells.pxd +++ b/src/h3/_cy/cells.pxd @@ -21,5 +21,5 @@ cpdef bool is_res_class_iii(H3int h) cpdef H3int[:] get_pentagon_indexes(int res) cpdef H3int[:] get_res0_indexes() cpdef get_faces(H3int h) -# cpdef (int, int) experimental_h3_to_local_ij(H3int origin, H3int h) except * -# cpdef H3int experimental_local_ij_to_h3(H3int origin, int i, int j) except 0 +cpdef (int, int) experimental_h3_to_local_ij(H3int origin, H3int h) except * +cpdef H3int experimental_local_ij_to_h3(H3int origin, int i, int j) except 0 diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index fdc2e7e..0bd99bd 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -402,39 +402,38 @@ cpdef get_faces(H3int h): return faces -# cpdef (int, int) experimental_h3_to_local_ij(H3int origin, H3int h) except *: -# cdef: -# int flag -# h3lib.CoordIJ c +cpdef (int, int) experimental_h3_to_local_ij(H3int origin, H3int h) except *: + cdef: + int flag + h3lib.CoordIJ c -# check_cell(origin) -# check_cell(h) + check_cell(origin) + check_cell(h) -# flag = h3lib.experimentalH3ToLocalIj(origin, h, &c) + flag = h3lib.cellToLocalIj(origin, h, 0, &c) -# if flag != 0: -# s = "Couldn't find local (i,j) between cells {} and {}." -# s = s.format(hex(origin), hex(h)) -# raise H3ValueError(s) + if flag != 0: + s = "Couldn't find local (i,j) between cells {} and {}." + s = s.format(hex(origin), hex(h)) + raise H3ValueError(s) -# return c.i, c.j + return c.i, c.j +cpdef H3int experimental_local_ij_to_h3(H3int origin, int i, int j) except 0: + cdef: + int flag + h3lib.CoordIJ c + H3int out -# cpdef H3int experimental_local_ij_to_h3(H3int origin, int i, int j) except 0: -# cdef: -# int flag -# h3lib.CoordIJ c -# H3int out + check_cell(origin) -# check_cell(origin) + c.i, c.j = i, j -# c.i, c.j = i, j + flag = h3lib.localIjToCell(origin, &c, 0, &out) -# flag = h3lib.experimentalLocalIjToH3(origin, &c, &out) + if flag != 0: + s = "Couldn't find cell at local ({},{}) from cell {}." + s = s.format(i, j, hex(origin)) + raise H3ValueError(s) -# if flag != 0: -# s = "Couldn't find cell at local ({},{}) from cell {}." -# s = s.format(i, j, hex(origin)) -# raise H3ValueError(s) - -# return out + return out diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index a5aeb77..05013b9 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -1,9 +1,8 @@ -from libc cimport stdint from cpython cimport bool -from libc.stdint cimport int64_t +from libc.stdint cimport uint64_t, int64_t, uint32_t -ctypedef stdint.uint64_t H3int -ctypedef stdint.uint32_t H3Error +ctypedef uint64_t H3int +ctypedef uint32_t H3Error ctypedef basestring H3str cdef extern from "h3api.h": @@ -11,12 +10,16 @@ cdef extern from "h3api.h": cdef int H3_VERSION_MINOR cdef int H3_VERSION_PATCH - ctypedef stdint.uint64_t H3Index + ctypedef uint64_t H3Index ctypedef struct LatLng: double lat # in radians double lng # in radians + ctypedef struct CoordIJ: + int i + int j + int isValidCell(H3Index h) nogil int isPentagon(H3Index h) nogil int isResClassIII(H3Index h) nogil @@ -79,6 +82,9 @@ cdef extern from "h3api.h": H3Error maxFaceCount(H3Index h, int *out) nogil H3Error getIcosahedronFaces(H3Index h3, int *out) nogil + H3Error cellToLocalIj(H3Index origin, H3Index h3, uint32_t mode, CoordIJ *out) nogil + H3Error localIjToCell(H3Index origin, const CoordIJ *ij, uint32_t mode, H3Index *out) nogil + # ctypedef struct GeoBoundary: # int num_verts "numVerts" # GeoCoord verts[10] # MAX_CELL_BNDRY_VERTS @@ -111,10 +117,6 @@ cdef extern from "h3api.h": # LinkedGeoLoop *_data_last "last" # not needed in Cython bindings # LinkedGeoPolygon *next - # ctypedef struct CoordIJ: - # int i - # int j - # void h3ToGeoBoundary(H3Index h3, GeoBoundary *gp) # int hexRange(H3Index origin, int k, H3Index *out) @@ -153,9 +155,6 @@ cdef extern from "h3api.h": # void getH3UnidirectionalEdgeBoundary(H3Index edge, GeoBoundary *gb) - # int experimentalH3ToLocalIj(H3Index origin, H3Index h3, CoordIJ *out) - # int experimentalLocalIjToH3(H3Index origin, const CoordIJ *ij, H3Index *out) - # double edgeLengthKm(int res) nogil # double edgeLengthM(int res) nogil From 610d648bfee25e55b96133f1038bffc0e81bff62 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Wed, 25 May 2022 21:45:26 -0700 Subject: [PATCH 005/177] ring (#251) --- src/h3/_cy/__init__.py | 38 ++++--------------- src/h3/_cy/cells.pxd | 4 +- src/h3/_cy/cells.pyx | 86 ++++++++++++++++++++++-------------------- src/h3/_cy/h3lib.pxd | 7 ++-- 4 files changed, 58 insertions(+), 77 deletions(-) diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index d378be8..6bce5bf 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -18,50 +18,26 @@ from .cells import ( is_pentagon, get_base_cell, resolution, - is_res_class_iii, + parent, distance, disk, - parent, + ring, children, - center_child, compact, uncompact, num_hexagons, - get_pentagon_indexes, - get_res0_indexes, - line, mean_hex_area, cell_area, + line, + is_res_class_iii, + get_pentagon_indexes, + get_res0_indexes, + center_child, get_faces, experimental_h3_to_local_ij, experimental_local_ij_to_h3, ) -from h3fake2._cy import ( - # is_cell, - # is_pentagon, - # get_base_cell, - # resolution, - # parent, - # distance, - # disk, - ring, - # children, - # compact, - # uncompact, - # num_hexagons, - # mean_hex_area, - # cell_area, - # line, - # is_res_class_iii, - # get_pentagon_indexes, - # get_res0_indexes, - # center_child, - # get_faces, - # experimental_h3_to_local_ij, - # experimental_local_ij_to_h3, -) - # from .edges import ( from h3fake2._cy import ( are_neighbors, diff --git a/src/h3/_cy/cells.pxd b/src/h3/_cy/cells.pxd index ee6c2a7..1071938 100644 --- a/src/h3/_cy/cells.pxd +++ b/src/h3/_cy/cells.pxd @@ -6,8 +6,8 @@ cpdef int get_base_cell(H3int h) except -1 cpdef int resolution(H3int h) except -1 cpdef int distance(H3int h1, H3int h2) except -1 cpdef H3int[:] disk(H3int h, int k) -# cpdef H3int[:] _ring_fallback(H3int h, int k) -# cpdef H3int[:] ring(H3int h, int k) +cpdef H3int[:] _ring_fallback(H3int h, int k) +cpdef H3int[:] ring(H3int h, int k) cpdef H3int parent(H3int h, res=*) except 0 cpdef H3int[:] children(H3int h, res=*) cpdef H3int center_child(H3int h, res=*) except 0 diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 0bd99bd..4453e38 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -85,61 +85,67 @@ cpdef H3int[:] disk(H3int h, int k): return mv -# cpdef H3int[:] _ring_fallback(H3int h, int k): -# """ -# `ring` tries to call `h3lib.hexRing` first; if that fails, we call -# this function, which relies on `h3lib.kRingDistances`. +cpdef H3int[:] _ring_fallback(H3int h, int k): + """ + `ring` tries to call `h3lib.hexRing` first; if that fails, we call + this function, which relies on `h3lib.kRingDistances`. -# Failures for `h3lib.hexRing` happen when the algortihm runs into a pentagon. -# """ -# check_cell(h) -# check_distance(k) + Failures for `h3lib.hexRing` happen when the algortihm runs into a pentagon. + """ + cdef: + int64_t n + h3lib.H3Error err -# n = h3lib.maxKringSize(k) -# # array of h3 cells -# ptr = create_ptr(n) + check_cell(h) + check_distance(k) -# # array of cell distances from `h` -# dist_ptr = stdlib.calloc(n, sizeof(int)) -# if dist_ptr is NULL: -# raise MemoryError() + err = h3lib.maxGridDiskSize(k, &n) + # array of h3 cells + ptr = create_ptr(n) -# h3lib.kRingDistances(h, k, ptr, dist_ptr) + # array of cell distances from `h` + dist_ptr = stdlib.calloc(n, sizeof(int)) + if dist_ptr is NULL: + raise MemoryError() -# distances = dist_ptr -# distances.callback_free_data = stdlib.free + err = h3lib.gridDiskDistances(h, k, ptr, dist_ptr) -# for i,v in enumerate(distances): -# if v != k: -# ptr[i] = 0 + distances = dist_ptr + distances.callback_free_data = stdlib.free -# mv = create_mv(ptr, n) + for i,v in enumerate(distances): + if v != k: + ptr[i] = 0 -# return mv + mv = create_mv(ptr, n) -# cpdef H3int[:] ring(H3int h, int k): -# """ Return cells at grid distance `== k` from `h`. -# Collection is "hollow" for k >= 1. -# """ -# check_cell(h) -# check_distance(k) + return mv -# n = 6*k if k > 0 else 1 -# ptr = create_ptr(n) +cpdef H3int[:] ring(H3int h, int k): + """ Return cells at grid distance `== k` from `h`. + Collection is "hollow" for k >= 1. + """ + cdef: + h3lib.H3Error err -# flag = h3lib.hexRing(h, k, ptr) + check_cell(h) + check_distance(k) -# # if we drop into the failure state, we might be tempted to not create -# # this mv, but creating the mv is exactly what guarantees that we'll free -# # the memory. context manager would be better here, if we can figure out -# # how to do that -# mv = create_mv(ptr, n) + n = 6*k if k > 0 else 1 + ptr = create_ptr(n) -# if flag != 0: -# mv = _ring_fallback(h, k) + err = h3lib.gridRingUnsafe(h, k, ptr) -# return mv + # if we drop into the failure state, we might be tempted to not create + # this mv, but creating the mv is exactly what guarantees that we'll free + # the memory. context manager would be better here, if we can figure out + # how to do that + mv = create_mv(ptr, n) + if err: + mv = _ring_fallback(h, k) + + return mv cpdef H3int parent(H3int h, res=None) except 0: cdef: diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index 05013b9..aa84b2b 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -85,6 +85,9 @@ cdef extern from "h3api.h": H3Error cellToLocalIj(H3Index origin, H3Index h3, uint32_t mode, CoordIJ *out) nogil H3Error localIjToCell(H3Index origin, const CoordIJ *ij, uint32_t mode, H3Index *out) nogil + H3Error gridDiskDistances(H3Index origin, int k, H3Index *out, int *distances) nogil + H3Error gridRingUnsafe(H3Index origin, int k, H3Index *out) nogil + # ctypedef struct GeoBoundary: # int num_verts "numVerts" # GeoCoord verts[10] # MAX_CELL_BNDRY_VERTS @@ -125,10 +128,6 @@ cdef extern from "h3api.h": # int hexRanges(H3Index *h3Set, int length, int k, H3Index *out) - # void kRingDistances(H3Index origin, int k, H3Index *out, int *distances) - - # int hexRing(H3Index origin, int k, H3Index *out) - # int maxPolyfillSize(const GeoPolygon *geoPolygon, int res) # void polyfill(const GeoPolygon *geoPolygon, int res, H3Index *out) From 51e73fe01b38ae53289d49d692e233e6b16eba3b Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 26 May 2022 14:15:35 -0400 Subject: [PATCH 006/177] Uncomment cython example, and exclude sdist from wheels test temporarilty (#252) * uncomment cython test * exclude make_sdist temporarily from the wheels tests --- .github/workflows/wheels.yml | 3 ++- tests/cython_example.pyx | 28 ++++++++++++------------- tests/test_cython.py | 40 ++++++++++++++++++------------------ 3 files changed, 36 insertions(+), 35 deletions(-) diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 71f47d5..dd6bfbc 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -168,7 +168,8 @@ jobs: path: wheelhouse/*.whl upload_all: - needs: [make_sdist, make_cibw_v1_wheels, make_cibw_v2_wheels] + # needs: [make_sdist, make_cibw_v1_wheels, make_cibw_v2_wheels] + needs: [make_cibw_v1_wheels, make_cibw_v2_wheels] runs-on: ubuntu-latest if: github.event_name == 'release' && github.event.action == 'published' diff --git a/tests/cython_example.pyx b/tests/cython_example.pyx index c19fe21..e8d2859 100644 --- a/tests/cython_example.pyx +++ b/tests/cython_example.pyx @@ -1,18 +1,18 @@ -# from cython cimport boundscheck, wraparound +from cython cimport boundscheck, wraparound -# from h3._cy.h3lib cimport H3int -# from h3._cy.geo cimport geo_to_h3 +from h3._cy.h3lib cimport H3int +from h3._cy.geo cimport geo_to_h3 -# @boundscheck(False) -# @wraparound(False) -# cpdef void geo_to_h3_vect( -# const double[:] lat, -# const double[:] lng, -# int res, -# H3int[:] out -# ): +@boundscheck(False) +@wraparound(False) +cpdef void geo_to_h3_vect( + const double[:] lat, + const double[:] lng, + int res, + H3int[:] out +): -# cdef Py_ssize_t i + cdef Py_ssize_t i -# for i in range(len(lat)): -# out[i] = geo_to_h3(lat[i], lng[i], res) + for i in range(len(lat)): + out[i] = geo_to_h3(lat[i], lng[i], res) diff --git a/tests/test_cython.py b/tests/test_cython.py index 0acf307..30566b1 100644 --- a/tests/test_cython.py +++ b/tests/test_cython.py @@ -1,28 +1,28 @@ -# import numpy as np +import numpy as np -# # Avoid checking for import-error here because cython_example may not have -# # been compiled yet. -# try: -# from .cython_example import geo_to_h3_vect # pylint: disable=import-error -# except ImportError: -# geo_to_h3_vect = None +# Avoid checking for import-error here because cython_example may not have +# been compiled yet. +try: + from .cython_example import geo_to_h3_vect # pylint: disable=import-error +except ImportError: + geo_to_h3_vect = None -# np.random.seed(0) +np.random.seed(0) -# def test_cython_api(): -# if geo_to_h3_vect is None: -# print("Not running Cython test because cython example was not compiled") -# return +def test_cython_api(): + if geo_to_h3_vect is None: + print("Not running Cython test because cython example was not compiled") + return -# N = 100000 + N = 100000 -# lats, lngs = np.random.uniform(0, 90, N), np.random.uniform(0, 90, N) -# res = 9 + lats, lngs = np.random.uniform(0, 90, N), np.random.uniform(0, 90, N) + res = 9 -# lats = np.array(lats, dtype=np.float64) -# lngs = np.array(lngs, dtype=np.float64) -# out = np.zeros(len(lats), dtype="uint64") -# geo_to_h3_vect(lats, lngs, res, out) + lats = np.array(lats, dtype=np.float64) + lngs = np.array(lngs, dtype=np.float64) + out = np.zeros(len(lats), dtype="uint64") + geo_to_h3_vect(lats, lngs, res, out) -# assert out[0] == 617284541015654399 + assert out[0] == 617284541015654399 From c5333321e92b77847685b3dbd80692e5f9d65713 Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Tue, 31 May 2022 19:01:51 -0700 Subject: [PATCH 007/177] v4: polygonToCells (#254) --- src/h3/_cy/__init__.py | 12 +- src/h3/_cy/geo.pyx | 259 +++++++++++++++++++++-------------------- src/h3/_cy/h3lib.pxd | 25 ++-- 3 files changed, 149 insertions(+), 147 deletions(-) diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index 6bce5bf..db15af6 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -54,9 +54,9 @@ from h3fake2._cy import ( from .geo import ( geo_to_h3, h3_to_geo, - # polyfill_polygon, - # polyfill_geojson, - # polyfill, + polyfill_polygon, + polyfill_geojson, + polyfill, # cell_boundary, # edge_boundary, # point_dist, @@ -65,9 +65,9 @@ from .geo import ( from h3fake2._cy import ( # geo_to_h3, # h3_to_geo, - polyfill_polygon, - polyfill_geojson, - polyfill, + # polyfill_polygon, + # polyfill_geojson, + # polyfill, cell_boundary, edge_boundary, point_dist, diff --git a/src/h3/_cy/geo.pyx b/src/h3/_cy/geo.pyx index fe6c93b..870594b 100644 --- a/src/h3/_cy/geo.pyx +++ b/src/h3/_cy/geo.pyx @@ -10,6 +10,7 @@ from .util cimport ( coord2deg, ) from libc cimport stdlib +from libc.stdint cimport uint64_t from .util import H3ValueError @@ -42,180 +43,182 @@ cpdef (double, double) h3_to_geo(H3int h) except *: return coord2deg(c) -# cdef h3lib.Geofence make_geofence(geos, bool lnglat_order=False) except *: -# """ +cdef h3lib.GeoLoop make_geoloop(geos, bool lnglat_order=False) except *: + """ -# The returned `Geofence` must be freed with a call to `free_geofence`. + The returned `GeoLoop` must be freed with a call to `free_geoloop`. -# Parameters -# ---------- -# geos : list or tuple -# GeoFence: A sequence of >= 3 (lat, lng) pairs where the last -# element may or may not be same as the first (to form a closed loop). -# The order of the pairs may be either clockwise or counterclockwise. -# lnglat_order : bool -# If True, assume coordinate pairs like (lng, lat) -# If False, assume coordinate pairs like (lat, lng) -# """ -# cdef: -# h3lib.Geofence gf + Parameters + ---------- + geos : list or tuple + GeoLoop: A sequence of >= 3 (lat, lng) pairs where the last + element may or may not be same as the first (to form a closed loop). + The order of the pairs may be either clockwise or counterclockwise. + lnglat_order : bool + If True, assume coordinate pairs like (lng, lat) + If False, assume coordinate pairs like (lat, lng) + """ + cdef: + h3lib.GeoLoop gl -# gf.numVerts = len(geos) + gl.numVerts = len(geos) -# gf.verts = stdlib.calloc(gf.numVerts, sizeof(h3lib.GeoCoord)) + gl.verts = stdlib.calloc(gl.numVerts, sizeof(h3lib.LatLng)) -# if lnglat_order: -# latlng = (g[::-1] for g in geos) -# else: -# latlng = geos + if lnglat_order: + latlng = (g[::-1] for g in geos) + else: + latlng = geos -# for i, (lat, lng) in enumerate(latlng): -# gf.verts[i] = deg2coord(lat, lng) + for i, (lat, lng) in enumerate(latlng): + gl.verts[i] = deg2coord(lat, lng) -# return gf + return gl -# cdef free_geofence(h3lib.Geofence* gf): -# stdlib.free(gf.verts) -# gf.verts = NULL +cdef free_geoloop(h3lib.GeoLoop* gl): + stdlib.free(gl.verts) + gl.verts = NULL -# cdef class GeoPolygon: -# cdef: -# h3lib.GeoPolygon gp +cdef class GeoPolygon: + cdef: + h3lib.GeoPolygon gp -# def __cinit__(self, outer, holes=None, bool lnglat_order=False): -# """ + def __cinit__(self, outer, holes=None, bool lnglat_order=False): + """ -# Parameters -# ---------- -# outer : list or tuple -# GeoFence -# A GeoFence is a sequence of >= 3 (lat, lng) pairs where the last -# element may or may not be same as the first (to form a closed loop). -# The order of the pairs may be either clockwise or counterclockwise. -# holes : list or tuple -# A sequence of GeoFences -# lnglat_order : bool -# If True, assume coordinate pairs like (lng, lat) -# If False, assume coordinate pairs like (lat, lng) + Parameters + ---------- + outer : list or tuple + GeoLoop + A GeoLoop is a sequence of >= 3 (lat, lng) pairs where the last + element may or may not be same as the first (to form a closed loop). + The order of the pairs may be either clockwise or counterclockwise. + holes : list or tuple + A sequence of GeoLoops + lnglat_order : bool + If True, assume coordinate pairs like (lng, lat) + If False, assume coordinate pairs like (lat, lng) -# """ -# if holes is None: -# holes = [] + """ + if holes is None: + holes = [] -# self.gp.geofence = make_geofence(outer, lnglat_order) -# self.gp.numHoles = len(holes) -# self.gp.holes = NULL + self.gp.geoloop = make_geoloop(outer, lnglat_order) + self.gp.numHoles = len(holes) + self.gp.holes = NULL -# if len(holes) > 0: -# self.gp.holes = stdlib.calloc(len(holes), sizeof(h3lib.Geofence)) -# for i, hole in enumerate(holes): -# self.gp.holes[i] = make_geofence(hole, lnglat_order) + if len(holes) > 0: + self.gp.holes = stdlib.calloc(len(holes), sizeof(h3lib.GeoLoop)) + for i, hole in enumerate(holes): + self.gp.holes[i] = make_geoloop(hole, lnglat_order) -# def __dealloc__(self): -# free_geofence(&self.gp.geofence) + def __dealloc__(self): + free_geoloop(&self.gp.geoloop) -# for i in range(self.gp.numHoles): -# free_geofence(&self.gp.holes[i]) + for i in range(self.gp.numHoles): + free_geoloop(&self.gp.holes[i]) -# stdlib.free(self.gp.holes) + stdlib.free(self.gp.holes) -# def polyfill_polygon(outer, int res, holes=None, bool lnglat_order=False): -# """ Set of hexagons whose center is contained in a polygon. +def polyfill_polygon(outer, int res, holes=None, bool lnglat_order=False): + """ Set of hexagons whose center is contained in a polygon. -# The polygon is defined as in the GeoJson standard, with an exterior -# LinearRing `outer` and a list of LinearRings `holes`, which define any -# holes in the polygon. + The polygon is defined as in the GeoJson standard, with an exterior + LinearRing `outer` and a list of LinearRings `holes`, which define any + holes in the polygon. -# Each LinearRing may be in clockwise or counter-clockwise order -# (right-hand rule or not), and may or may not be a closed loop (where the last -# element is equal to the first). -# The GeoJSON spec requires the right-hand rule, and a closed loop, but -# this function will work with any input format. + Each LinearRing may be in clockwise or counter-clockwise order + (right-hand rule or not), and may or may not be a closed loop (where the last + element is equal to the first). + The GeoJSON spec requires the right-hand rule, and a closed loop, but + this function will work with any input format. -# Parameters -# ---------- -# outer : list or tuple -# A LinearRing, a sequence of (lat/lng) or (lng/lat) pairs -# res : int -# The resolution of the output hexagons -# holes : list or tuple -# A collection of LinearRings, describing any holes in the polygon -# lnglat_order : bool -# If True, assume coordinate pairs like (lng, lat) -# If False, assume coordinate pairs like (lat, lng) -# """ + Parameters + ---------- + outer : list or tuple + A LinearRing, a sequence of (lat/lng) or (lng/lat) pairs + res : int + The resolution of the output hexagons + holes : list or tuple + A collection of LinearRings, describing any holes in the polygon + lnglat_order : bool + If True, assume coordinate pairs like (lng, lat) + If False, assume coordinate pairs like (lat, lng) + """ + cdef: + uint64_t n -# check_res(res) -# gp = GeoPolygon(outer, holes=holes, lnglat_order=lnglat_order) + check_res(res) + gp = GeoPolygon(outer, holes=holes, lnglat_order=lnglat_order) -# n = h3lib.maxPolyfillSize(&gp.gp, res) -# ptr = create_ptr(n) + h3lib.maxPolygonToCellsSize(&gp.gp, res, 0, &n) + ptr = create_ptr(n) -# h3lib.polyfill(&gp.gp, res, ptr) -# mv = create_mv(ptr, n) + h3lib.polygonToCells(&gp.gp, res, 0, ptr) + mv = create_mv(ptr, n) -# return mv + return mv -# def polyfill_geojson(geojson, int res): -# """ Set of hexagons whose center is contained in a GeoJson Polygon object. +def polyfill_geojson(geojson, int res): + """ Set of hexagons whose center is contained in a GeoJson Polygon object. -# The polygon is defined exactly as in the GeoJson standard, so -# `geojson` should be a dictionary like: -# { -# 'type': 'Polygon', -# 'coordinates': [...] -# } + The polygon is defined exactly as in the GeoJson standard, so + `geojson` should be a dictionary like: + { + 'type': 'Polygon', + 'coordinates': [...] + } -# 'coordinates' should be a list of LinearRings, where the first ring describes -# the exterior boundary of the Polygon, and any subsequent LinearRings -# describe holes in the polygon. + 'coordinates' should be a list of LinearRings, where the first ring describes + the exterior boundary of the Polygon, and any subsequent LinearRings + describe holes in the polygon. -# Note that we don't provide an option for the order of the coordinates, -# as the GeoJson standard requires them to be in lng/lat order. + Note that we don't provide an option for the order of the coordinates, + as the GeoJson standard requires them to be in lng/lat order. -# Parameters -# ---------- -# geojson : dict -# res : int -# The resolution of the output hexagons -# """ + Parameters + ---------- + geojson : dict + res : int + The resolution of the output hexagons + """ -# # todo: this one could handle multipolygons... + # todo: this one could handle multipolygons... -# if geojson['type'] != 'Polygon': -# raise ValueError('Only Polygon GeoJSON supported') + if geojson['type'] != 'Polygon': + raise ValueError('Only Polygon GeoJSON supported') -# coords = geojson['coordinates'] + coords = geojson['coordinates'] -# out = polyfill_polygon(coords[0], res, holes=coords[1:], lnglat_order=True) + out = polyfill_polygon(coords[0], res, holes=coords[1:], lnglat_order=True) -# return out + return out -# def polyfill(dict geojson, int res, bool geo_json_conformant=False): -# """ Light wrapper around `polyfill_geojson` to provide backward compatibility. -# """ +def polyfill(dict geojson, int res, bool geo_json_conformant=False): + """ Light wrapper around `polyfill_geojson` to provide backward compatibility. + """ -# try: -# gj_type = geojson['type'] -# except KeyError: -# raise KeyError("`geojson` dict must have key 'type'.") from None + try: + gj_type = geojson['type'] + except KeyError: + raise KeyError("`geojson` dict must have key 'type'.") from None -# if gj_type != 'Polygon': -# raise ValueError('Only Polygon GeoJSON supported') + if gj_type != 'Polygon': + raise ValueError('Only Polygon GeoJSON supported') -# if geo_json_conformant: -# out = polyfill_geojson(geojson, res) -# else: -# coords = geojson['coordinates'] -# out = polyfill_polygon(coords[0], res, holes=coords[1:], lnglat_order=False) + if geo_json_conformant: + out = polyfill_geojson(geojson, res) + else: + coords = geojson['coordinates'] + out = polyfill_polygon(coords[0], res, holes=coords[1:], lnglat_order=False) -# return out + return out # def cell_boundary(H3int h, bool geo_json=False): diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index aa84b2b..440391a 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -20,6 +20,15 @@ cdef extern from "h3api.h": int i int j + ctypedef struct GeoLoop: + int numVerts + LatLng *verts + + ctypedef struct GeoPolygon: + GeoLoop geoloop + int numHoles + GeoLoop *holes + int isValidCell(H3Index h) nogil int isPentagon(H3Index h) nogil int isResClassIII(H3Index h) nogil @@ -88,19 +97,13 @@ cdef extern from "h3api.h": H3Error gridDiskDistances(H3Index origin, int k, H3Index *out, int *distances) nogil H3Error gridRingUnsafe(H3Index origin, int k, H3Index *out) nogil + H3Error maxPolygonToCellsSize(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t *count) + H3Error polygonToCells(const GeoPolygon *geoPolygon, int res, uint32_t flags, H3Index *out) + # ctypedef struct GeoBoundary: # int num_verts "numVerts" # GeoCoord verts[10] # MAX_CELL_BNDRY_VERTS - # ctypedef struct Geofence: - # int numVerts - # GeoCoord *verts - - # ctypedef struct GeoPolygon: - # Geofence geofence - # int numHoles - # Geofence *holes - # ctypedef struct GeoMultiPolygon: # int numPolygons # GeoPolygon *polygons @@ -128,10 +131,6 @@ cdef extern from "h3api.h": # int hexRanges(H3Index *h3Set, int length, int k, H3Index *out) - # int maxPolyfillSize(const GeoPolygon *geoPolygon, int res) - - # void polyfill(const GeoPolygon *geoPolygon, int res, H3Index *out) - # void h3SetToLinkedGeo(const H3Index *h3Set, const int numHexes, LinkedGeoPolygon *out) # void destroyLinkedPolygon(LinkedGeoPolygon *polygon) From dc9c011dde04df701fe22df429e16d9980fd146b Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Wed, 1 Jun 2022 14:42:02 -0700 Subject: [PATCH 008/177] v4: geo boundary, set to multi polygon (#255) * v4: cell boundary * v4: h3_set_to_multi_polygon --- src/h3/_cy/__init__.py | 14 +---- src/h3/_cy/geo.pxd | 6 +-- src/h3/_cy/geo.pyx | 92 +++++++++++++++---------------- src/h3/_cy/h3lib.pxd | 57 ++++++++++---------- src/h3/_cy/to_multipoly.pyx | 104 ++++++++++++++++++------------------ 5 files changed, 132 insertions(+), 141 deletions(-) diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index db15af6..c684997 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -57,24 +57,12 @@ from .geo import ( polyfill_polygon, polyfill_geojson, polyfill, - # cell_boundary, - # edge_boundary, - # point_dist, -) - -from h3fake2._cy import ( - # geo_to_h3, - # h3_to_geo, - # polyfill_polygon, - # polyfill_geojson, - # polyfill, cell_boundary, edge_boundary, point_dist, ) -# from .to_multipoly import ( -from h3fake2._cy import ( +from .to_multipoly import ( h3_set_to_multi_polygon ) diff --git a/src/h3/_cy/geo.pxd b/src/h3/_cy/geo.pxd index 37e32a0..1a2c1c3 100644 --- a/src/h3/_cy/geo.pxd +++ b/src/h3/_cy/geo.pxd @@ -2,6 +2,6 @@ from .h3lib cimport H3int cpdef H3int geo_to_h3(double lat, double lng, int res) except 1 cpdef (double, double) h3_to_geo(H3int h) except * -# cpdef double point_dist( -# double lat1, double lng1, -# double lat2, double lng2, unit=*) except -1 +cpdef double point_dist( + double lat1, double lng1, + double lat2, double lng2, unit=*) except -1 diff --git a/src/h3/_cy/geo.pyx b/src/h3/_cy/geo.pyx index 870594b..7a737e2 100644 --- a/src/h3/_cy/geo.pyx +++ b/src/h3/_cy/geo.pyx @@ -221,66 +221,66 @@ def polyfill(dict geojson, int res, bool geo_json_conformant=False): return out -# def cell_boundary(H3int h, bool geo_json=False): -# """Compose an array of geo-coordinates that outlines a hexagonal cell""" -# cdef: -# h3lib.GeoBoundary gb +def cell_boundary(H3int h, bool geo_json=False): + """Compose an array of geo-coordinates that outlines a hexagonal cell""" + cdef: + h3lib.CellBoundary gb -# check_cell(h) + check_cell(h) -# h3lib.h3ToGeoBoundary(h, &gb) + h3lib.cellToBoundary(h, &gb) -# verts = tuple( -# coord2deg(gb.verts[i]) -# for i in range(gb.num_verts) -# ) + verts = tuple( + coord2deg(gb.verts[i]) + for i in range(gb.num_verts) + ) -# if geo_json: -# #lat/lng -> lng/lat and last point same as first -# verts += (verts[0],) -# verts = tuple(v[::-1] for v in verts) + if geo_json: + #lat/lng -> lng/lat and last point same as first + verts += (verts[0],) + verts = tuple(v[::-1] for v in verts) -# return verts + return verts -# def edge_boundary(H3int edge, bool geo_json=False): -# """ Returns the GeoBoundary containing the coordinates of the edge -# """ -# cdef: -# h3lib.GeoBoundary gb +def edge_boundary(H3int edge, bool geo_json=False): + """ Returns the CellBoundary containing the coordinates of the edge + """ + cdef: + h3lib.CellBoundary gb -# check_edge(edge) + check_edge(edge) -# h3lib.getH3UnidirectionalEdgeBoundary(edge, &gb) + h3lib.directedEdgeToBoundary(edge, &gb) -# # todo: move this verts transform into the GeoBoundary object -# verts = tuple( -# coord2deg(gb.verts[i]) -# for i in range(gb.num_verts) -# ) + # todo: move this verts transform into the CellBoundary object + verts = tuple( + coord2deg(gb.verts[i]) + for i in range(gb.num_verts) + ) -# if geo_json: -# #lat/lng -> lng/lat and last point same as first -# verts += (verts[0],) -# verts = tuple(v[::-1] for v in verts) + if geo_json: + #lat/lng -> lng/lat and last point same as first + verts += (verts[0],) + verts = tuple(v[::-1] for v in verts) -# return verts + return verts -# cpdef double point_dist( -# double lat1, double lng1, -# double lat2, double lng2, unit='km') except -1: +cpdef double point_dist( + double lat1, double lng1, + double lat2, double lng2, unit='km') except -1: -# a = deg2coord(lat1, lng1) -# b = deg2coord(lat2, lng2) + a = deg2coord(lat1, lng1) + b = deg2coord(lat2, lng2) -# if unit == 'rads': -# d = h3lib.pointDistRads(&a, &b) -# elif unit == 'km': -# d = h3lib.pointDistKm(&a, &b) -# elif unit == 'm': -# d = h3lib.pointDistM(&a, &b) -# else: -# raise H3ValueError('Unknown unit: {}'.format(unit)) + if unit == 'rads': + d = h3lib.distanceRads(&a, &b) + elif unit == 'km': + d = h3lib.distanceKm(&a, &b) + elif unit == 'm': + d = h3lib.distanceM(&a, &b) + else: + raise H3ValueError('Unknown unit: {}'.format(unit)) -# return d + return d diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index 440391a..c3efea8 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -16,10 +16,29 @@ cdef extern from "h3api.h": double lat # in radians double lng # in radians + ctypedef struct CellBoundary: + int num_verts "numVerts" + LatLng verts[10] # MAX_CELL_BNDRY_VERTS + ctypedef struct CoordIJ: int i int j + ctypedef struct LinkedLatLng: + LatLng data "vertex" + LinkedLatLng *next + + # renaming these for clarity + ctypedef struct LinkedGeoLoop: + LinkedLatLng *data "first" + LinkedLatLng *_data_last "last" # not needed in Cython bindings + LinkedGeoLoop *next + + ctypedef struct LinkedGeoPolygon: + LinkedGeoLoop *data "first" + LinkedGeoLoop *_data_last "last" # not needed in Cython bindings + LinkedGeoPolygon *next + ctypedef struct GeoLoop: int numVerts LatLng *verts @@ -97,34 +116,24 @@ cdef extern from "h3api.h": H3Error gridDiskDistances(H3Index origin, int k, H3Index *out, int *distances) nogil H3Error gridRingUnsafe(H3Index origin, int k, H3Index *out) nogil + H3Error cellToBoundary(H3Index h3, CellBoundary *gp) nogil + + H3Error directedEdgeToBoundary(H3Index edge, CellBoundary *gb) nogil + + double distanceRads(const LatLng *a, const LatLng *b) nogil + double distanceKm(const LatLng *a, const LatLng *b) nogil + double distanceM(const LatLng *a, const LatLng *b) nogil + + H3Error cellsToLinkedMultiPolygon(const H3Index *h3Set, const int numHexes, LinkedGeoPolygon *out) + void destroyLinkedMultiPolygon(LinkedGeoPolygon *polygon) + H3Error maxPolygonToCellsSize(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t *count) H3Error polygonToCells(const GeoPolygon *geoPolygon, int res, uint32_t flags, H3Index *out) - # ctypedef struct GeoBoundary: - # int num_verts "numVerts" - # GeoCoord verts[10] # MAX_CELL_BNDRY_VERTS - # ctypedef struct GeoMultiPolygon: # int numPolygons # GeoPolygon *polygons - # ctypedef struct LinkedGeoCoord: - # GeoCoord data "vertex" - # LinkedGeoCoord *next - - # # renaming these for clarity - # ctypedef struct LinkedGeoLoop: - # LinkedGeoCoord *data "first" - # LinkedGeoCoord *_data_last "last" # not needed in Cython bindings - # LinkedGeoLoop *next - - # ctypedef struct LinkedGeoPolygon: - # LinkedGeoLoop *data "first" - # LinkedGeoLoop *_data_last "last" # not needed in Cython bindings - # LinkedGeoPolygon *next - - # void h3ToGeoBoundary(H3Index h3, GeoBoundary *gp) - # int hexRange(H3Index origin, int k, H3Index *out) # int hexRangeDistances(H3Index origin, int k, H3Index *out, int *distances) @@ -151,15 +160,9 @@ cdef extern from "h3api.h": # void getH3UnidirectionalEdgesFromHexagon(H3Index origin, H3Index *edges) - # void getH3UnidirectionalEdgeBoundary(H3Index edge, GeoBoundary *gb) - # double edgeLengthKm(int res) nogil # double edgeLengthM(int res) nogil # double exactEdgeLengthRads(H3Index edge) nogil # double exactEdgeLengthKm(H3Index edge) nogil # double exactEdgeLengthM(H3Index edge) nogil - - # double pointDistRads(const GeoCoord *a, const GeoCoord *b) nogil - # double pointDistKm(const GeoCoord *a, const GeoCoord *b) nogil - # double pointDistM(const GeoCoord *a, const GeoCoord *b) nogil diff --git a/src/h3/_cy/to_multipoly.pyx b/src/h3/_cy/to_multipoly.pyx index 296a932..7a421f7 100644 --- a/src/h3/_cy/to_multipoly.pyx +++ b/src/h3/_cy/to_multipoly.pyx @@ -1,75 +1,75 @@ -# cimport h3lib -# from h3lib cimport H3int -# from .util cimport check_cell, coord2deg +cimport h3lib +from h3lib cimport H3int +from .util cimport check_cell, coord2deg -# # todo: it's driving me crazy that these three functions are all essentially the same linked list walker... -# # grumble: no way to do iterators in with cdef functions! -# cdef walk_polys(const h3lib.LinkedGeoPolygon* L): -# out = [] -# while L: -# out += [walk_loops(L.data)] -# L = L.next +# todo: it's driving me crazy that these three functions are all essentially the same linked list walker... +# grumble: no way to do iterators in with cdef functions! +cdef walk_polys(const h3lib.LinkedGeoPolygon* L): + out = [] + while L: + out += [walk_loops(L.data)] + L = L.next -# return out + return out -# cdef walk_loops(const h3lib.LinkedGeoLoop* L): -# out = [] -# while L: -# out += [walk_coords(L.data)] -# L = L.next +cdef walk_loops(const h3lib.LinkedGeoLoop* L): + out = [] + while L: + out += [walk_coords(L.data)] + L = L.next -# return out + return out -# cdef walk_coords(const h3lib.LinkedGeoCoord* L): -# out = [] -# while L: -# out += [coord2deg(L.data)] -# L = L.next +cdef walk_coords(const h3lib.LinkedLatLng* L): + out = [] + while L: + out += [coord2deg(L.data)] + L = L.next -# return out + return out -# # todo: tuples instead of lists? -# def _to_multi_polygon(const H3int[:] hexes): -# cdef: -# h3lib.LinkedGeoPolygon polygon +# todo: tuples instead of lists? +def _to_multi_polygon(const H3int[:] hexes): + cdef: + h3lib.LinkedGeoPolygon polygon -# for h in hexes: -# check_cell(h) + for h in hexes: + check_cell(h) -# h3lib.h3SetToLinkedGeo(&hexes[0], len(hexes), &polygon) + h3lib.cellsToLinkedMultiPolygon(&hexes[0], len(hexes), &polygon) -# out = walk_polys(&polygon) + out = walk_polys(&polygon) -# # we're still responsible for cleaning up the passed in `polygon`, -# # but not a problem here, since it is stack allocated -# h3lib.destroyLinkedPolygon(&polygon) + # we're still responsible for cleaning up the passed in `polygon`, + # but not a problem here, since it is stack allocated + h3lib.destroyLinkedMultiPolygon(&polygon) -# return out + return out -# def _geojson_loop(loop): -# """ Swap lat/lng order and close loop. -# """ -# loop = [e[::-1] for e in loop] -# loop += [loop[0]] +def _geojson_loop(loop): + """ Swap lat/lng order and close loop. + """ + loop = [e[::-1] for e in loop] + loop += [loop[0]] -# return loop + return loop -# def h3_set_to_multi_polygon(const H3int[:] hexes, geo_json=False): -# # todo: gotta be a more elegant way to handle these... -# if len(hexes) == 0: -# return [] +def h3_set_to_multi_polygon(const H3int[:] hexes, geo_json=False): + # todo: gotta be a more elegant way to handle these... + if len(hexes) == 0: + return [] -# multipoly = _to_multi_polygon(hexes) + multipoly = _to_multi_polygon(hexes) -# if geo_json: -# multipoly = [ -# [_geojson_loop(loop) for loop in poly] -# for poly in multipoly -# ] + if geo_json: + multipoly = [ + [_geojson_loop(loop) for loop in poly] + for poly in multipoly + ] -# return multipoly + return multipoly From 75fb4c7046a3b14bf6b413dc6a0709579189c1e9 Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Thu, 2 Jun 2022 15:44:24 -0700 Subject: [PATCH 009/177] v4: convert edge from h3fake2 (#253) * v4: convert edge from h3fake2 * on error not neighbors * except * * check for neighbor error --- src/h3/_cy/__init__.py | 3 +- src/h3/_cy/edges.pxd | 20 ++--- src/h3/_cy/edges.pyx | 165 ++++++++++++++++++++++++----------------- src/h3/_cy/h3lib.pxd | 31 ++++---- 4 files changed, 119 insertions(+), 100 deletions(-) diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index c684997..bb4dfc0 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -38,8 +38,7 @@ from .cells import ( experimental_local_ij_to_h3, ) -# from .edges import ( -from h3fake2._cy import ( +from .edges import ( are_neighbors, edge, is_edge, diff --git a/src/h3/_cy/edges.pxd b/src/h3/_cy/edges.pxd index cdcf4d0..bf4c5c4 100644 --- a/src/h3/_cy/edges.pxd +++ b/src/h3/_cy/edges.pxd @@ -1,11 +1,11 @@ -# from .h3lib cimport bool, H3int +from .h3lib cimport bool, H3int -# cpdef bool are_neighbors(H3int h1, H3int h2) -# cpdef H3int edge(H3int origin, H3int destination) except 1 -# cpdef bool is_edge(H3int e) -# cpdef H3int edge_origin(H3int e) except 1 -# cpdef H3int edge_destination(H3int e) except 1 -# cpdef (H3int, H3int) edge_cells(H3int e) except * -# cpdef H3int[:] edges_from_cell(H3int origin) -# cpdef double mean_edge_length(int resolution, unit=*) except -1 -# cpdef double edge_length(H3int e, unit=*) except -1 +cpdef bool are_neighbors(H3int h1, H3int h2) +cpdef H3int edge(H3int origin, H3int destination) except * +cpdef bool is_edge(H3int e) +cpdef H3int edge_origin(H3int e) except 1 +cpdef H3int edge_destination(H3int e) except 1 +cpdef (H3int, H3int) edge_cells(H3int e) except * +cpdef H3int[:] edges_from_cell(H3int origin) +cpdef double mean_edge_length(int resolution, unit=*) except -1 +cpdef double edge_length(H3int e, unit=*) except -1 diff --git a/src/h3/_cy/edges.pyx b/src/h3/_cy/edges.pyx index 27397d9..716c96a 100644 --- a/src/h3/_cy/edges.pyx +++ b/src/h3/_cy/edges.pyx @@ -1,100 +1,125 @@ -# cimport h3lib -# from .h3lib cimport bool, H3int +cimport h3lib +from .h3lib cimport bool, H3int -# from .util cimport ( -# check_cell, -# check_edge, -# check_res, -# create_ptr, -# create_mv, -# ) +from .util cimport ( + check_cell, + check_edge, + check_res, + create_ptr, + create_mv, +) -# from .util import H3ValueError +from .util import H3ValueError -# cpdef bool are_neighbors(H3int h1, H3int h2): -# check_cell(h1) -# check_cell(h2) +cpdef bool are_neighbors(H3int h1, H3int h2): + cdef: + int out -# return h3lib.h3IndexesAreNeighbors(h1, h2) == 1 + check_cell(h1) + check_cell(h2) + + error = h3lib.areNeighborCells(h1, h2, &out) + if error != 0: + return False + return out == 1 -# cpdef H3int edge(H3int origin, H3int destination) except 1: -# check_cell(origin) -# check_cell(destination) +cpdef H3int edge(H3int origin, H3int destination) except *: + cdef: + int neighbor_out + H3int out -# if h3lib.h3IndexesAreNeighbors(origin, destination) != 1: -# s = 'Cells are not neighbors: {} and {}' -# s = s.format(hex(origin), hex(destination)) -# raise H3ValueError(s) + check_cell(origin) + check_cell(destination) -# return h3lib.getH3UnidirectionalEdge(origin, destination) + error = h3lib.areNeighborCells(origin, destination, &neighbor_out) + if error != 0 or neighbor_out != 1: + s = 'Cells are not neighbors: {} and {}' + s = s.format(hex(origin), hex(destination)) + raise H3ValueError(s) + + h3lib.cellsToDirectedEdge(origin, destination, &out) + return out -# cpdef bool is_edge(H3int e): -# return h3lib.h3UnidirectionalEdgeIsValid(e) == 1 +cpdef bool is_edge(H3int e): + return h3lib.isValidDirectedEdge(e) == 1 -# cpdef H3int edge_origin(H3int e) except 1: -# # without the check, with an invalid input, the function will just return 0 -# check_edge(e) +cpdef H3int edge_origin(H3int e) except 1: + cdef: + H3int out -# return h3lib.getOriginH3IndexFromUnidirectionalEdge(e) + # without the check, with an invalid input, the function will just return 0 + check_edge(e) -# cpdef H3int edge_destination(H3int e) except 1: -# check_edge(e) + h3lib.getDirectedEdgeOrigin(e, &out) + return out -# return h3lib.getDestinationH3IndexFromUnidirectionalEdge(e) +cpdef H3int edge_destination(H3int e) except 1: + cdef: + H3int out -# cpdef (H3int, H3int) edge_cells(H3int e) except *: -# check_edge(e) + check_edge(e) -# return edge_origin(e), edge_destination(e) + h3lib.getDirectedEdgeDestination(e, &out) + return out -# cpdef H3int[:] edges_from_cell(H3int origin): -# """ Returns the 6 (or 5 for pentagons) directed edges -# for the given origin cell -# """ -# check_cell(origin) +cpdef (H3int, H3int) edge_cells(H3int e) except *: + check_edge(e) -# ptr = create_ptr(6) -# h3lib.getH3UnidirectionalEdgesFromHexagon(origin, ptr) -# mv = create_mv(ptr, 6) + return edge_origin(e), edge_destination(e) -# return mv +cpdef H3int[:] edges_from_cell(H3int origin): + """ Returns the 6 (or 5 for pentagons) directed edges + for the given origin cell + """ + check_cell(origin) + + ptr = create_ptr(6) + h3lib.originToDirectedEdges(origin, ptr) + mv = create_mv(ptr, 6) + + return mv -# cpdef double mean_edge_length(int resolution, unit='km') except -1: -# check_res(resolution) +cpdef double mean_edge_length(int resolution, unit='km') except -1: + cdef: + double length -# length = h3lib.edgeLengthKm(resolution) + check_res(resolution) -# # todo: multiple units -# convert = { -# 'km': 1.0, -# 'm': 1000.0 -# } + h3lib.getHexagonEdgeLengthAvgKm(resolution, &length) -# try: -# length *= convert[unit] -# except: -# raise H3ValueError('Unknown unit: {}'.format(unit)) + # todo: multiple units + convert = { + 'km': 1.0, + 'm': 1000.0 + } -# return length + try: + length *= convert[unit] + except: + raise H3ValueError('Unknown unit: {}'.format(unit)) + + return length -# cpdef double edge_length(H3int e, unit='km') except -1: -# check_edge(e) +cpdef double edge_length(H3int e, unit='km') except -1: + cdef: + double length + check_edge(e) -# # todo: maybe kick this logic up to the python level -# # it might be a little cleaner, because we can do the "switch statement" -# # with a dict, but would require exposing more C functions + # todo: maybe kick this logic up to the python level + # it might be a little cleaner, because we can do the "switch statement" + # with a dict, but would require exposing more C functions -# if unit == 'rads': -# length = h3lib.exactEdgeLengthRads(e) -# elif unit == 'km': -# length = h3lib.exactEdgeLengthKm(e) -# elif unit == 'm': -# length = h3lib.exactEdgeLengthM(e) -# else: -# raise H3ValueError('Unknown unit: {}'.format(unit)) + if unit == 'rads': + h3lib.exactEdgeLengthRads(e, &length) + elif unit == 'km': + h3lib.exactEdgeLengthKm(e, &length) + elif unit == 'm': + h3lib.exactEdgeLengthM(e, &length) + else: + raise H3ValueError('Unknown unit: {}'.format(unit)) -# return length + return length diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index c3efea8..ba8a4e2 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -116,8 +116,20 @@ cdef extern from "h3api.h": H3Error gridDiskDistances(H3Index origin, int k, H3Index *out, int *distances) nogil H3Error gridRingUnsafe(H3Index origin, int k, H3Index *out) nogil - H3Error cellToBoundary(H3Index h3, CellBoundary *gp) nogil + H3Error areNeighborCells(H3Index origin, H3Index destination, int *out) nogil + H3Error cellsToDirectedEdge(H3Index origin, H3Index destination, H3Index *out) nogil + H3Error getDirectedEdgeOrigin(H3Index edge, H3Index *out) nogil + H3Error getDirectedEdgeDestination(H3Index edge, H3Index *out) nogil + H3Error originToDirectedEdges(H3Index origin, H3Index *edges) nogil + H3Error getHexagonEdgeLengthAvgKm(int res, double *out) nogil + H3Error getHexagonEdgeLengthAvgM(int res, double *out) nogil + + H3Error exactEdgeLengthRads(H3Index edge, double *out) nogil + H3Error exactEdgeLengthKm(H3Index edge, double *out) nogil + H3Error exactEdgeLengthM(H3Index edge, double *out) nogil + + H3Error cellToBoundary(H3Index h3, CellBoundary *gp) nogil H3Error directedEdgeToBoundary(H3Index edge, CellBoundary *gb) nogil double distanceRads(const LatLng *a, const LatLng *b) nogil @@ -148,21 +160,4 @@ cdef extern from "h3api.h": # void h3ToString(H3Index h, char *str, size_t sz) - # int h3IndexesAreNeighbors(H3Index origin, H3Index destination) - - # H3Index getH3UnidirectionalEdge(H3Index origin, H3Index destination) - - # H3Index getOriginH3IndexFromUnidirectionalEdge(H3Index edge) - - # H3Index getDestinationH3IndexFromUnidirectionalEdge(H3Index edge) - # void getH3IndexesFromUnidirectionalEdge(H3Index edge, H3Index *originDestination) - - # void getH3UnidirectionalEdgesFromHexagon(H3Index origin, H3Index *edges) - - # double edgeLengthKm(int res) nogil - # double edgeLengthM(int res) nogil - - # double exactEdgeLengthRads(H3Index edge) nogil - # double exactEdgeLengthKm(H3Index edge) nogil - # double exactEdgeLengthM(H3Index edge) nogil From 075da765394683988610a6fb02415acf24e5f490 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 2 Jun 2022 20:10:41 -0400 Subject: [PATCH 010/177] Fix sdist build (#239) * make sure `make_sdist` CI job still broken * reproduce locally * update h3lib * still seems broken * try sdist on mac and ubuntu * pyest! * debugging * ensurepath * Disable building docs * just build sdist once * colon Co-authored-by: Isaac Brodsky --- .github/workflows/wheels.yml | 58 ++++++++++++++++++++---------------- CMakeLists.txt | 1 + makefile | 1 - src/h3lib | 2 +- 4 files changed, 35 insertions(+), 27 deletions(-) diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index dd6bfbc..a6607e4 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -18,34 +18,43 @@ on: - published jobs: - # make_sdist: - # name: SDist - # if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }} - # runs-on: ubuntu-latest + make_sdist: + name: "SDist: ${{ matrix.os }}" + if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }} + runs-on: ${{ matrix.os }} - # steps: - # - uses: actions/checkout@v3 - # with: - # submodules: recursive + strategy: + matrix: + os: [ubuntu-latest] - # - name: Make sdist - # run: | - # pipx run build --sdist + steps: + - uses: actions/checkout@v3 + with: + submodules: recursive - # - name: Install from sdist - # run: | - # pip install --upgrade pip setuptools wheel - # pip install git+https://github.com/ajfriend/h3fake2.git - # cp dist/h3-*.tar.gz h3.tar.gz - # pip install h3.tar.gz[all] + - name: Setup Python + uses: actions/setup-python@v3.1.2 - # - name: Test sdist - # run: pytest --cov=h3 --full-trace + - name: Make sdist + run: | + python --version + pipx --version + pipx run build --sdist - # - name: Upload artifacts to GitHub - # uses: actions/upload-artifact@v3 - # with: - # path: ./dist + - name: Install from sdist + run: | + pip install --upgrade pip setuptools wheel + pip install git+https://github.com/ajfriend/h3fake2.git pytest + cp dist/h3-*.tar.gz h3.tar.gz + pip install h3.tar.gz[all] + + - name: Test sdist + run: pytest --cov=h3 --full-trace + + - name: Upload artifacts to GitHub + uses: actions/upload-artifact@v3 + with: + path: ./dist make_cibw_v1_wheels: name: "cibuildwheel v1: ${{ matrix.name }}" @@ -168,8 +177,7 @@ jobs: path: wheelhouse/*.whl upload_all: - # needs: [make_sdist, make_cibw_v1_wheels, make_cibw_v2_wheels] - needs: [make_cibw_v1_wheels, make_cibw_v2_wheels] + needs: [make_sdist, make_cibw_v1_wheels, make_cibw_v2_wheels] runs-on: ubuntu-latest if: github.event_name == 'release' && github.event.action == 'published' diff --git a/CMakeLists.txt b/CMakeLists.txt index 00d9fe4..436ea65 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -11,6 +11,7 @@ set(BUILD_BENCHMARKS OFF CACHE BOOL "" FORCE) set(BUILD_FILTERS OFF CACHE BOOL "" FORCE) set(BUILD_GENERATORS OFF CACHE BOOL "" FORCE) set(BUILD_TESTING OFF CACHE BOOL "" FORCE) +set(ENABLE_DOCS OFF CACHE BOOL "" FORCE) # Build the core library as static set(BUILD_SHARED_LIBS OFF) diff --git a/makefile b/makefile index 7c2845e..ac2e463 100644 --- a/makefile +++ b/makefile @@ -7,7 +7,6 @@ build-docs: open: open docs/_build/html/index.html - init: purge git submodule update --init python -m venv env diff --git a/src/h3lib b/src/h3lib index 294c20e..a36c614 160000 --- a/src/h3lib +++ b/src/h3lib @@ -1 +1 @@ -Subproject commit 294c20ed7d447122d5ab37260896d4ef7579ebfb +Subproject commit a36c614b477fb5409a0a87e0111d347ce550e40d From cfbd892780978dfba70747465069c0b28ca3f22f Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 2 Jun 2022 21:11:17 -0400 Subject: [PATCH 011/177] remove h3fake2 transitional library (#257) --- .github/workflows/coverage-lint.yml | 1 - .github/workflows/tests.yml | 1 - .github/workflows/wheels.yml | 6 +----- makefile | 1 - tests/h3fake2_errors.py | 15 --------------- tests/test_cells_and_edges.py | 2 +- tests/test_length_area.py | 2 +- tests/test_polyfill.py | 2 +- 8 files changed, 4 insertions(+), 26 deletions(-) delete mode 100644 tests/h3fake2_errors.py diff --git a/.github/workflows/coverage-lint.yml b/.github/workflows/coverage-lint.yml index 5110236..6d33368 100644 --- a/.github/workflows/coverage-lint.yml +++ b/.github/workflows/coverage-lint.yml @@ -23,7 +23,6 @@ jobs: - name: Install from source run: | pip install --upgrade pip setuptools wheel - pip install git+https://github.com/ajfriend/h3fake2.git pip install .[all] - name: Lint diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 0b9883d..072e21c 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -44,7 +44,6 @@ jobs: - name: Install from source run: | pip install --upgrade pip setuptools wheel - pip install git+https://github.com/ajfriend/h3fake2.git pip install .[all] - name: Tests diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index a6607e4..a02f51d 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -44,7 +44,7 @@ jobs: - name: Install from sdist run: | pip install --upgrade pip setuptools wheel - pip install git+https://github.com/ajfriend/h3fake2.git pytest + pip install pytest cp dist/h3-*.tar.gz h3.tar.gz pip install h3.tar.gz[all] @@ -84,8 +84,6 @@ jobs: CIBW_TEST_COMMAND: pytest {project}/tests CIBW_ARCHS_LINUX: auto aarch64 CIBW_BUILD: ${{ matrix.build }} - CIBW_BEFORE_BUILD: pip install git+https://github.com/ajfriend/h3fake2.git - CIBW_BEFORE_TEST: pip install git+https://github.com/ajfriend/h3fake2.git - name: Check with Twine run: | @@ -164,8 +162,6 @@ jobs: CIBW_ARCHS_MACOS: x86_64 arm64 CIBW_BUILD: ${{ matrix.build }} CIBW_SKIP: ${{ matrix.skip }} - CIBW_BEFORE_BUILD: pip install git+https://github.com/ajfriend/h3fake2.git - CIBW_BEFORE_TEST: pip install git+https://github.com/ajfriend/h3fake2.git - name: Check with Twine run: | diff --git a/makefile b/makefile index ac2e463..44eceb8 100644 --- a/makefile +++ b/makefile @@ -11,7 +11,6 @@ init: purge git submodule update --init python -m venv env env/bin/pip install --upgrade pip wheel setuptools - env/bin/pip install git+https://github.com/ajfriend/h3fake2.git env/bin/pip install .[all] env/bin/pip install -r requirements.in diff --git a/tests/h3fake2_errors.py b/tests/h3fake2_errors.py deleted file mode 100644 index da56887..0000000 --- a/tests/h3fake2_errors.py +++ /dev/null @@ -1,15 +0,0 @@ -# flake8: noqa -""" -Some of the tests expect to catch certain errors. -As we transition, we'll have errors of each type. -pytest functions can accept tuples of errors to check for either one. -""" - -import h3 -import h3fake2 - -H3ValueError = (h3.H3ValueError, h3fake2.H3ValueError) -H3CellError = (h3.H3CellError, h3fake2.H3CellError) -H3ResolutionError = (h3.H3ResolutionError, h3fake2.H3ResolutionError) -H3EdgeError = (h3.H3EdgeError, h3fake2.H3EdgeError) -H3DistanceError = (h3.H3DistanceError, h3fake2.H3DistanceError) diff --git a/tests/test_cells_and_edges.py b/tests/test_cells_and_edges.py index 851dda5..a90bb0a 100644 --- a/tests/test_cells_and_edges.py +++ b/tests/test_cells_and_edges.py @@ -1,7 +1,7 @@ import h3 import pytest -from .h3fake2_errors import ( +from h3 import ( H3ValueError, H3CellError, H3ResolutionError, diff --git a/tests/test_length_area.py b/tests/test_length_area.py index 2a1b5d7..8236199 100644 --- a/tests/test_length_area.py +++ b/tests/test_length_area.py @@ -1,7 +1,7 @@ import h3 import pytest -from .h3fake2_errors import H3ValueError +from h3 import H3ValueError def approx2(a, b): diff --git a/tests/test_polyfill.py b/tests/test_polyfill.py index a02560d..7c35bb6 100644 --- a/tests/test_polyfill.py +++ b/tests/test_polyfill.py @@ -2,7 +2,7 @@ import h3 import itertools import pytest -from .h3fake2_errors import H3ResolutionError +from h3 import H3ResolutionError def reverse(loop): From 572a09b08c5a7de5440346bebc79effcf0e0b36a Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 20:10:10 -0700 Subject: [PATCH 012/177] initial commit --- src/h3/_cy/CMakeLists.txt | 3 ++ src/h3/_cy/cells.pyx | 8 ++-- src/h3/_cy/memory.pxd | 14 ++++++ src/h3/_cy/memory.pyx | 99 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 121 insertions(+), 3 deletions(-) create mode 100644 src/h3/_cy/memory.pxd create mode 100644 src/h3/_cy/memory.pyx diff --git a/src/h3/_cy/CMakeLists.txt b/src/h3/_cy/CMakeLists.txt index 386557c..2103b48 100644 --- a/src/h3/_cy/CMakeLists.txt +++ b/src/h3/_cy/CMakeLists.txt @@ -22,6 +22,7 @@ add_cython_file(geo) add_cython_file(cells) add_cython_file(edges) add_cython_file(to_multipoly) +add_cython_file(memory) # Include pyx and pxd files in distribution for use by Cython API install( @@ -35,6 +36,8 @@ install( h3lib.pxd util.pxd util.pyx + memory.pxd + memory.pyx DESTINATION src/h3/_cy ) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 4453e38..c280a77 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -11,6 +11,8 @@ from .util cimport ( empty_memory_view, # want to drop this import if possible ) +from .memory cimport H3MemoryManager + from .util import H3ValueError, H3ResolutionError # todo: add notes about Cython exception handling @@ -78,9 +80,9 @@ cpdef H3int[:] disk(H3int h, int k): # ignoring error for now err = h3lib.maxGridDiskSize(k, &n) - ptr = create_ptr(n) # todo: return a "smart" pointer that knows its length? - err = h3lib.gridDisk(h, k, ptr) # ignoring error again! - mv = create_mv(ptr, n) + hmm = H3MemoryManager(n) + err = h3lib.gridDisk(h, k, hmm.get_ptr()) + mv = hmm.create_mv() return mv diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd new file mode 100644 index 0000000..8e058fd --- /dev/null +++ b/src/h3/_cy/memory.pxd @@ -0,0 +1,14 @@ +from .h3lib cimport H3int + +cdef class H3MemoryManager: + cdef: + size_t n + H3int* ptr + + cdef H3int* get_ptr(self) + cdef H3int[:] create_mv(self) + + +""" +todo: read: https://cython.readthedocs.io/en/latest/src/tutorial/pxd_files.html +""" diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx new file mode 100644 index 0000000..69fce9c --- /dev/null +++ b/src/h3/_cy/memory.pyx @@ -0,0 +1,99 @@ +from libc cimport stdlib +from cython.view cimport array +from .h3lib cimport H3int + + +cdef size_t move_nonzeros(H3int* a, size_t n): + """ Move nonzero elements to front of array `a` of length `n`. + Return the number of nonzero elements. + + Loop invariant: Everything *before* `i` or *after* `j` is "done". + Move `i` and `j` inwards until they equal, and exit. + You can move `i` forward until there's a zero in front of it. + You can move `j` backward until there's a nonzero to the left of it. + Anything to the right of `j` is "junk" that can be reallocated. + + | a | b | 0 | c | d | ... | + ^ ^ + i j + + + | a | b | d | c | d | ... | + ^ ^ + i j + """ + cdef: + size_t i = 0 + size_t j = n + + while i < j: + if a[j-1] == 0: + j -= 1 + continue + + if a[i] != 0: + i += 1 + continue + + # if we're here, we know: + # a[i] == 0 + # a[j-1] != 0 + # i < j + # so we can swap! (actually, move a[j-1] -> a[i]) + a[i] = a[j-1] + j -= 1 + + return i + + +cdef H3int[:] empty_memory_view(): + # there's gotta be a better way to do this... + # create an empty cython.view.array? + cdef: + H3int a[1] + + return (a)[:0] + + +cdef class H3MemoryManager: + def __cinit__(self, size_t n): + self.n = n + self.ptr = stdlib.calloc(self.n, sizeof(H3int)) + + if (self.n > 0) and (not self.ptr): + raise MemoryError() + + cdef H3int* get_ptr(self): + return self.ptr + + cdef H3int[:] create_mv(self): + cdef: + array x + + self.n = move_nonzeros(self.ptr, self.n) + if self.n <= 0: + stdlib.free(self.ptr) + return empty_memory_view() + + self.ptr = stdlib.realloc(self.ptr, self.n*sizeof(H3int)) + + if self.ptr is NULL: + raise MemoryError() + + x = self.ptr + x.callback_free_data = stdlib.free + + # responsibility for the memory moves from this object to the array/memoryview + self.ptr = NULL + self.n = 0 + + return x + + def __dealloc__(self): + # If the memory now belongs elsewhere with a memoryview, this pointer + # should be null, and deallocing on NULL is fine. + # If the pointer is not null, then this means the MemoryManager + # has not given the memory away to another object. + stdlib.free(self.ptr) + + From 34b7eed770b96e94158b527efef6eab362e16eb0 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 20:15:36 -0700 Subject: [PATCH 013/177] hmmmmmmm --- src/h3/_cy/cells.pyx | 2 +- src/h3/_cy/memory.pxd | 1 - src/h3/_cy/memory.pyx | 11 ++++------- 3 files changed, 5 insertions(+), 9 deletions(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index c280a77..6cc4841 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -81,7 +81,7 @@ cpdef H3int[:] disk(H3int h, int k): err = h3lib.maxGridDiskSize(k, &n) hmm = H3MemoryManager(n) - err = h3lib.gridDisk(h, k, hmm.get_ptr()) + err = h3lib.gridDisk(h, k, hmm.ptr) mv = hmm.create_mv() return mv diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd index 8e058fd..5dc5b2a 100644 --- a/src/h3/_cy/memory.pxd +++ b/src/h3/_cy/memory.pxd @@ -5,7 +5,6 @@ cdef class H3MemoryManager: size_t n H3int* ptr - cdef H3int* get_ptr(self) cdef H3int[:] create_mv(self) diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index 69fce9c..b051d73 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -63,9 +63,6 @@ cdef class H3MemoryManager: if (self.n > 0) and (not self.ptr): raise MemoryError() - cdef H3int* get_ptr(self): - return self.ptr - cdef H3int[:] create_mv(self): cdef: array x @@ -90,10 +87,10 @@ cdef class H3MemoryManager: return x def __dealloc__(self): - # If the memory now belongs elsewhere with a memoryview, this pointer - # should be null, and deallocing on NULL is fine. - # If the pointer is not null, then this means the MemoryManager - # has not given the memory away to another object. + # If the memory has been handed off to a memoryview, this pointer + # should be NULL, and deallocing on NULL is fine. + # If the pointer is *not* NULL, then this means the MemoryManager + # has is still responsible for the memory (it hasn't given the memory away to another object). stdlib.free(self.ptr) From 0daa79be3e20904a9bf9cccc4bfabe8037c160dd Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 20:27:15 -0700 Subject: [PATCH 014/177] H3Index -> H3int --- src/h3/_cy/h3lib.pxd | 105 +++++++++++++++++++++---------------------- 1 file changed, 52 insertions(+), 53 deletions(-) diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index ba8a4e2..c3b9417 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -1,7 +1,6 @@ from cpython cimport bool from libc.stdint cimport uint64_t, int64_t, uint32_t -ctypedef uint64_t H3int ctypedef uint32_t H3Error ctypedef basestring H3str @@ -10,7 +9,7 @@ cdef extern from "h3api.h": cdef int H3_VERSION_MINOR cdef int H3_VERSION_PATCH - ctypedef uint64_t H3Index + ctypedef uint64_t H3int "H3Index" ctypedef struct LatLng: double lat # in radians @@ -48,45 +47,45 @@ cdef extern from "h3api.h": int numHoles GeoLoop *holes - int isValidCell(H3Index h) nogil - int isPentagon(H3Index h) nogil - int isResClassIII(H3Index h) nogil - int isValidDirectedEdge(H3Index edge) nogil + int isValidCell(H3int h) nogil + int isPentagon(H3int h) nogil + int isResClassIII(H3int h) nogil + int isValidDirectedEdge(H3int edge) nogil double degsToRads(double degrees) nogil double radsToDegs(double radians) nogil - int getResolution(H3Index h) nogil - int getBaseCellNumber(H3Index h) nogil + int getResolution(H3int h) nogil + int getBaseCellNumber(H3int h) nogil - H3Error latLngToCell(const LatLng *g, int res, H3Index *out) nogil - H3Error cellToLatLng(H3Index h, LatLng *) nogil - H3Error gridDistance(H3Index h1, H3Index h2, int64_t *distance) nogil + H3Error latLngToCell(const LatLng *g, int res, H3int *out) nogil + H3Error cellToLatLng(H3int h, LatLng *) nogil + H3Error gridDistance(H3int h1, H3int h2, int64_t *distance) nogil H3Error maxGridDiskSize(int k, int64_t *out) nogil # num/out/N? - H3Error gridDisk(H3Index h, int k, H3Index *out) nogil + H3Error gridDisk(H3int h, int k, H3int *out) nogil - H3Error cellToParent( H3Index h, int parentRes, H3Index *parent) nogil - H3Error cellToCenterChild(H3Index h, int childRes, H3Index *child) nogil + H3Error cellToParent( H3int h, int parentRes, H3int *parent) nogil + H3Error cellToCenterChild(H3int h, int childRes, H3int *child) nogil - H3Error cellToChildrenSize(H3Index h, int childRes, int64_t *num) nogil # num/out/N? - H3Error cellToChildren( H3Index h, int childRes, H3Index *children) nogil + H3Error cellToChildrenSize(H3int h, int childRes, int64_t *num) nogil # num/out/N? + H3Error cellToChildren( H3int h, int childRes, H3int *children) nogil H3Error compactCells( - const H3Index *cells_u, - H3Index *cells_c, + const H3int *cells_u, + H3int *cells_c, const int num_u ) nogil H3Error uncompactCellsSize( - const H3Index *cells_c, + const H3int *cells_c, const int64_t num_c, const int res, int64_t *num_u ) nogil H3Error uncompactCells( - const H3Index *cells_c, + const H3int *cells_c, const int num_c, - H3Index *cells_u, + H3int *cells_u, const int num_u, const int res ) nogil @@ -94,70 +93,70 @@ cdef extern from "h3api.h": H3Error getNumCells(int res, int64_t *out) nogil int pentagonCount() nogil int res0CellCount() nogil - H3Error getPentagons(int res, H3Index *out) nogil - H3Error getRes0Cells(H3Index *out) nogil + H3Error getPentagons(int res, H3int *out) nogil + H3Error getRes0Cells(H3int *out) nogil - H3Error gridPathCellsSize(H3Index start, H3Index end, int64_t *size) nogil - H3Error gridPathCells(H3Index start, H3Index end, H3Index *out) nogil + H3Error gridPathCellsSize(H3int start, H3int end, int64_t *size) nogil + H3Error gridPathCells(H3int start, H3int end, H3int *out) nogil H3Error getHexagonAreaAvgKm2(int res, double *out) nogil H3Error getHexagonAreaAvgM2(int res, double *out) nogil - H3Error cellAreaRads2(H3Index h, double *out) nogil - H3Error cellAreaKm2(H3Index h, double *out) nogil - H3Error cellAreaM2(H3Index h, double *out) nogil + H3Error cellAreaRads2(H3int h, double *out) nogil + H3Error cellAreaKm2(H3int h, double *out) nogil + H3Error cellAreaM2(H3int h, double *out) nogil - H3Error maxFaceCount(H3Index h, int *out) nogil - H3Error getIcosahedronFaces(H3Index h3, int *out) nogil + H3Error maxFaceCount(H3int h, int *out) nogil + H3Error getIcosahedronFaces(H3int h3, int *out) nogil - H3Error cellToLocalIj(H3Index origin, H3Index h3, uint32_t mode, CoordIJ *out) nogil - H3Error localIjToCell(H3Index origin, const CoordIJ *ij, uint32_t mode, H3Index *out) nogil + H3Error cellToLocalIj(H3int origin, H3int h3, uint32_t mode, CoordIJ *out) nogil + H3Error localIjToCell(H3int origin, const CoordIJ *ij, uint32_t mode, H3int *out) nogil - H3Error gridDiskDistances(H3Index origin, int k, H3Index *out, int *distances) nogil - H3Error gridRingUnsafe(H3Index origin, int k, H3Index *out) nogil + H3Error gridDiskDistances(H3int origin, int k, H3int *out, int *distances) nogil + H3Error gridRingUnsafe(H3int origin, int k, H3int *out) nogil - H3Error areNeighborCells(H3Index origin, H3Index destination, int *out) nogil - H3Error cellsToDirectedEdge(H3Index origin, H3Index destination, H3Index *out) nogil - H3Error getDirectedEdgeOrigin(H3Index edge, H3Index *out) nogil - H3Error getDirectedEdgeDestination(H3Index edge, H3Index *out) nogil - H3Error originToDirectedEdges(H3Index origin, H3Index *edges) nogil + H3Error areNeighborCells(H3int origin, H3int destination, int *out) nogil + H3Error cellsToDirectedEdge(H3int origin, H3int destination, H3int *out) nogil + H3Error getDirectedEdgeOrigin(H3int edge, H3int *out) nogil + H3Error getDirectedEdgeDestination(H3int edge, H3int *out) nogil + H3Error originToDirectedEdges(H3int origin, H3int *edges) nogil H3Error getHexagonEdgeLengthAvgKm(int res, double *out) nogil H3Error getHexagonEdgeLengthAvgM(int res, double *out) nogil - H3Error exactEdgeLengthRads(H3Index edge, double *out) nogil - H3Error exactEdgeLengthKm(H3Index edge, double *out) nogil - H3Error exactEdgeLengthM(H3Index edge, double *out) nogil + H3Error exactEdgeLengthRads(H3int edge, double *out) nogil + H3Error exactEdgeLengthKm(H3int edge, double *out) nogil + H3Error exactEdgeLengthM(H3int edge, double *out) nogil - H3Error cellToBoundary(H3Index h3, CellBoundary *gp) nogil - H3Error directedEdgeToBoundary(H3Index edge, CellBoundary *gb) nogil + H3Error cellToBoundary(H3int h3, CellBoundary *gp) nogil + H3Error directedEdgeToBoundary(H3int edge, CellBoundary *gb) nogil double distanceRads(const LatLng *a, const LatLng *b) nogil double distanceKm(const LatLng *a, const LatLng *b) nogil double distanceM(const LatLng *a, const LatLng *b) nogil - H3Error cellsToLinkedMultiPolygon(const H3Index *h3Set, const int numHexes, LinkedGeoPolygon *out) + H3Error cellsToLinkedMultiPolygon(const H3int *h3Set, const int numHexes, LinkedGeoPolygon *out) void destroyLinkedMultiPolygon(LinkedGeoPolygon *polygon) H3Error maxPolygonToCellsSize(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t *count) - H3Error polygonToCells(const GeoPolygon *geoPolygon, int res, uint32_t flags, H3Index *out) + H3Error polygonToCells(const GeoPolygon *geoPolygon, int res, uint32_t flags, H3int *out) # ctypedef struct GeoMultiPolygon: # int numPolygons # GeoPolygon *polygons - # int hexRange(H3Index origin, int k, H3Index *out) + # int hexRange(H3int origin, int k, H3int *out) - # int hexRangeDistances(H3Index origin, int k, H3Index *out, int *distances) + # int hexRangeDistances(H3int origin, int k, H3int *out, int *distances) - # int hexRanges(H3Index *h3Set, int length, int k, H3Index *out) + # int hexRanges(H3int *h3Set, int length, int k, H3int *out) - # void h3SetToLinkedGeo(const H3Index *h3Set, const int numHexes, LinkedGeoPolygon *out) + # void h3SetToLinkedGeo(const H3int *h3Set, const int numHexes, LinkedGeoPolygon *out) # void destroyLinkedPolygon(LinkedGeoPolygon *polygon) - # H3Index stringToH3(const char *str) + # H3int stringToH3(const char *str) - # void h3ToString(H3Index h, char *str, size_t sz) + # void h3ToString(H3int h, char *str, size_t sz) - # void getH3IndexesFromUnidirectionalEdge(H3Index edge, H3Index *originDestination) + # void getH3intesFromUnidirectionalEdge(H3int edge, H3int *originDestination) From ffb8c8a3c1b835c0d0a1ddfdabf76fcd41a475f9 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 20:39:09 -0700 Subject: [PATCH 015/177] hmm --- src/h3/_cy/cells.pyx | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 6cc4841..9ca5ce3 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -92,7 +92,7 @@ cpdef H3int[:] _ring_fallback(H3int h, int k): `ring` tries to call `h3lib.hexRing` first; if that fails, we call this function, which relies on `h3lib.kRingDistances`. - Failures for `h3lib.hexRing` happen when the algortihm runs into a pentagon. + Failures for `h3lib.hexRing` happen when the algorithm runs into a pentagon. """ cdef: int64_t n @@ -102,24 +102,23 @@ cpdef H3int[:] _ring_fallback(H3int h, int k): check_distance(k) err = h3lib.maxGridDiskSize(k, &n) - # array of h3 cells - ptr = create_ptr(n) + hmm = H3MemoryManager(n) # array of cell distances from `h` dist_ptr = stdlib.calloc(n, sizeof(int)) if dist_ptr is NULL: raise MemoryError() - err = h3lib.gridDiskDistances(h, k, ptr, dist_ptr) + err = h3lib.gridDiskDistances(h, k, hmm.ptr, dist_ptr) distances = dist_ptr distances.callback_free_data = stdlib.free for i,v in enumerate(distances): if v != k: - ptr[i] = 0 + hmm.ptr[i] = 0 - mv = create_mv(ptr, n) + mv = hmm.create_mv() return mv From 6f62aab5c69e4a915dea1513ead30e3a02075392 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 21:07:08 -0700 Subject: [PATCH 016/177] int_mv rides into town --- src/h3/_cy/memory.pxd | 6 ++++++ src/h3/_cy/memory.pyx | 18 ++++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd index 5dc5b2a..83ac1fb 100644 --- a/src/h3/_cy/memory.pxd +++ b/src/h3/_cy/memory.pxd @@ -8,6 +8,12 @@ cdef class H3MemoryManager: cdef H3int[:] create_mv(self) +cdef int[:] int_mv(size_t n) + + """ todo: read: https://cython.readthedocs.io/en/latest/src/tutorial/pxd_files.html + +todo: should i be allocating with python memory functions? +https://cython.readthedocs.io/en/latest/src/tutorial/memory_allocation.html """ diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index b051d73..1393a0e 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -94,3 +94,21 @@ cdef class H3MemoryManager: stdlib.free(self.ptr) +""" +Can someone please swoop in and find a much cleaner way to do all of this Cython memory management baloney? +""" +cdef int[:] int_mv(size_t n): + cdef: + int* ptr + array arr + + if n <= 0: + raise MemoryError() + ptr = stdlib.calloc(n, sizeof(int)) + if ptr is NULL: + raise MemoryError() + + arr = ptr + arr.callback_free_data = stdlib.free + + return arr From f8a65051d80ae0d882f8c6c60e3e4d1197a9d9a3 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 21:22:50 -0700 Subject: [PATCH 017/177] the mystery of the `int[:] distances` --- src/h3/_cy/cells.pyx | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 9ca5ce3..5b48a3a 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -11,7 +11,7 @@ from .util cimport ( empty_memory_view, # want to drop this import if possible ) -from .memory cimport H3MemoryManager +from .memory cimport H3MemoryManager, int_mv from .util import H3ValueError, H3ResolutionError @@ -97,6 +97,7 @@ cpdef H3int[:] _ring_fallback(H3int h, int k): cdef: int64_t n h3lib.H3Error err + int[:] distances ## todo: weird, this needs to be specified to avoid errors. cython bug? check_cell(h) check_distance(k) @@ -104,15 +105,9 @@ cpdef H3int[:] _ring_fallback(H3int h, int k): err = h3lib.maxGridDiskSize(k, &n) hmm = H3MemoryManager(n) - # array of cell distances from `h` - dist_ptr = stdlib.calloc(n, sizeof(int)) - if dist_ptr is NULL: - raise MemoryError() - - err = h3lib.gridDiskDistances(h, k, hmm.ptr, dist_ptr) - - distances = dist_ptr - distances.callback_free_data = stdlib.free + # parallel array of cell distances from `h` + distances = int_mv(n) + err = h3lib.gridDiskDistances(h, k, hmm.ptr, &distances[0]) for i,v in enumerate(distances): if v != k: From c38be89b26f27e1a24799de1977d6b04d56d6e7e Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 21:42:37 -0700 Subject: [PATCH 018/177] ring and children --- src/h3/_cy/cells.pyx | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 5b48a3a..8e04e22 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -106,6 +106,9 @@ cpdef H3int[:] _ring_fallback(H3int h, int k): hmm = H3MemoryManager(n) # parallel array of cell distances from `h` + + # idea: instead of a memoryview object, have a my_mv object that can return a ptr, but does the correct logic when it has length 0 + # then can always just return the pointer, instead of the weird &mv[0] syntax distances = int_mv(n) err = h3lib.gridDiskDistances(h, k, hmm.ptr, &distances[0]) @@ -128,18 +131,14 @@ cpdef H3int[:] ring(H3int h, int k): check_distance(k) n = 6*k if k > 0 else 1 - ptr = create_ptr(n) + hmm = H3MemoryManager(n) - err = h3lib.gridRingUnsafe(h, k, ptr) - - # if we drop into the failure state, we might be tempted to not create - # this mv, but creating the mv is exactly what guarantees that we'll free - # the memory. context manager would be better here, if we can figure out - # how to do that - mv = create_mv(ptr, n) + err = h3lib.gridRingUnsafe(h, k, hmm.ptr) if err: mv = _ring_fallback(h, k) + else: + mv = hmm.create_mv() return mv @@ -165,9 +164,8 @@ cpdef H3int parent(H3int h, res=None) except 0: cpdef H3int[:] children(H3int h, res=None): cdef: - H3int child h3lib.H3Error err - int64_t N + int64_t n check_cell(h) @@ -179,11 +177,11 @@ cpdef H3int[:] children(H3int h, res=None): raise H3ResolutionError(msg) check_res(res) - err = h3lib.cellToChildrenSize(h, res, &N) + err = h3lib.cellToChildrenSize(h, res, &n) - ptr = create_ptr(N) - err = h3lib.cellToChildren(h, res, ptr) - mv = create_mv(ptr, N) + hmm = H3MemoryManager(n) + err = h3lib.cellToChildren(h, res, hmm.ptr) + mv = hmm.create_mv() return mv From b0b0472f75218d2805e888e2e96565764cd4cbdf Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 21:54:33 -0700 Subject: [PATCH 019/177] mysteries abound! --- src/h3/_cy/cells.pyx | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 8e04e22..da496c5 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -222,14 +222,18 @@ cpdef H3int[:] compact(const H3int[:] hu): for h in hu: ## todo: should we have an array version? would that be faster? check_cell(h) - ptr = create_ptr(len(hu)) - err = h3lib.compactCells(&hu[0], ptr, len(hu)) - mv = create_mv(ptr, len(hu)) + cdef size_t n = len(hu) + hmm = H3MemoryManager(n) + err = h3lib.compactCells(&hu[0], hmm.ptr, n) if err: # todo: additional error processing raise H3ValueError('Could not compact set of hexagons!') + # todo: mystery: why does this break in the tests when you move it before the error check? + # ideally, the create_mv method would be robust to borked data... + mv = hmm.create_mv() + return mv From fd8a9c261656e45fb6d56bae1c014305162d663f Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 21:56:45 -0700 Subject: [PATCH 020/177] thinking thoughts --- src/h3/_cy/cells.pyx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index da496c5..ccfbd21 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -208,6 +208,8 @@ cpdef H3int center_child(H3int h, res=None) except 0: cpdef H3int[:] compact(const H3int[:] hu): + # todo: fix this with my own Cython object "wrapper" class? + # everything has a .ptr interface? # todo: the Clib can handle 0-len arrays because it **avoids** # dereferencing the pointer, but Cython's syntax of # `&hu[0]` **requires** a dereference. For Cython, checking for array From b74f7ef584e5f20440ac21a8603242271959bc89 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 22:02:01 -0700 Subject: [PATCH 021/177] so, check this out: this works --- src/h3/_cy/cells.pyx | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index ccfbd21..ab7e92e 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -249,7 +249,7 @@ cpdef H3int[:] uncompact(const H3int[:] hc, int res): # note: open to better ideas! cdef: h3lib.H3Error err - int64_t N + int64_t n if len(hc) == 0: return empty_memory_view() @@ -258,21 +258,22 @@ cpdef H3int[:] uncompact(const H3int[:] hc, int res): check_cell(h) # ignoring error for now - err = h3lib.uncompactCellsSize(&hc[0], len(hc), res, &N) + err = h3lib.uncompactCellsSize(&hc[0], len(hc), res, &n) - ptr = create_ptr(N) + hmm = H3MemoryManager(n) err = h3lib.uncompactCells( &hc[0], len(hc), - ptr, - N, + hmm.ptr, + hmm.n, res ) - mv = create_mv(ptr, N) if err: raise H3ValueError('Could not uncompact set of hexagons!') + mv = hmm.create_mv() + return mv From 5e02924c6e00dbb8590262eb4b0e0e815ed2f9fa Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 22:04:51 -0700 Subject: [PATCH 022/177] and this one gives an error. the game is afoot. --- src/h3/_cy/cells.pyx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index ab7e92e..f75a990 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -269,11 +269,11 @@ cpdef H3int[:] uncompact(const H3int[:] hc, int res): res ) + mv = hmm.create_mv() + if err: raise H3ValueError('Could not uncompact set of hexagons!') - mv = hmm.create_mv() - return mv From f70f1163bb6bbb238f9a65f366e33e69756c80e1 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 22:06:33 -0700 Subject: [PATCH 023/177] good ol' fashioned detective work will catch the crook --- src/h3/_cy/cells.pyx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index f75a990..16298ba 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -269,11 +269,13 @@ cpdef H3int[:] uncompact(const H3int[:] hc, int res): res ) - mv = hmm.create_mv() - if err: raise H3ValueError('Could not uncompact set of hexagons!') + # todo: again! doesn't work if i have this before the error check! + # why isn't hmm.create_mv() robust to failures before it? + mv = hmm.create_mv() + return mv From b787da973f45a35f03850fa63aeccef352038395 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 22:09:48 -0700 Subject: [PATCH 024/177] just good taste, really --- src/h3/_cy/cells.pyx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 16298ba..ec5de04 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -262,7 +262,7 @@ cpdef H3int[:] uncompact(const H3int[:] hc, int res): hmm = H3MemoryManager(n) err = h3lib.uncompactCells( - &hc[0], + &hc[0], # todo: symmetry here with the wrapper object might be nice. hc.ptr / hc.n len(hc), hmm.ptr, hmm.n, From 582973012717b92cd68085bfc312c93baeb32c1b Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 22:14:00 -0700 Subject: [PATCH 025/177] line --- src/h3/_cy/cells.pyx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index ec5de04..c1d45c1 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -347,15 +347,17 @@ cpdef H3int[:] line(H3int start, H3int end): s = s.format(hex(start), hex(end)) raise H3ValueError(s) - ptr = create_ptr(n) - err = h3lib.gridPathCells(start, end, ptr) - mv = create_mv(ptr, n) + hmm = H3MemoryManager(n) + err = h3lib.gridPathCells(start, end, hmm.ptr) if err: s = "Couldn't find line between cells {} and {}" s = s.format(hex(start), hex(end)) raise H3ValueError(s) + # todo: probably here too? + mv = hmm.create_mv() + return mv cpdef bool is_res_class_iii(H3int h): From f4471d3a2a6000522ca9f602107cd062438e94df Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 22:15:54 -0700 Subject: [PATCH 026/177] oh boy. didn't actually break on this one. --- src/h3/_cy/cells.pyx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index c1d45c1..b847eff 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -350,14 +350,14 @@ cpdef H3int[:] line(H3int start, H3int end): hmm = H3MemoryManager(n) err = h3lib.gridPathCells(start, end, hmm.ptr) + # todo: probably here too? + mv = hmm.create_mv() + if err: s = "Couldn't find line between cells {} and {}" s = s.format(hex(start), hex(end)) raise H3ValueError(s) - # todo: probably here too? - mv = hmm.create_mv() - return mv cpdef bool is_res_class_iii(H3int h): From 0354013a51bddc9095cece918f62a1406ab7140d Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 22:16:11 -0700 Subject: [PATCH 027/177] but back to what's good, just to be safe --- src/h3/_cy/cells.pyx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index b847eff..c1d45c1 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -350,14 +350,14 @@ cpdef H3int[:] line(H3int start, H3int end): hmm = H3MemoryManager(n) err = h3lib.gridPathCells(start, end, hmm.ptr) - # todo: probably here too? - mv = hmm.create_mv() - if err: s = "Couldn't find line between cells {} and {}" s = s.format(hex(start), hex(end)) raise H3ValueError(s) + # todo: probably here too? + mv = hmm.create_mv() + return mv cpdef bool is_res_class_iii(H3int h): From 2ceaa5c493e4c98701231dee26a0d327fd219d68 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 22:19:45 -0700 Subject: [PATCH 028/177] these work --- src/h3/_cy/cells.pyx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index c1d45c1..a537159 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -372,9 +372,9 @@ cpdef H3int[:] get_pentagon_indexes(int res): n = h3lib.pentagonCount() - ptr = create_ptr(n) - err = h3lib.getPentagons(res, ptr) - mv = create_mv(ptr, n) + hmm = H3MemoryManager(n) + err = h3lib.getPentagons(res, hmm.ptr) + mv = hmm.create_mv() return mv @@ -385,9 +385,9 @@ cpdef H3int[:] get_res0_indexes(): n = h3lib.res0CellCount() - ptr = create_ptr(n) - err = h3lib.getRes0Cells(ptr) - mv = create_mv(ptr, n) + hmm = H3MemoryManager(n) + err = h3lib.getRes0Cells(hmm.ptr) + mv = hmm.create_mv() return mv From f2fd2b7ca513e1a82420a9173ba743192a4c9737 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 22:29:04 -0700 Subject: [PATCH 029/177] get_faces --- src/h3/_cy/cells.pyx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index a537159..f749464 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -391,26 +391,26 @@ cpdef H3int[:] get_res0_indexes(): return mv +# oh, this is returning a set?? +# todo: convert to int[:]? cpdef get_faces(H3int h): cdef: h3lib.H3Error err int n + int[:] faces ## todo: weird, this needs to be specified to avoid errors. cython bug? check_cell(h) err = h3lib.maxFaceCount(h, &n) #ignore error for now - cdef int* ptr = stdlib.calloc(n, sizeof(int)) - if (n > 0) and (not ptr): - raise MemoryError() + faces = int_mv(n) + err = h3lib.getIcosahedronFaces(h, &faces[0]) # handle error? - err = h3lib.getIcosahedronFaces(h, ptr) # handle error? + # todo: wait? do faces start from 0 or 1? + # we could do this check/processing in the int_mv object + out = {f for f in faces if f >= 0} - faces = ptr - faces = {f for f in faces if f >= 0} - stdlib.free(ptr) - - return faces + return out cpdef (int, int) experimental_h3_to_local_ij(H3int origin, H3int h) except *: From 9669632af5b1474b6c95fececbd5db69bdd267b0 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 22:43:01 -0700 Subject: [PATCH 030/177] cells.pyx is moved over --- src/h3/_cy/cells.pyx | 12 ++++++------ src/h3/_cy/memory.pxd | 2 +- src/h3/_cy/memory.pyx | 1 + 3 files changed, 8 insertions(+), 7 deletions(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index f749464..f363d95 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -6,15 +6,15 @@ from .util cimport ( check_cell, check_res, check_distance, - create_ptr, - create_mv, - empty_memory_view, # want to drop this import if possible ) - -from .memory cimport H3MemoryManager, int_mv - from .util import H3ValueError, H3ResolutionError +from .memory cimport ( + H3MemoryManager, + int_mv, + empty_memory_view, # todo: want to get rid of this! +) + # todo: add notes about Cython exception handling diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd index 83ac1fb..235c06e 100644 --- a/src/h3/_cy/memory.pxd +++ b/src/h3/_cy/memory.pxd @@ -9,7 +9,7 @@ cdef class H3MemoryManager: cdef int[:] int_mv(size_t n) - +cdef H3int[:] empty_memory_view() """ todo: read: https://cython.readthedocs.io/en/latest/src/tutorial/pxd_files.html diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index 1393a0e..1625bca 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -47,6 +47,7 @@ cdef size_t move_nonzeros(H3int* a, size_t n): cdef H3int[:] empty_memory_view(): + # todo: get rid of this? # there's gotta be a better way to do this... # create an empty cython.view.array? cdef: From f918c91b81458258bae71ab152fab2364e670b78 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 22:47:16 -0700 Subject: [PATCH 031/177] i think that covers edges.pyx --- src/h3/_cy/edges.pyx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/h3/_cy/edges.pyx b/src/h3/_cy/edges.pyx index 716c96a..45fd711 100644 --- a/src/h3/_cy/edges.pyx +++ b/src/h3/_cy/edges.pyx @@ -5,10 +5,10 @@ from .util cimport ( check_cell, check_edge, check_res, - create_ptr, - create_mv, ) +from .memory cimport H3MemoryManager + from .util import H3ValueError cpdef bool are_neighbors(H3int h1, H3int h2): @@ -75,9 +75,9 @@ cpdef H3int[:] edges_from_cell(H3int origin): """ check_cell(origin) - ptr = create_ptr(6) - h3lib.originToDirectedEdges(origin, ptr) - mv = create_mv(ptr, 6) + hmm = H3MemoryManager(6) + h3lib.originToDirectedEdges(origin, hmm.ptr) + mv = hmm.create_mv() return mv From cec9c84fa5a141c48715317b3b6614c466d44e18 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 23:07:01 -0700 Subject: [PATCH 032/177] so i can get this far, but i run into issues when i try to convert `polyfill_polygon`. some memory error. not sure what's happening just yet. --- src/h3/_cy/geo.pyx | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/src/h3/_cy/geo.pyx b/src/h3/_cy/geo.pyx index 7a737e2..725bd25 100644 --- a/src/h3/_cy/geo.pyx +++ b/src/h3/_cy/geo.pyx @@ -1,5 +1,9 @@ +from libc cimport stdlib +from libc.stdint cimport uint64_t + cimport h3lib -from h3lib cimport bool, H3int +from h3lib cimport bool, H3int, H3Error + from .util cimport ( check_cell, check_edge, @@ -9,11 +13,10 @@ from .util cimport ( deg2coord, coord2deg, ) -from libc cimport stdlib -from libc.stdint cimport uint64_t - from .util import H3ValueError +from .memory cimport H3MemoryManager + cpdef H3int geo_to_h3(double lat, double lng, int res) except 1: cdef: @@ -27,6 +30,9 @@ cpdef H3int geo_to_h3(double lat, double lng, int res) except 1: # todo: just ignoring the error for now, check in the future err = h3lib.latLngToCell(&c, res, &out) + if err: + raise H3ValueError() + return out @@ -39,6 +45,8 @@ cpdef (double, double) h3_to_geo(H3int h) except *: check_cell(h) err = h3lib.cellToLatLng(h, &c) + if err: + raise H3ValueError() return coord2deg(c) @@ -63,6 +71,7 @@ cdef h3lib.GeoLoop make_geoloop(geos, bool lnglat_order=False) except *: gl.numVerts = len(geos) + # todo: need for memory management gl.verts = stdlib.calloc(gl.numVerts, sizeof(h3lib.LatLng)) if lnglat_order: From 12b6370f09dd6d35102bf184fe99caf08bf69523 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 4 Jun 2022 23:18:42 -0700 Subject: [PATCH 033/177] even with the error checking... --- src/h3/_cy/geo.pyx | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/src/h3/_cy/geo.pyx b/src/h3/_cy/geo.pyx index 725bd25..0436184 100644 --- a/src/h3/_cy/geo.pyx +++ b/src/h3/_cy/geo.pyx @@ -160,14 +160,21 @@ def polyfill_polygon(outer, int res, holes=None, bool lnglat_order=False): """ cdef: uint64_t n + H3Error err check_res(res) gp = GeoPolygon(outer, holes=holes, lnglat_order=lnglat_order) - h3lib.maxPolygonToCellsSize(&gp.gp, res, 0, &n) + err = h3lib.maxPolygonToCellsSize(&gp.gp, res, 0, &n) + if err: + raise H3ValueError() + ptr = create_ptr(n) - h3lib.polygonToCells(&gp.gp, res, 0, ptr) + err = h3lib.polygonToCells(&gp.gp, res, 0, ptr) + if err: + raise H3ValueError() + mv = create_mv(ptr, n) return mv From 03a27e71c91870e235f239c334adbde340dea20e Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Mon, 6 Jun 2022 01:11:02 -0700 Subject: [PATCH 034/177] notes --- src/h3/_cy/memory.pxd | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd index 235c06e..afe8b9e 100644 --- a/src/h3/_cy/memory.pxd +++ b/src/h3/_cy/memory.pxd @@ -16,4 +16,11 @@ todo: read: https://cython.readthedocs.io/en/latest/src/tutorial/pxd_files.html todo: should i be allocating with python memory functions? https://cython.readthedocs.io/en/latest/src/tutorial/memory_allocation.html + +## things i'm not happy about with this current situation + +- there's gotta be a cleaner way to create a empty_memory_view() +- abolish any appearance of &thing[0]. (i.e., identical interfaces) +- can i make the interface for all these memory views identical? +- also, what's going on with the segfault stuff when we `.create_mv()` before checking an error? why isn't it robust to that? """ From 95c9affd90a141a1959bf9313aba94bd4ef103bc Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Mon, 6 Jun 2022 19:37:42 -0400 Subject: [PATCH 035/177] Remove more sdist files (#259) * remove scripts/examples/apps * BUILD_FUZZERS OFF * ENABLE_FORMAT off * turn off all the things (and sort options) * mac attack * see if there's a build time difference * back to the future --- CMakeLists.txt | 21 ++++++++++++++++----- MANIFEST.in | 3 --- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 436ea65..85ea71c 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -7,11 +7,22 @@ set(CMAKE_POSITION_INDEPENDENT_CODE ON) set(CMAKE_BUILD_TYPE Release) # Avoid building tooling we won't need for release -set(BUILD_BENCHMARKS OFF CACHE BOOL "" FORCE) -set(BUILD_FILTERS OFF CACHE BOOL "" FORCE) -set(BUILD_GENERATORS OFF CACHE BOOL "" FORCE) -set(BUILD_TESTING OFF CACHE BOOL "" FORCE) -set(ENABLE_DOCS OFF CACHE BOOL "" FORCE) +# See all options with `cmake -LA` in an `h3/build` directory, +# or at https://h3geo.org/docs/next/core-library/compilation-options/ +macro(turn_off option_name) + set(${option_name} OFF CACHE BOOL "" FORCE) +endmacro() +turn_off(BUILD_ALLOC_TESTS) +turn_off(BUILD_BENCHMARKS) +turn_off(BUILD_FILTERS) +turn_off(BUILD_FUZZERS) +turn_off(BUILD_GENERATORS) +turn_off(BUILD_TESTING) +turn_off(ENABLE_COVERAGE) +turn_off(ENABLE_DOCS) +turn_off(ENABLE_FORMAT) +turn_off(ENABLE_LIBFUZZER) +turn_off(ENABLE_LINTING) # Build the core library as static set(BUILD_SHARED_LIBS OFF) diff --git a/MANIFEST.in b/MANIFEST.in index 47de939..6ccde1f 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -19,9 +19,6 @@ include src/h3lib/README.md include src/h3lib/VERSION include src/h3lib/CMakeLists.txt -graft src/h3lib/scripts -graft src/h3lib/examples graft src/h3lib/cmake graft src/h3lib/src/h3lib -graft src/h3lib/src/apps exclude MANIFEST.in From 20a6a29dae19bb22c6b61b24d77f56b70c00d63a Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 28 Jul 2022 15:47:09 -0400 Subject: [PATCH 036/177] New error system (#260) * starting to play around with new error system * move enum to h3lib.pxd * this structure is weird :( * error system gets its own file * go back to using H3ErrorCodes * extern the H3ErrorCodes * remove H3Index in favor of just H3int * " to ' * import ordering * something * exception hierarchy * formatting * errors list * remove H3ResolutionError * remove H3EdgeError * remove H3CellError * remove H3DistanceError * H3FailedError * domain error * H3UnrecognizedException * most of em done * remove H3ValueError * remove some checks * ideas ideas * document what the function raises? * thoughts * lint * one half idea for DRYing (kinda) * potentially make the E_SUCCESS path faster * typos * maple syrup * cimport H3ErrorCodes as ec * clean up * whitespace * clarify cases * trying new error idiom * thanks comment * notes * applied idiom a few times now * alternative idiom? * handling some more potential errors * idioms and ideas * clean * removing check * interesting allocation example * lint * just trying to beat 2.7 for sport right now * works? * bow to lint * using enum values directly! * now that's a hierarchy * remove raise_with_msg * ij funcs * lint * remove some checks * remove err * comment * cleaned up `ring`, and i think i fixed a memory leak bug * think i fixed another memory leak bug * another memory leak bug * memory leaks! * clean * removing some comments * meh * H3Exception shouldn't be appearing as a concrete object * renaming some base exceptions * clean up * don't have a test for this anyway * documented * puttering around * words * backing up this nonsense with an airtight argument * air toight * todos * more words * skepticism * rewording * editing * ordering * tests on the error codes * more error code tests * note * address some comments * we raise! * lint * comments --- src/h3/__init__.py | 25 +++- src/h3/_cy/CMakeLists.txt | 2 + src/h3/_cy/__init__.py | 28 ++++- src/h3/_cy/cells.pyx | 202 ++++++++++++++--------------- src/h3/_cy/edges.pyx | 55 ++++---- src/h3/_cy/error_system.pxd | 3 + src/h3/_cy/error_system.pyx | 231 ++++++++++++++++++++++++++++++++++ src/h3/_cy/geo.pyx | 18 +-- src/h3/_cy/h3lib.pxd | 143 +++++++++++---------- src/h3/_cy/util.pyx | 30 ++--- src/h3/api/_api_template.py | 2 +- tests/test_cells_and_edges.py | 116 +++++++++-------- tests/test_error_codes.py | 67 ++++++++++ tests/test_h3.py | 5 +- tests/test_length_area.py | 10 +- tests/test_polyfill.py | 6 +- 16 files changed, 643 insertions(+), 300 deletions(-) create mode 100644 src/h3/_cy/error_system.pxd create mode 100644 src/h3/_cy/error_system.pyx create mode 100644 tests/test_error_codes.py diff --git a/src/h3/__init__.py b/src/h3/__init__.py index 717f9cb..a507e3b 100644 --- a/src/h3/__init__.py +++ b/src/h3/__init__.py @@ -8,9 +8,26 @@ from .api import basic_str as h3 from ._cy import ( + UnknownH3ErrorCode, + H3BaseException, + + H3GridNavigationError, + H3MemoryError, H3ValueError, - H3CellError, - H3ResolutionError, - H3EdgeError, - H3DistanceError, + + H3FailedError, + H3DomainError, + H3LatLngDomainError, + H3ResDomainError, + H3CellInvalidError, + H3DirEdgeInvalidError, + H3UndirEdgeInvalidError, + H3VertexInvalidError, + H3PentagonError, + H3DuplicateInputError, + H3NotNeighborsError, + H3ResMismatchError, + H3MemoryAllocError, + H3MemoryBoundsError, + H3OptionInvalidError, ) diff --git a/src/h3/_cy/CMakeLists.txt b/src/h3/_cy/CMakeLists.txt index 386557c..57a3b21 100644 --- a/src/h3/_cy/CMakeLists.txt +++ b/src/h3/_cy/CMakeLists.txt @@ -22,6 +22,7 @@ add_cython_file(geo) add_cython_file(cells) add_cython_file(edges) add_cython_file(to_multipoly) +add_cython_file(error_system) # Include pyx and pxd files in distribution for use by Cython API install( @@ -35,6 +36,7 @@ install( h3lib.pxd util.pxd util.pyx + error_system.pyx DESTINATION src/h3/_cy ) diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index bb4dfc0..8496c05 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -70,9 +70,29 @@ from .util import ( hex2int, int2hex, from_iter, +) + +from .error_system import ( + UnknownH3ErrorCode, + H3BaseException, + + H3GridNavigationError, + H3MemoryError, H3ValueError, - H3CellError, - H3ResolutionError, - H3EdgeError, - H3DistanceError, + + H3FailedError, + H3DomainError, + H3LatLngDomainError, + H3ResDomainError, + H3CellInvalidError, + H3DirEdgeInvalidError, + H3UndirEdgeInvalidError, + H3VertexInvalidError, + H3PentagonError, + H3DuplicateInputError, + H3NotNeighborsError, + H3ResMismatchError, + H3MemoryAllocError, + H3MemoryBoundsError, + H3OptionInvalidError, ) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 4453e38..f6abe99 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -1,5 +1,5 @@ cimport h3lib -from .h3lib cimport bool, int64_t, H3int +from .h3lib cimport bool, int64_t, H3int, H3ErrorCodes from libc cimport stdlib from .util cimport ( @@ -11,7 +11,10 @@ from .util cimport ( empty_memory_view, # want to drop this import if possible ) -from .util import H3ValueError, H3ResolutionError +from .error_system cimport ( + check_for_error, + check_for_error_msg, +) # todo: add notes about Cython exception handling @@ -51,17 +54,15 @@ cpdef int distance(H3int h1, H3int h2) except -1: """ cdef: int64_t distance - h3lib.H3Error err check_cell(h1) check_cell(h2) - err = h3lib.gridDistance(h1, h2, &distance) - if err: - # todo: do error handling later - s = 'Cells are too far apart to compute distance: {} and {}' - s = s.format(hex(h1), hex(h2)) - raise H3ValueError(s) + check_for_error( + h3lib.gridDistance(h1, h2, &distance) + ) # todo: should this raise a distance error? + + # s = 'Cells are too far apart to compute distance: {} and {}' return distance @@ -70,17 +71,19 @@ cpdef H3int[:] disk(H3int h, int k): """ cdef: int64_t n - h3lib.H3Error err check_cell(h) check_distance(k) - # ignoring error for now - err = h3lib.maxGridDiskSize(k, &n) + check_for_error( + h3lib.maxGridDiskSize(k, &n) + ) ptr = create_ptr(n) # todo: return a "smart" pointer that knows its length? - err = h3lib.gridDisk(h, k, ptr) # ignoring error again! + + err = h3lib.gridDisk(h, k, ptr) mv = create_mv(ptr, n) + check_for_error(err) # needs to be after, to ensure we clean up memory return mv @@ -94,19 +97,20 @@ cpdef H3int[:] _ring_fallback(H3int h, int k): """ cdef: int64_t n - h3lib.H3Error err check_cell(h) check_distance(k) - err = h3lib.maxGridDiskSize(k, &n) + check_for_error( + h3lib.maxGridDiskSize(k, &n) + ) # array of h3 cells ptr = create_ptr(n) # array of cell distances from `h` dist_ptr = stdlib.calloc(n, sizeof(int)) if dist_ptr is NULL: - raise MemoryError() + raise MemoryError() #todo: H3 memory error? err = h3lib.gridDiskDistances(h, k, ptr, dist_ptr) @@ -119,15 +123,15 @@ cpdef H3int[:] _ring_fallback(H3int h, int k): mv = create_mv(ptr, n) + check_for_error(err) # note: need to move this down here to make sure ptr gets freed + # again, easier with a memory manager object + return mv cpdef H3int[:] ring(H3int h, int k): """ Return cells at grid distance `== k` from `h`. Collection is "hollow" for k >= 1. """ - cdef: - h3lib.H3Error err - check_cell(h) check_distance(k) @@ -136,33 +140,33 @@ cpdef H3int[:] ring(H3int h, int k): err = h3lib.gridRingUnsafe(h, k, ptr) - # if we drop into the failure state, we might be tempted to not create - # this mv, but creating the mv is exactly what guarantees that we'll free - # the memory. context manager would be better here, if we can figure out - # how to do that - mv = create_mv(ptr, n) - - if err: + if err == H3ErrorCodes.E_SUCCESS: + mv = create_mv(ptr, n) + elif err == H3ErrorCodes.E_PENTAGON: + mv = create_mv(ptr, n) # need to create this to guarantee memory is freed. + # better done with a Cython object, i think. mv = _ring_fallback(h, k) + else: + mv = create_mv(ptr, n) # need to create this to guarantee memory is freed. + # definitely better done with a Cython "memory manager" object. + check_for_error(err) return mv cpdef H3int parent(H3int h, res=None) except 0: cdef: H3int parent - h3lib.H3Error err - check_cell(h) + check_cell(h) # todo: do we want to check for validity here? or leave correctness to the user? if res is None: res = resolution(h) - 1 - if res > resolution(h): + + err = h3lib.cellToParent(h, res, &parent) + if err: msg = 'Invalid parent resolution {} for cell {}.' msg = msg.format(res, hex(h)) - raise H3ResolutionError(msg) - - check_res(res) - err = h3lib.cellToParent(h, res, &parent) + check_for_error_msg(err, msg) return parent @@ -170,24 +174,23 @@ cpdef H3int parent(H3int h, res=None) except 0: cpdef H3int[:] children(H3int h, res=None): cdef: H3int child - h3lib.H3Error err int64_t N check_cell(h) if res is None: res = resolution(h) + 1 - if res < resolution(h): + + err = h3lib.cellToChildrenSize(h, res, &N) + if err: msg = 'Invalid child resolution {} for cell {}.' msg = msg.format(res, hex(h)) - raise H3ResolutionError(msg) - - check_res(res) - err = h3lib.cellToChildrenSize(h, res, &N) + check_for_error_msg(err, msg) ptr = create_ptr(N) err = h3lib.cellToChildren(h, res, ptr) mv = create_mv(ptr, N) + check_for_error(err) # needs to be after, to ensure memory is freed! return mv @@ -195,19 +198,17 @@ cpdef H3int[:] children(H3int h, res=None): cpdef H3int center_child(H3int h, res=None) except 0: cdef: H3int child - h3lib.H3Error err check_cell(h) if res is None: res = resolution(h) + 1 - if res < resolution(h): + + err = h3lib.cellToCenterChild(h, res, &child) + if err: msg = 'Invalid child resolution {} for cell {}.' msg = msg.format(res, hex(h)) - raise H3ResolutionError(msg) - - check_res(res) - err = h3lib.cellToCenterChild(h, res, &child) + check_for_error_msg(err, msg) return child @@ -219,8 +220,6 @@ cpdef H3int[:] compact(const H3int[:] hu): # `&hu[0]` **requires** a dereference. For Cython, checking for array # length of zero and returning early seems like the easiest solution. # note: open to better ideas! - cdef: - h3lib.H3Error err if len(hu) == 0: return empty_memory_view() @@ -232,9 +231,8 @@ cpdef H3int[:] compact(const H3int[:] hu): err = h3lib.compactCells(&hu[0], ptr, len(hu)) mv = create_mv(ptr, len(hu)) - if err: - # todo: additional error processing - raise H3ValueError('Could not compact set of hexagons!') + # todo: fix weird error ordering due to memory freeing... + check_for_error(err) return mv @@ -248,7 +246,6 @@ cpdef H3int[:] uncompact(const H3int[:] hc, int res): # length of zero and returning early seems like the easiest solution. # note: open to better ideas! cdef: - h3lib.H3Error err int64_t N if len(hc) == 0: @@ -270,31 +267,30 @@ cpdef H3int[:] uncompact(const H3int[:] hc, int res): ) mv = create_mv(ptr, N) - if err: - raise H3ValueError('Could not uncompact set of hexagons!') + # todo: fix weird error ordering due to memory freeing... + check_for_error(err) return mv cpdef int64_t num_hexagons(int resolution) except -1: - check_res(resolution) cdef: - h3lib.H3Error err int64_t num_cells - err = h3lib.getNumCells(resolution, &num_cells) + check_for_error( + h3lib.getNumCells(resolution, &num_cells) + ) return num_cells cpdef double mean_hex_area(int resolution, unit='km^2') except -1: cdef: - h3lib.H3Error err double area - check_res(resolution) - - err = h3lib.getHexagonAreaAvgKm2(resolution, &area) + check_for_error( + h3lib.getHexagonAreaAvgKm2(resolution, &area) + ) # todo: multiple units convert = { @@ -305,18 +301,15 @@ cpdef double mean_hex_area(int resolution, unit='km^2') except -1: try: area *= convert[unit] except: - raise H3ValueError('Unknown unit: {}'.format(unit)) + raise ValueError('Unknown unit: {}'.format(unit)) return area cpdef double cell_area(H3int h, unit='km^2') except -1: cdef: - h3lib.H3Error err double area - check_cell(h) - if unit == 'rads^2': err = h3lib.cellAreaRads2(h, &area) elif unit == 'km^2': @@ -324,34 +317,35 @@ cpdef double cell_area(H3int h, unit='km^2') except -1: elif unit == 'm^2': err = h3lib.cellAreaM2(h, &area) else: - raise H3ValueError('Unknown unit: {}'.format(unit)) + raise ValueError('Unknown unit: {}'.format(unit)) + + check_for_error(err) return area +cdef could_not_find_line(err, start, end): + msg = "Couldn't find line between cells {} and {}" + msg = msg.format(hex(start), hex(end)) + + check_for_error_msg(err, msg) + cpdef H3int[:] line(H3int start, H3int end): cdef: - h3lib.H3Error err int64_t n - check_cell(start) - check_cell(end) - + # todo: can we segfault here with invalid inputs? + # Can we trust the c library to validate the start/end cells? + # probably applies to all size/work pairs of functions... err = h3lib.gridPathCellsSize(start, end, &n) - if err: - s = "Couldn't find line between cells {} and {}" - s = s.format(hex(start), hex(end)) - raise H3ValueError(s) + could_not_find_line(err, start, end) ptr = create_ptr(n) err = h3lib.gridPathCells(start, end, ptr) mv = create_mv(ptr, n) - if err: - s = "Couldn't find line between cells {} and {}" - s = s.format(hex(start), hex(end)) - raise H3ValueError(s) + could_not_find_line(err, start, end) return mv @@ -360,46 +354,45 @@ cpdef bool is_res_class_iii(H3int h): cpdef H3int[:] get_pentagon_indexes(int res): - cdef: - h3lib.H3Error err - - check_res(res) - n = h3lib.pentagonCount() + # todo note: this is the tricky situation where we need the memory manager ptr = create_ptr(n) err = h3lib.getPentagons(res, ptr) mv = create_mv(ptr, n) + check_for_error(err) + return mv cpdef H3int[:] get_res0_indexes(): - cdef: - h3lib.H3Error err - n = h3lib.res0CellCount() + # todo note: this is the tricky situation where we need the memory manager ptr = create_ptr(n) err = h3lib.getRes0Cells(ptr) mv = create_mv(ptr, n) + check_for_error(err) + return mv cpdef get_faces(H3int h): cdef: - h3lib.H3Error err int n - check_cell(h) - - err = h3lib.maxFaceCount(h, &n) #ignore error for now + check_for_error( + h3lib.maxFaceCount(h, &n) + ) cdef int* ptr = stdlib.calloc(n, sizeof(int)) if (n > 0) and (not ptr): raise MemoryError() - err = h3lib.getIcosahedronFaces(h, ptr) # handle error? + check_for_error( + h3lib.getIcosahedronFaces(h, ptr) + ) faces = ptr faces = {f for f in faces if f >= 0} @@ -410,36 +403,27 @@ cpdef get_faces(H3int h): cpdef (int, int) experimental_h3_to_local_ij(H3int origin, H3int h) except *: cdef: - int flag h3lib.CoordIJ c - check_cell(origin) - check_cell(h) - - flag = h3lib.cellToLocalIj(origin, h, 0, &c) - - if flag != 0: - s = "Couldn't find local (i,j) between cells {} and {}." - s = s.format(hex(origin), hex(h)) - raise H3ValueError(s) + err = h3lib.cellToLocalIj(origin, h, 0, &c) + if err: + msg = "Couldn't find local (i,j) between cells {} and {}." + msg = msg.format(hex(origin), hex(h)) + check_for_error_msg(err, msg) return c.i, c.j cpdef H3int experimental_local_ij_to_h3(H3int origin, int i, int j) except 0: cdef: - int flag h3lib.CoordIJ c H3int out - check_cell(origin) - c.i, c.j = i, j - flag = h3lib.localIjToCell(origin, &c, 0, &out) - - if flag != 0: - s = "Couldn't find cell at local ({},{}) from cell {}." - s = s.format(i, j, hex(origin)) - raise H3ValueError(s) + err = h3lib.localIjToCell(origin, &c, 0, &out) + if err: + msg = "Couldn't find cell at local ({},{}) from cell {}." + msg = msg.format(i, j, hex(origin)) + check_for_error_msg(err, msg) return out diff --git a/src/h3/_cy/edges.pyx b/src/h3/_cy/edges.pyx index 716c96a..2df0795 100644 --- a/src/h3/_cy/edges.pyx +++ b/src/h3/_cy/edges.pyx @@ -2,25 +2,25 @@ cimport h3lib from .h3lib cimport bool, H3int from .util cimport ( - check_cell, - check_edge, - check_res, create_ptr, create_mv, ) -from .util import H3ValueError +from .error_system cimport check_for_error +# todo: make bint cpdef bool are_neighbors(H3int h1, H3int h2): cdef: int out - check_cell(h1) - check_cell(h2) + err = h3lib.areNeighborCells(h1, h2, &out) - error = h3lib.areNeighborCells(h1, h2, &out) - if error != 0: + # note: we are intentionally not raising an error here, and just + # returning false. + # todo: is this choice consistent across the Python and C libs? + if err: return False + return out == 1 @@ -29,16 +29,10 @@ cpdef H3int edge(H3int origin, H3int destination) except *: int neighbor_out H3int out - check_cell(origin) - check_cell(destination) + check_for_error( + h3lib.cellsToDirectedEdge(origin, destination, &out) + ) - error = h3lib.areNeighborCells(origin, destination, &neighbor_out) - if error != 0 or neighbor_out != 1: - s = 'Cells are not neighbors: {} and {}' - s = s.format(hex(origin), hex(destination)) - raise H3ValueError(s) - - h3lib.cellsToDirectedEdge(origin, destination, &out) return out @@ -49,34 +43,36 @@ cpdef H3int edge_origin(H3int e) except 1: cdef: H3int out - # without the check, with an invalid input, the function will just return 0 - check_edge(e) + check_for_error( + h3lib.getDirectedEdgeOrigin(e, &out) + ) - h3lib.getDirectedEdgeOrigin(e, &out) return out cpdef H3int edge_destination(H3int e) except 1: cdef: H3int out - check_edge(e) + check_for_error( + h3lib.getDirectedEdgeDestination(e, &out) + ) - h3lib.getDirectedEdgeDestination(e, &out) return out cpdef (H3int, H3int) edge_cells(H3int e) except *: - check_edge(e) - return edge_origin(e), edge_destination(e) cpdef H3int[:] edges_from_cell(H3int origin): """ Returns the 6 (or 5 for pentagons) directed edges for the given origin cell """ - check_cell(origin) ptr = create_ptr(6) - h3lib.originToDirectedEdges(origin, ptr) + + check_for_error( + h3lib.originToDirectedEdges(origin, ptr) + ) + mv = create_mv(ptr, 6) return mv @@ -86,8 +82,6 @@ cpdef double mean_edge_length(int resolution, unit='km') except -1: cdef: double length - check_res(resolution) - h3lib.getHexagonEdgeLengthAvgKm(resolution, &length) # todo: multiple units @@ -99,7 +93,7 @@ cpdef double mean_edge_length(int resolution, unit='km') except -1: try: length *= convert[unit] except: - raise H3ValueError('Unknown unit: {}'.format(unit)) + raise ValueError('Unknown unit: {}'.format(unit)) return length @@ -107,7 +101,6 @@ cpdef double mean_edge_length(int resolution, unit='km') except -1: cpdef double edge_length(H3int e, unit='km') except -1: cdef: double length - check_edge(e) # todo: maybe kick this logic up to the python level # it might be a little cleaner, because we can do the "switch statement" @@ -120,6 +113,6 @@ cpdef double edge_length(H3int e, unit='km') except -1: elif unit == 'm': h3lib.exactEdgeLengthM(e, &length) else: - raise H3ValueError('Unknown unit: {}'.format(unit)) + raise ValueError('Unknown unit: {}'.format(unit)) return length diff --git a/src/h3/_cy/error_system.pxd b/src/h3/_cy/error_system.pxd new file mode 100644 index 0000000..af8c709 --- /dev/null +++ b/src/h3/_cy/error_system.pxd @@ -0,0 +1,3 @@ +from .h3lib cimport H3Error +cdef check_for_error(H3Error err) +cdef check_for_error_msg(H3Error err, str msg) diff --git a/src/h3/_cy/error_system.pyx b/src/h3/_cy/error_system.pyx new file mode 100644 index 0000000..799e4f2 --- /dev/null +++ b/src/h3/_cy/error_system.pyx @@ -0,0 +1,231 @@ +""" +Exceptions from the h3-py library have three possible sources: + +- the Python code +- the Cython code +- the underlying H3 C library code + +The Python and Cython `h3-py` code will only raise standard Python +built-in exceptions; **no custom** exception classes will be used. + +Conversely, many functions in the H3 C library return a `uint32_t` +error code (aliased as type `H3Error`). +When these errors happen (and `h3-py` can't recover from them internally), +they are passed up to the Python/Cython code, where their +`uint32_t` error values are converted to **custom** Python exception types. +These custom exception classes all inherit from `H3BaseException`. + +There is a 1-1 correspondence between the concrete subclasses of +`H3BaseException` and the H3 C library `H3ErrorCodes` values. +The correspondence is intentional, so that the user can refer to the +H3 C library documentation on these errors. + +The (`uint32_t` <-> Exception) correspondence should be clear from +the names of each error/exception, but the explicit mapping is given by +a dictionary in the code below. + +Note that some "abstract" subclasses of `H3BaseException` are also included to +group the exceptions by type. (We say "abstract" because Python has no easy +way to make true abstract exception classes.) + +These "abstract" exceptions will never be raised directly by `h3-py`, but they +allow the user to catch general groups of errors. +Note that `h3-py` will only ever directly raise +the "concrete" exception classes. + +Summarizing, all exceptions originating from the C library inherit from +`H3BaseException`, which has both "abstract" and "concrete" subclasses. + +**Abstract classes**: + +- H3BaseException +- H3ValueError +- H3MemoryError +- H3GridNavigationError + +**Concrete classes**: + +- H3FailedError +- H3DomainError +- H3LatLngDomainError +- H3ResDomainError +- H3CellInvalidError +- H3DirEdgeInvalidError +- H3UndirEdgeInvalidError +- H3VertexInvalidError +- H3PentagonError +- H3DuplicateInputError +- H3NotNeighborsError +- H3ResMismatchError +- H3MemoryAllocError +- H3MemoryBoundsError +- H3OptionInvalidError + + +# TODO: add tests verifying that concrete exception classes have the right error codes associated with them +""" + +from contextlib import contextmanager + +from .h3lib cimport ( + H3Error, + + # H3ErrorCodes enum values + E_SUCCESS, + E_FAILED, + E_DOMAIN, + E_LATLNG_DOMAIN, + E_RES_DOMAIN, + E_CELL_INVALID, + E_DIR_EDGE_INVALID, + E_UNDIR_EDGE_INVALID, + E_VERTEX_INVALID, + E_PENTAGON, + E_DUPLICATE_INPUT, + E_NOT_NEIGHBORS, + E_RES_MISMATCH, + E_MEMORY, + E_MEMORY_BOUNDS, + E_OPTION_INVALID, +) + +@contextmanager +def _the_error(obj): + """ + Syntactic maple syrup for grouping exception definitions. + The associated `with` statement ends up as a not-half-bad + approximation to a valid sentence fragment. + + This provides sort of a "pretend scope", in that it allows for + block indentation which helps to visually indicate the "scope" + of the `... as e` statement. Just note that Python doesn't treat the + `with` block as a "true" separate scope. + + Note that this doesn't actually do anything context-manager-y, outside + of the variable assignment and block indentation. + """ + yield obj + + +# +# Base exception for C library error codes +# +class H3BaseException(Exception): + """ Base H3 exception class. + + Concrete subclasses of this class correspond to specific + error codes from the C library. + + Base/abstract subclasses will have `h3_error_code = None`, while + concrete subclasses will have `h3_error_code` equal to their associated + C library error code. + """ + h3_error_code = None + + +# +# A few "abstract" exceptions; organizational. +# +with _the_error(H3BaseException) as e: + class H3ValueError(e, ValueError): ... + class H3MemoryError(e, MemoryError): ... + class H3GridNavigationError(e, RuntimeError): ... + + +# +# Concrete exceptions +# +class UnknownH3ErrorCode(H3BaseException): + """ + Indicates that the h3-py Python bindings have received an + unrecognized error code from the C library. + + This should never happen. Please report if you get this error. + + Note that this exception is *outside* of the + H3BaseException class hierarchy. + """ + pass + +with _the_error(H3BaseException) as e: + class H3FailedError(e): ... + +with _the_error(H3GridNavigationError) as e: + class H3PentagonError(e): ... + +with _the_error(H3MemoryError) as e: + class H3MemoryAllocError(e): ... + class H3MemoryBoundsError(e): ... + +with _the_error(H3ValueError) as e: + class H3DomainError(e): ... + class H3LatLngDomainError(e): ... + class H3ResDomainError(e): ... + class H3CellInvalidError(e): ... + class H3DirEdgeInvalidError(e): ... + class H3UndirEdgeInvalidError(e): ... + class H3VertexInvalidError(e): ... + class H3DuplicateInputError(e): ... + class H3NotNeighborsError(e): ... + class H3ResMismatchError(e): ... + class H3OptionInvalidError(e): ... + + +""" +This defines a mapping between uint32_t error codes and concrete Python +exception classes. +Note that we intentionally omit E_SUCCESS, as it isn't an actual error. +""" +error_mapping = { + E_FAILED: H3FailedError, + E_DOMAIN: H3DomainError, + E_LATLNG_DOMAIN: H3LatLngDomainError, + E_RES_DOMAIN: H3ResDomainError, + E_CELL_INVALID: H3CellInvalidError, + E_DIR_EDGE_INVALID: H3DirEdgeInvalidError, + E_UNDIR_EDGE_INVALID: H3UndirEdgeInvalidError, + E_VERTEX_INVALID: H3VertexInvalidError, + E_PENTAGON: H3PentagonError, + E_DUPLICATE_INPUT: H3DuplicateInputError, + E_NOT_NEIGHBORS: H3NotNeighborsError, + E_RES_MISMATCH: H3ResMismatchError, + E_MEMORY: H3MemoryAllocError, + E_MEMORY_BOUNDS: H3MemoryBoundsError, + E_OPTION_INVALID: H3OptionInvalidError, +} + +# Go back and modify the class definitions so that each concrete exception +# stores its associated error code. +for code, ex in error_mapping.items(): + ex.h3_error_code = code + + +# +# Helper functions +# + +# TODO: Move the helpers to util? +# TODO: Unclear how/where to expose these functions. cdef/cpdef? + +cdef code_to_exception(H3Error err): + if err == E_SUCCESS: + return None + elif err in error_mapping: + return error_mapping[err] + else: + raise UnknownH3ErrorCode(err) + +cdef check_for_error(H3Error err): + ex = code_to_exception(err) + if ex: + raise ex + +# todo: There's no easy way to do `*args` in `cdef` functions, but I'm also +# not sure this even needs to be a Cython `cdef` function at all, or that +# any of the other helper functions need to be in Cython. +# todo: Revisit after we've played with this a bit. +# todo: also: maybe the extra messages aren't that much more helpful... +cdef check_for_error_msg(H3Error err, str msg): + ex = code_to_exception(err) + if ex: + raise ex(msg) diff --git a/src/h3/_cy/geo.pyx b/src/h3/_cy/geo.pyx index 7a737e2..b40039b 100644 --- a/src/h3/_cy/geo.pyx +++ b/src/h3/_cy/geo.pyx @@ -12,20 +12,19 @@ from .util cimport ( from libc cimport stdlib from libc.stdint cimport uint64_t -from .util import H3ValueError +from .error_system cimport check_for_error cpdef H3int geo_to_h3(double lat, double lng, int res) except 1: cdef: h3lib.LatLng c H3int out - h3lib.H3Error err - check_res(res) c = deg2coord(lat, lng) - # todo: just ignoring the error for now, check in the future - err = h3lib.latLngToCell(&c, res, &out) + check_for_error( + h3lib.latLngToCell(&c, res, &out) + ) return out @@ -34,11 +33,14 @@ cpdef (double, double) h3_to_geo(H3int h) except *: """Map an H3 cell into its centroid geo-coordinate (lat/lng)""" cdef: h3lib.LatLng c - h3lib.H3Error err check_cell(h) + # todo: think about: if you give this an invalid cell, should it still return a lat/lng? + # idea: safe and unsafe APIs? - err = h3lib.cellToLatLng(h, &c) + check_for_error( + h3lib.cellToLatLng(h, &c) + ) return coord2deg(c) @@ -281,6 +283,6 @@ cpdef double point_dist( elif unit == 'm': d = h3lib.distanceM(&a, &b) else: - raise H3ValueError('Unknown unit: {}'.format(unit)) + raise ValueError('Unknown unit: {}'.format(unit)) return d diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index ba8a4e2..0ff65e3 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -1,23 +1,40 @@ from cpython cimport bool -from libc.stdint cimport uint64_t, int64_t, uint32_t +from libc.stdint cimport uint32_t, uint64_t, int64_t -ctypedef uint64_t H3int -ctypedef uint32_t H3Error -ctypedef basestring H3str +ctypedef basestring H3str # todo: do we really need this str one? -cdef extern from "h3api.h": +cdef extern from 'h3api.h': cdef int H3_VERSION_MAJOR cdef int H3_VERSION_MINOR cdef int H3_VERSION_PATCH - ctypedef uint64_t H3Index + ctypedef uint64_t H3int 'H3Index' + + ctypedef uint32_t H3Error + ctypedef enum H3ErrorCodes: + E_SUCCESS = 0 + E_FAILED = 1 + E_DOMAIN = 2 + E_LATLNG_DOMAIN = 3 + E_RES_DOMAIN = 4 + E_CELL_INVALID = 5 + E_DIR_EDGE_INVALID = 6 + E_UNDIR_EDGE_INVALID = 7 + E_VERTEX_INVALID = 8 + E_PENTAGON = 9 + E_DUPLICATE_INPUT = 10 + E_NOT_NEIGHBORS = 11 + E_RES_MISMATCH = 12 + E_MEMORY = 13 + E_MEMORY_BOUNDS = 14 + E_OPTION_INVALID = 15 ctypedef struct LatLng: double lat # in radians double lng # in radians ctypedef struct CellBoundary: - int num_verts "numVerts" + int num_verts 'numVerts' LatLng verts[10] # MAX_CELL_BNDRY_VERTS ctypedef struct CoordIJ: @@ -25,18 +42,18 @@ cdef extern from "h3api.h": int j ctypedef struct LinkedLatLng: - LatLng data "vertex" + LatLng data 'vertex' LinkedLatLng *next # renaming these for clarity ctypedef struct LinkedGeoLoop: - LinkedLatLng *data "first" - LinkedLatLng *_data_last "last" # not needed in Cython bindings + LinkedLatLng *data 'first' + LinkedLatLng *_data_last 'last' # not needed in Cython bindings LinkedGeoLoop *next ctypedef struct LinkedGeoPolygon: - LinkedGeoLoop *data "first" - LinkedGeoLoop *_data_last "last" # not needed in Cython bindings + LinkedGeoLoop *data 'first' + LinkedGeoLoop *_data_last 'last' # not needed in Cython bindings LinkedGeoPolygon *next ctypedef struct GeoLoop: @@ -48,45 +65,45 @@ cdef extern from "h3api.h": int numHoles GeoLoop *holes - int isValidCell(H3Index h) nogil - int isPentagon(H3Index h) nogil - int isResClassIII(H3Index h) nogil - int isValidDirectedEdge(H3Index edge) nogil + int isValidCell(H3int h) nogil + int isPentagon(H3int h) nogil + int isResClassIII(H3int h) nogil + int isValidDirectedEdge(H3int edge) nogil double degsToRads(double degrees) nogil double radsToDegs(double radians) nogil - int getResolution(H3Index h) nogil - int getBaseCellNumber(H3Index h) nogil + int getResolution(H3int h) nogil + int getBaseCellNumber(H3int h) nogil - H3Error latLngToCell(const LatLng *g, int res, H3Index *out) nogil - H3Error cellToLatLng(H3Index h, LatLng *) nogil - H3Error gridDistance(H3Index h1, H3Index h2, int64_t *distance) nogil + H3Error latLngToCell(const LatLng *g, int res, H3int *out) nogil + H3Error cellToLatLng(H3int h, LatLng *) nogil + H3Error gridDistance(H3int h1, H3int h2, int64_t *distance) nogil H3Error maxGridDiskSize(int k, int64_t *out) nogil # num/out/N? - H3Error gridDisk(H3Index h, int k, H3Index *out) nogil + H3Error gridDisk(H3int h, int k, H3int *out) nogil - H3Error cellToParent( H3Index h, int parentRes, H3Index *parent) nogil - H3Error cellToCenterChild(H3Index h, int childRes, H3Index *child) nogil + H3Error cellToParent( H3int h, int parentRes, H3int *parent) nogil + H3Error cellToCenterChild(H3int h, int childRes, H3int *child) nogil - H3Error cellToChildrenSize(H3Index h, int childRes, int64_t *num) nogil # num/out/N? - H3Error cellToChildren( H3Index h, int childRes, H3Index *children) nogil + H3Error cellToChildrenSize(H3int h, int childRes, int64_t *num) nogil # num/out/N? + H3Error cellToChildren( H3int h, int childRes, H3int *children) nogil H3Error compactCells( - const H3Index *cells_u, - H3Index *cells_c, + const H3int *cells_u, + H3int *cells_c, const int num_u ) nogil H3Error uncompactCellsSize( - const H3Index *cells_c, + const H3int *cells_c, const int64_t num_c, const int res, int64_t *num_u ) nogil H3Error uncompactCells( - const H3Index *cells_c, + const H3int *cells_c, const int num_c, - H3Index *cells_u, + H3int *cells_u, const int num_u, const int res ) nogil @@ -94,70 +111,70 @@ cdef extern from "h3api.h": H3Error getNumCells(int res, int64_t *out) nogil int pentagonCount() nogil int res0CellCount() nogil - H3Error getPentagons(int res, H3Index *out) nogil - H3Error getRes0Cells(H3Index *out) nogil + H3Error getPentagons(int res, H3int *out) nogil + H3Error getRes0Cells(H3int *out) nogil - H3Error gridPathCellsSize(H3Index start, H3Index end, int64_t *size) nogil - H3Error gridPathCells(H3Index start, H3Index end, H3Index *out) nogil + H3Error gridPathCellsSize(H3int start, H3int end, int64_t *size) nogil + H3Error gridPathCells(H3int start, H3int end, H3int *out) nogil H3Error getHexagonAreaAvgKm2(int res, double *out) nogil H3Error getHexagonAreaAvgM2(int res, double *out) nogil - H3Error cellAreaRads2(H3Index h, double *out) nogil - H3Error cellAreaKm2(H3Index h, double *out) nogil - H3Error cellAreaM2(H3Index h, double *out) nogil + H3Error cellAreaRads2(H3int h, double *out) nogil + H3Error cellAreaKm2(H3int h, double *out) nogil + H3Error cellAreaM2(H3int h, double *out) nogil - H3Error maxFaceCount(H3Index h, int *out) nogil - H3Error getIcosahedronFaces(H3Index h3, int *out) nogil + H3Error maxFaceCount(H3int h, int *out) nogil + H3Error getIcosahedronFaces(H3int h3, int *out) nogil - H3Error cellToLocalIj(H3Index origin, H3Index h3, uint32_t mode, CoordIJ *out) nogil - H3Error localIjToCell(H3Index origin, const CoordIJ *ij, uint32_t mode, H3Index *out) nogil + H3Error cellToLocalIj(H3int origin, H3int h3, uint32_t mode, CoordIJ *out) nogil + H3Error localIjToCell(H3int origin, const CoordIJ *ij, uint32_t mode, H3int *out) nogil - H3Error gridDiskDistances(H3Index origin, int k, H3Index *out, int *distances) nogil - H3Error gridRingUnsafe(H3Index origin, int k, H3Index *out) nogil + H3Error gridDiskDistances(H3int origin, int k, H3int *out, int *distances) nogil + H3Error gridRingUnsafe(H3int origin, int k, H3int *out) nogil - H3Error areNeighborCells(H3Index origin, H3Index destination, int *out) nogil - H3Error cellsToDirectedEdge(H3Index origin, H3Index destination, H3Index *out) nogil - H3Error getDirectedEdgeOrigin(H3Index edge, H3Index *out) nogil - H3Error getDirectedEdgeDestination(H3Index edge, H3Index *out) nogil - H3Error originToDirectedEdges(H3Index origin, H3Index *edges) nogil + H3Error areNeighborCells(H3int origin, H3int destination, int *out) nogil + H3Error cellsToDirectedEdge(H3int origin, H3int destination, H3int *out) nogil + H3Error getDirectedEdgeOrigin(H3int edge, H3int *out) nogil + H3Error getDirectedEdgeDestination(H3int edge, H3int *out) nogil + H3Error originToDirectedEdges(H3int origin, H3int *edges) nogil H3Error getHexagonEdgeLengthAvgKm(int res, double *out) nogil H3Error getHexagonEdgeLengthAvgM(int res, double *out) nogil - H3Error exactEdgeLengthRads(H3Index edge, double *out) nogil - H3Error exactEdgeLengthKm(H3Index edge, double *out) nogil - H3Error exactEdgeLengthM(H3Index edge, double *out) nogil + H3Error exactEdgeLengthRads(H3int edge, double *out) nogil + H3Error exactEdgeLengthKm(H3int edge, double *out) nogil + H3Error exactEdgeLengthM(H3int edge, double *out) nogil - H3Error cellToBoundary(H3Index h3, CellBoundary *gp) nogil - H3Error directedEdgeToBoundary(H3Index edge, CellBoundary *gb) nogil + H3Error cellToBoundary(H3int h3, CellBoundary *gp) nogil + H3Error directedEdgeToBoundary(H3int edge, CellBoundary *gb) nogil double distanceRads(const LatLng *a, const LatLng *b) nogil double distanceKm(const LatLng *a, const LatLng *b) nogil double distanceM(const LatLng *a, const LatLng *b) nogil - H3Error cellsToLinkedMultiPolygon(const H3Index *h3Set, const int numHexes, LinkedGeoPolygon *out) + H3Error cellsToLinkedMultiPolygon(const H3int *h3Set, const int numHexes, LinkedGeoPolygon *out) void destroyLinkedMultiPolygon(LinkedGeoPolygon *polygon) H3Error maxPolygonToCellsSize(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t *count) - H3Error polygonToCells(const GeoPolygon *geoPolygon, int res, uint32_t flags, H3Index *out) + H3Error polygonToCells(const GeoPolygon *geoPolygon, int res, uint32_t flags, H3int *out) # ctypedef struct GeoMultiPolygon: # int numPolygons # GeoPolygon *polygons - # int hexRange(H3Index origin, int k, H3Index *out) + # int hexRange(H3int origin, int k, H3int *out) - # int hexRangeDistances(H3Index origin, int k, H3Index *out, int *distances) + # int hexRangeDistances(H3int origin, int k, H3int *out, int *distances) - # int hexRanges(H3Index *h3Set, int length, int k, H3Index *out) + # int hexRanges(H3int *h3Set, int length, int k, H3int *out) - # void h3SetToLinkedGeo(const H3Index *h3Set, const int numHexes, LinkedGeoPolygon *out) + # void h3SetToLinkedGeo(const H3int *h3Set, const int numHexes, LinkedGeoPolygon *out) # void destroyLinkedPolygon(LinkedGeoPolygon *polygon) - # H3Index stringToH3(const char *str) + # H3int stringToH3(const char *str) - # void h3ToString(H3Index h, char *str, size_t sz) + # void h3ToString(H3int h, char *str, size_t sz) - # void getH3IndexesFromUnidirectionalEdge(H3Index edge, H3Index *originDestination) + # void getH3intesFromUnidirectionalEdge(H3int edge, H3int *originDestination) diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index bbb63e4..fff0216 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -4,6 +4,13 @@ from .h3lib cimport H3int, H3str, isValidCell, isValidDirectedEdge cimport h3lib +from .error_system import ( + H3ResDomainError, + H3DomainError, + H3DirEdgeInvalidError, + H3CellInvalidError, +) + cdef h3lib.LatLng deg2coord(double lat, double lng) nogil: cdef: @@ -48,21 +55,6 @@ cpdef H3str int2hex(H3int x): return '{:x}'.format(x) -class H3ValueError(ValueError): - pass - -class H3CellError(H3ValueError): - pass - -class H3EdgeError(H3ValueError): - pass - -class H3ResolutionError(H3ValueError): - pass - -class H3DistanceError(H3ValueError): - pass - cdef check_cell(H3int h): """ Check if valid H3 "cell" (hexagon or pentagon). @@ -78,19 +70,19 @@ cdef check_cell(H3int h): `str` inputs. """ if isValidCell(h) == 0: - raise H3CellError('Integer is not a valid H3 cell: {}'.format(hex(h))) + raise H3CellInvalidError('Integer is not a valid H3 cell: {}'.format(hex(h))) cdef check_edge(H3int e): if isValidDirectedEdge(e) == 0: - raise H3EdgeError('Integer is not a valid H3 edge: {}'.format(hex(e))) + raise H3DirEdgeInvalidError('Integer is not a valid H3 edge: {}'.format(hex(e))) cdef check_res(int res): if (res < 0) or (res > 15): - raise H3ResolutionError(res) + raise H3ResDomainError(res) cdef check_distance(int k): if k < 0: - raise H3DistanceError( + raise H3DomainError( 'Grid distances must be nonnegative. Received: {}'.format(k) ) diff --git a/src/h3/api/_api_template.py b/src/h3/api/_api_template.py index 499c040..fa9082e 100644 --- a/src/h3/api/_api_template.py +++ b/src/h3/api/_api_template.py @@ -254,7 +254,7 @@ class _API_FUNCTIONS(object): path between the cells in the graph formed by connecting adjacent cells. - This function will return an H3ValueError if the + This function will raise an exception if the cells are too far apart to compute the distance. Parameters diff --git a/tests/test_cells_and_edges.py b/tests/test_cells_and_edges.py index a90bb0a..ccca342 100644 --- a/tests/test_cells_and_edges.py +++ b/tests/test_cells_and_edges.py @@ -2,11 +2,12 @@ import h3 import pytest from h3 import ( - H3ValueError, - H3CellError, - H3ResolutionError, - H3EdgeError, - H3DistanceError, + H3FailedError, + H3ResDomainError, + H3DomainError, + H3ResMismatchError, + H3CellInvalidError, + H3NotNeighborsError, ) @@ -61,12 +62,12 @@ def test4(): def test_k_ring_distance(): - with pytest.raises(H3DistanceError): + with pytest.raises(H3DomainError): h3.k_ring('8928308280fffff', -10) def test_hex_ring_distance(): - with pytest.raises(H3DistanceError): + with pytest.raises(H3DomainError): h3.hex_ring('8928308280fffff', -10) @@ -114,7 +115,7 @@ def test8(): assert not h3.h3_is_valid(h_bad) # other methods should validate and raise exception if bad input - with pytest.raises(H3CellError): + with pytest.raises(H3CellInvalidError): h3.h3_get_resolution(h_bad) @@ -130,15 +131,34 @@ def test_parent(): assert h3.h3_to_parent(h, 8) == '8828308281fffff' assert h3.h3_to_parent(h, 9) == h - with pytest.raises(H3ResolutionError): + with pytest.raises(H3ResMismatchError): h3.h3_to_parent(h, 10) +def test_parent_err(): + # Test 1 + h = '8075fffffffffff' # geo_to_h3(0,0,0) + + with pytest.raises(H3ResDomainError): + h3.h3_to_parent(h) + + # Test 2 + try: + h3.h3_to_parent(h) + except Exception as e: + msg = str(e) + + # todo: revist this weird formatting stuff + expected = 'Invalid parent resolution -1 for cell {}.' + expected = expected.format(hex(h3.string_to_h3(h))) + + assert msg == expected + + def test_children(): h = '8928308280fffff' - # one above should raise an exception - with pytest.raises(H3ResolutionError): + with pytest.raises(H3ResDomainError): h3.h3_to_children(h, 8) # same resolution is set of just cell itself @@ -160,7 +180,7 @@ def test_children(): # finest resolution cell should return error for children h = '8f04ccb2c45e225' - with pytest.raises(H3ResolutionError): + with pytest.raises(H3ResDomainError): h3.h3_to_children(h) @@ -168,7 +188,7 @@ def test_center_child(): h = '8928308280fffff' # one above should raise an exception - with pytest.raises(H3ResolutionError): + with pytest.raises(H3ResDomainError): h3.h3_to_center_child(h, 8) # same resolution should be same cell @@ -180,7 +200,7 @@ def test_center_child(): # finest resolution hex should return error for child h = '8f04ccb2c45e225' - with pytest.raises(H3ResolutionError): + with pytest.raises(H3ResDomainError): h3.h3_to_center_child(h) @@ -196,10 +216,14 @@ def test_distance(): def test_distance_error(): + """ Two valid cells, but they are too far apart compute the distance + + todo: make sure this raises a E_TOO_FAR error (when we add it in the future) + """ h1 = '8353b0fffffffff' h2 = '835804fffffffff' - with pytest.raises(H3ValueError): + with pytest.raises(H3FailedError): h3.h3_distance(h1, h2) @@ -351,38 +375,38 @@ def test_edge_boundary(): def test_validation(): h = '8a28308280fffff' # invalid cell - with pytest.raises(H3CellError): + with pytest.raises(H3CellInvalidError): h3.h3_get_base_cell(h) - with pytest.raises(H3CellError): + with pytest.raises(H3CellInvalidError): h3.h3_get_resolution(h) - with pytest.raises(H3CellError): + with pytest.raises(H3CellInvalidError): h3.h3_to_parent(h, 9) - with pytest.raises(H3CellError): + with pytest.raises(H3CellInvalidError): h3.h3_distance(h, h) - with pytest.raises(H3CellError): + with pytest.raises(H3CellInvalidError): h3.k_ring(h, 1) - with pytest.raises(H3CellError): + with pytest.raises(H3CellInvalidError): h3.hex_ring(h, 1) - with pytest.raises(H3CellError): + with pytest.raises(H3CellInvalidError): h3.h3_to_children(h, 11) - with pytest.raises(H3CellError): + with pytest.raises(H3CellInvalidError): h3.compact({h}) - with pytest.raises(H3CellError): + with pytest.raises(H3CellInvalidError): h3.uncompact({h}, 10) def test_validation2(): h = '8928308280fffff' - with pytest.raises(H3ResolutionError): + with pytest.raises(H3ResDomainError): h3.h3_to_children(h, 17) assert not h3.h3_indexes_are_neighbors(h, h) @@ -391,40 +415,37 @@ def test_validation2(): def test_validation_geo(): h = '8a28308280fffff' # invalid cell - with pytest.raises(H3CellError): + with pytest.raises(H3CellInvalidError): h3.h3_to_geo(h) - with pytest.raises(H3ResolutionError): + with pytest.raises(H3ResDomainError): h3.geo_to_h3(0, 0, 17) - with pytest.raises(H3CellError): + with pytest.raises(H3CellInvalidError): h3.h3_to_geo_boundary(h) - with pytest.raises(H3CellError): - h3.h3_indexes_are_neighbors(h, h) + # note: this won't raise an exception on bad input, but it does + # *correctly* say that two invalid indexes are not neighbors + assert not h3.h3_indexes_are_neighbors(h, h) def test_edges(): h = '8928308280fffff' - with pytest.raises(H3ValueError): + with pytest.raises(H3NotNeighborsError): h3.get_h3_unidirectional_edge(h, h) h2 = h3.hex_ring(h, 2).pop() - with pytest.raises(H3ValueError): + with pytest.raises(H3NotNeighborsError): h3.get_h3_unidirectional_edge(h, h2) e_bad = '14928308280ffff1' assert not h3.h3_unidirectional_edge_is_valid(e_bad) - with pytest.raises(H3EdgeError): - h3.get_origin_h3_index_from_unidirectional_edge(e_bad) - - with pytest.raises(H3EdgeError): - h3.get_destination_h3_index_from_unidirectional_edge(e_bad) - - with pytest.raises(H3EdgeError): - h3.get_h3_indexes_from_unidirectional_edge(e_bad) + # note: won't raise an error on bad input + h3.get_origin_h3_index_from_unidirectional_edge(e_bad) + h3.get_destination_h3_index_from_unidirectional_edge(e_bad) + h3.get_h3_indexes_from_unidirectional_edge(e_bad) def test_line(): @@ -523,7 +544,7 @@ def test_uncompact_cell_input(): # inputting a single cell string can raise weird errors. # Ensure we get a reasonably helpful answer - with pytest.raises(H3CellError): + with pytest.raises(H3CellInvalidError): h3.uncompact('8001fffffffffff', 1) @@ -554,13 +575,6 @@ def test_get_res0_indexes(): assert sub < out -def test_get_faces_invalid(): - h = '8a28308280fffff' # invalid cell - - with pytest.raises(H3CellError): - h3.h3_get_faces(h) - - def test_get_faces(): h = '804dfffffffffff' expected = {2, 3, 7, 8, 12} @@ -583,7 +597,9 @@ def test_to_local_ij_error(): # error if we cross a face nb = h3.hex_ring(h, k=2) - with pytest.raises(H3ValueError): + + # todo: should this be the E_TOO_FAR guy? + with pytest.raises(H3FailedError): [h3.experimental_h3_to_local_ij(h, p) for p in nb] # should be fine if we do not cross a face @@ -599,7 +615,7 @@ def test_from_local_ij_error(): baddies = [(1, -1), (-1, 1), (-1, -1)] for i, j in baddies: - with pytest.raises(H3ValueError): + with pytest.raises(H3FailedError): h3.experimental_local_ij_to_h3(h, i, j) # inverting output should give good data diff --git a/tests/test_error_codes.py b/tests/test_error_codes.py new file mode 100644 index 0000000..d8229b3 --- /dev/null +++ b/tests/test_error_codes.py @@ -0,0 +1,67 @@ +import pytest + +import h3 + +# todo: maybe check the `check_for_error` function behavior directly? + + +h3_exceptions = { + # h3.UnknownH3ErrorCode + h3.H3BaseException: None, + + h3.H3GridNavigationError: None, + h3.H3MemoryError: None, + h3.H3ValueError: None, + + h3.H3FailedError: 1, + h3.H3DomainError: 2, + h3.H3LatLngDomainError: 3, + h3.H3ResDomainError: 4, + h3.H3CellInvalidError: 5, + h3.H3DirEdgeInvalidError: 6, + h3.H3UndirEdgeInvalidError: 7, + h3.H3VertexInvalidError: 8, + h3.H3PentagonError: 9, + h3.H3DuplicateInputError: 10, + h3.H3NotNeighborsError: 11, + h3.H3ResMismatchError: 12, + h3.H3MemoryAllocError: 13, + h3.H3MemoryBoundsError: 14, + h3.H3OptionInvalidError: 15, +} + + +def test_error_codes_match(): + """ + Should match the error codes given in `h3api.h.in` in the core C lib. + """ + + for err, code in h3_exceptions.items(): + assert err.h3_error_code == code + + +def test_unknown(): + weird_code = 1234 + + with pytest.raises(h3.UnknownH3ErrorCode) as excinfo: + raise h3.UnknownH3ErrorCode(weird_code) + err = excinfo.value + + assert isinstance(err, h3.UnknownH3ErrorCode) + assert err.args == (weird_code,) + + +def test_atributes(): + # errors always have an `h3_error_code` attribute + for err in h3_exceptions: + x = err.h3_error_code + assert (x is None) or (x > 0) + + # UnknownH3ErrorCode is a bit of a special case + weird_code = 1234 + with pytest.raises(h3.UnknownH3ErrorCode) as excinfo: + raise h3.UnknownH3ErrorCode(weird_code) + err = excinfo.value + + assert err.h3_error_code is None + assert err.args == (weird_code,) diff --git a/tests/test_h3.py b/tests/test_h3.py index 09a1e7d..73b1869 100644 --- a/tests/test_h3.py +++ b/tests/test_h3.py @@ -877,6 +877,7 @@ def test_h3_is_pentagon(): def test_h3_indexes_are_neighbors(): assert h3.h3_indexes_are_neighbors('8928308280fffff', '8928308280bffff') + assert not h3.h3_indexes_are_neighbors('821c07fffffffff', '8928308280fffff') @@ -884,7 +885,7 @@ def test_get_h3_unidirectional_edge(): out = h3.get_h3_unidirectional_edge('8928308280fffff', '8928308280bffff') assert h3.h3_unidirectional_edge_is_valid(out) - with pytest.raises(ValueError): + with pytest.raises(h3.H3NotNeighborsError): h3.get_h3_unidirectional_edge('821c07fffffffff', '8928308280fffff') @@ -982,5 +983,5 @@ def test_h3_line(): assert out == expected - with pytest.raises(ValueError): + with pytest.raises(h3.H3ResMismatchError): h3.h3_line(h1, '8001fffffffffff') diff --git a/tests/test_length_area.py b/tests/test_length_area.py index 8236199..b16ef90 100644 --- a/tests/test_length_area.py +++ b/tests/test_length_area.py @@ -1,8 +1,6 @@ import h3 import pytest -from h3 import H3ValueError - def approx2(a, b): if len(a) != len(b): @@ -103,13 +101,13 @@ def test_bad_units(): assert h3.h3_is_valid(h) assert h3.h3_unidirectional_edge_is_valid(e) - with pytest.raises(H3ValueError): + with pytest.raises(ValueError): h3.cell_area(h, unit='foot-pounds') - with pytest.raises(H3ValueError): - h3.exact_edge_length(h, unit='foot-pounds') + with pytest.raises(ValueError): + h3.exact_edge_length(e, unit='foot-pounds') - with pytest.raises(H3ValueError): + with pytest.raises(ValueError): h3.point_dist((0, 0), (0, 0), unit='foot-pounds') diff --git a/tests/test_polyfill.py b/tests/test_polyfill.py index 7c35bb6..58faaff 100644 --- a/tests/test_polyfill.py +++ b/tests/test_polyfill.py @@ -2,7 +2,7 @@ import h3 import itertools import pytest -from h3 import H3ResolutionError +from h3 import H3ResDomainError def reverse(loop): @@ -211,10 +211,10 @@ def test_resolution(): 'coordinates': [[]], } - with pytest.raises(H3ResolutionError): + with pytest.raises(H3ResDomainError): h3.polyfill(d, -1) - with pytest.raises(H3ResolutionError): + with pytest.raises(H3ResDomainError): h3.polyfill(d, 16) From d12658336bc6d0dad225dedb1a0eb311a1f87010 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 17:33:21 -0700 Subject: [PATCH 037/177] Not sure why, but self.ptr = NULL fixes the bug --- src/h3/_cy/geo.pyx | 16 +++++----------- src/h3/_cy/memory.pyx | 3 +++ 2 files changed, 8 insertions(+), 11 deletions(-) diff --git a/src/h3/_cy/geo.pyx b/src/h3/_cy/geo.pyx index e229bb2..b793670 100644 --- a/src/h3/_cy/geo.pyx +++ b/src/h3/_cy/geo.pyx @@ -169,17 +169,11 @@ def polyfill_polygon(outer, int res, holes=None, bool lnglat_order=False): h3lib.maxPolygonToCellsSize(&gp.gp, res, 0, &n) ) - ptr = create_ptr(n) - err = h3lib.polygonToCells(&gp.gp, res, 0, ptr) - mv = create_mv(ptr, n) - check_for_error(err) - - # todo: I don't understand why this code below breaks the tests. - # hmm = H3MemoryManager(n) - # check_for_error( - # h3lib.polygonToCells(&gp.gp, res, 0, hmm.ptr) - # ) - # mv = hmm.create_mv() + hmm = H3MemoryManager(n) + check_for_error( + h3lib.polygonToCells(&gp.gp, res, 0, hmm.ptr) + ) + mv = hmm.create_mv() return mv diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index 1625bca..df1d38b 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -71,6 +71,8 @@ cdef class H3MemoryManager: self.n = move_nonzeros(self.ptr, self.n) if self.n <= 0: stdlib.free(self.ptr) + self.ptr = NULL + self.n = 0 return empty_memory_view() self.ptr = stdlib.realloc(self.ptr, self.n*sizeof(H3int)) @@ -93,6 +95,7 @@ cdef class H3MemoryManager: # If the pointer is *not* NULL, then this means the MemoryManager # has is still responsible for the memory (it hasn't given the memory away to another object). stdlib.free(self.ptr) + self.ptr = NULL """ From 24eef340b3f03277fc371bc6195dae1fa115d37c Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 17:46:32 -0700 Subject: [PATCH 038/177] remove create_ptr and create_mv --- src/h3/_cy/geo.pyx | 2 -- src/h3/_cy/util.pxd | 6 ------ src/h3/_cy/util.pyx | 22 ++-------------------- 3 files changed, 2 insertions(+), 28 deletions(-) diff --git a/src/h3/_cy/geo.pyx b/src/h3/_cy/geo.pyx index b793670..619ec53 100644 --- a/src/h3/_cy/geo.pyx +++ b/src/h3/_cy/geo.pyx @@ -8,8 +8,6 @@ from .util cimport ( check_cell, check_edge, check_res, - create_ptr, - create_mv, deg2coord, coord2deg, ) diff --git a/src/h3/_cy/util.pxd b/src/h3/_cy/util.pxd index 6a34b75..750316b 100644 --- a/src/h3/_cy/util.pxd +++ b/src/h3/_cy/util.pxd @@ -6,13 +6,7 @@ cdef (double, double) coord2deg(LatLng c) nogil cpdef H3int hex2int(H3str h) except? 0 cpdef H3str int2hex(H3int x) -cdef H3int* create_ptr(size_t n) except? NULL -cdef H3int[:] create_mv(H3int* ptr, size_t n) - - cdef check_cell(H3int h) cdef check_edge(H3int e) cdef check_res(int res) cdef check_distance(int k) - -cdef H3int[:] empty_memory_view() # want to drop this if possible diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index fff0216..de5c298 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -11,6 +11,8 @@ from .error_system import ( H3CellInvalidError, ) +from .memory cimport H3MemoryManager + cdef h3lib.LatLng deg2coord(double lat, double lng) nogil: cdef: @@ -96,26 +98,6 @@ cdef H3int* create_ptr(size_t n) except? NULL: return ptr -cdef H3int[:] create_mv(H3int* ptr, size_t n): - cdef: - array x - - n = move_nonzeros(ptr, n) - if n <= 0: - stdlib.free(ptr) - return empty_memory_view() - - ptr = stdlib.realloc(ptr, n*sizeof(H3int)) - - if ptr is NULL: - raise MemoryError() - - x = ptr - x.callback_free_data = stdlib.free - - return x - - cpdef H3int[:] from_iter(hexes): """ hexes needs to be an iterable that knows its size... or should we have it match the np.fromiter function, which infers if not available? From 85ab47dae517323f6c07030beb6e197a117d635a Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 18:16:58 -0700 Subject: [PATCH 039/177] meh --- src/h3/_cy/memory.pxd | 1 + src/h3/_cy/memory.pyx | 14 +++++++++++ src/h3/_cy/util.pyx | 58 ++++--------------------------------------- 3 files changed, 20 insertions(+), 53 deletions(-) diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd index afe8b9e..bc78c0a 100644 --- a/src/h3/_cy/memory.pxd +++ b/src/h3/_cy/memory.pxd @@ -10,6 +10,7 @@ cdef class H3MemoryManager: cdef int[:] int_mv(size_t n) cdef H3int[:] empty_memory_view() +cdef H3int[:] simple_mv(size_t n) """ todo: read: https://cython.readthedocs.io/en/latest/src/tutorial/pxd_files.html diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index df1d38b..c1e905d 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -56,6 +56,20 @@ cdef H3int[:] empty_memory_view(): return (a)[:0] +cdef H3int[:] simple_mv(size_t n): + if n == 0: + return empty_memory_view() + + ptr = stdlib.calloc(n, sizeof(H3int)) + if not ptr: + raise MemoryError() + + x = ptr + x.callback_free_data = stdlib.free + + return x + + cdef class H3MemoryManager: def __cinit__(self, size_t n): self.n = n diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index de5c298..5eec9cd 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -11,7 +11,11 @@ from .error_system import ( H3CellInvalidError, ) -from .memory cimport H3MemoryManager +from .memory cimport ( + H3MemoryManager, + empty_memory_view, + simple_mv, +) cdef h3lib.LatLng deg2coord(double lat, double lng) nogil: @@ -117,55 +121,3 @@ cpdef H3int[:] from_iter(hexes): x[i] = h return x - - -cdef size_t move_nonzeros(H3int* a, size_t n): - """ Move nonzero elements to front of array `a` of length `n`. - Return the number of nonzero elements. - - Loop invariant: Everything *before* `i` or *after* `j` is "done". - Move `i` and `j` inwards until they equal, and exit. - You can move `i` forward until there's a zero in front of it. - You can move `j` backward until there's a nonzero to the left of it. - Anything to the right of `j` is "junk" that can be reallocated. - - | a | b | 0 | c | d | ... | - ^ ^ - i j - - - | a | b | d | c | d | ... | - ^ ^ - i j - """ - cdef: - size_t i = 0 - size_t j = n - - while i < j: - if a[j-1] == 0: - j -= 1 - continue - - if a[i] != 0: - i += 1 - continue - - # if we're here, we know: - # a[i] == 0 - # a[j-1] != 0 - # i < j - # so we can swap! (actually, move a[j-1] -> a[i]) - a[i] = a[j-1] - j -= 1 - - return i - - -cdef H3int[:] empty_memory_view(): - # there's gotta be a better way to do this... - # create an empty cython.view.array? - cdef: - H3int a[1] - - return (a)[:0] From 4d90557d2465b1b8bb41649a216e346a1837eb40 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 18:22:49 -0700 Subject: [PATCH 040/177] bah --- src/h3/_cy/util.pyx | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index 5eec9cd..96f5626 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -93,7 +93,6 @@ cdef check_distance(int k): ) -## todo: can i turn these two into a context manager? cdef H3int* create_ptr(size_t n) except? NULL: cdef H3int* ptr = stdlib.calloc(n, sizeof(H3int)) if (n > 0) and (not ptr): @@ -101,15 +100,9 @@ cdef H3int* create_ptr(size_t n) except? NULL: return ptr - -cpdef H3int[:] from_iter(hexes): - """ hexes needs to be an iterable that knows its size... - or should we have it match the np.fromiter function, which infers if not available? - """ +cdef H3int[:] foo(size_t n): cdef: array x - size_t n - n = len(hexes) if n == 0: return empty_memory_view() @@ -117,6 +110,20 @@ cpdef H3int[:] from_iter(hexes): x = create_ptr(n) x.callback_free_data = stdlib.free + return x + + +cpdef H3int[:] from_iter(hexes): + """ hexes needs to be an iterable that knows its size... + or should we have it match the np.fromiter function, which infers if not available? + """ + cdef: + # array x # this needs to be commented out to avoid an error + size_t n + n = len(hexes) + + x = foo(n) + for i,h in enumerate(hexes): x[i] = h From b2307b004006d1a1e1955fdeb57843e58fd915ff Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 18:25:59 -0700 Subject: [PATCH 041/177] works! --- src/h3/_cy/memory.pyx | 3 +++ src/h3/_cy/util.pyx | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index c1e905d..9f9bdf3 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -57,6 +57,9 @@ cdef H3int[:] empty_memory_view(): cdef H3int[:] simple_mv(size_t n): + cdef: + array x + if n == 0: return empty_memory_view() diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index 96f5626..5ad36b5 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -122,7 +122,7 @@ cpdef H3int[:] from_iter(hexes): size_t n n = len(hexes) - x = foo(n) + x = simple_mv(n) for i,h in enumerate(hexes): x[i] = h From e945f1fd4c1b106dd4fc1bd08375bab9a343f040 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 18:27:32 -0700 Subject: [PATCH 042/177] clean up --- src/h3/_cy/util.pyx | 26 +------------------------- 1 file changed, 1 insertion(+), 25 deletions(-) diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index 5ad36b5..073841d 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -11,11 +11,7 @@ from .error_system import ( H3CellInvalidError, ) -from .memory cimport ( - H3MemoryManager, - empty_memory_view, - simple_mv, -) +from .memory cimport simple_mv cdef h3lib.LatLng deg2coord(double lat, double lng) nogil: @@ -93,26 +89,6 @@ cdef check_distance(int k): ) -cdef H3int* create_ptr(size_t n) except? NULL: - cdef H3int* ptr = stdlib.calloc(n, sizeof(H3int)) - if (n > 0) and (not ptr): - raise MemoryError() - - return ptr - -cdef H3int[:] foo(size_t n): - cdef: - array x - - if n == 0: - return empty_memory_view() - - x = create_ptr(n) - x.callback_free_data = stdlib.free - - return x - - cpdef H3int[:] from_iter(hexes): """ hexes needs to be an iterable that knows its size... or should we have it match the np.fromiter function, which infers if not available? From e8b245747deade1b4ef0068861326c3243023123 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 18:29:21 -0700 Subject: [PATCH 043/177] works --- src/h3/_cy/util.pyx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index 073841d..76779e0 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -96,9 +96,8 @@ cpdef H3int[:] from_iter(hexes): cdef: # array x # this needs to be commented out to avoid an error size_t n - n = len(hexes) - x = simple_mv(n) + x = simple_mv(len(hexes)) for i,h in enumerate(hexes): x[i] = h From 8d2acb90c0343c61af8525cb3ba40003d70bba72 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 18:32:40 -0700 Subject: [PATCH 044/177] clean --- src/h3/_cy/util.pyx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index 76779e0..976fac0 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -93,9 +93,7 @@ cpdef H3int[:] from_iter(hexes): """ hexes needs to be an iterable that knows its size... or should we have it match the np.fromiter function, which infers if not available? """ - cdef: - # array x # this needs to be commented out to avoid an error - size_t n + # cdef array x # this needs to be commented out to avoid an error x = simple_mv(len(hexes)) From 7307e97ca51847490067a9591e1319c3a818bb01 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 18:35:25 -0700 Subject: [PATCH 045/177] maybe we don't need this? --- src/h3/_cy/memory.pyx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index 9f9bdf3..989a0e0 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -57,8 +57,8 @@ cdef H3int[:] empty_memory_view(): cdef H3int[:] simple_mv(size_t n): - cdef: - array x + # cdef: + # array x if n == 0: return empty_memory_view() From 28dc3698b206f5b97875ced65e0dc76a6a26ff04 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 18:36:06 -0700 Subject: [PATCH 046/177] comments --- src/h3/_cy/cells.pyx | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 4abcbe1..19b910c 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -225,8 +225,6 @@ cpdef H3int[:] compact(const H3int[:] hu): h3lib.compactCells(&hu[0], hmm.ptr, n) ) - # todo: mystery: why does this break in the tests when you move it before the error check? - # ideally, the create_mv method would be robust to borked data... mv = hmm.create_mv() return mv From 7afc536caeb9bbae1d6c2f0cd251e09a99501eb2 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 18:36:18 -0700 Subject: [PATCH 047/177] line --- src/h3/_cy/cells.pyx | 1 - 1 file changed, 1 deletion(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 19b910c..d4930a0 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -224,7 +224,6 @@ cpdef H3int[:] compact(const H3int[:] hu): check_for_error( h3lib.compactCells(&hu[0], hmm.ptr, n) ) - mv = hmm.create_mv() return mv From 55c4343396f53bcd23ffc66b1652be9d49e79865 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 18:45:28 -0700 Subject: [PATCH 048/177] nice and clean --- src/h3/_cy/cells.pyx | 6 ++---- src/h3/_cy/geo.pyx | 3 --- src/h3/_cy/memory.pxd | 1 - src/h3/_cy/util.pyx | 2 -- 4 files changed, 2 insertions(+), 10 deletions(-) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index d4930a0..7e961cf 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -1,6 +1,5 @@ cimport h3lib from .h3lib cimport bool, int64_t, H3int, H3ErrorCodes -from libc cimport stdlib from .util cimport ( check_cell, @@ -16,7 +15,6 @@ from .error_system cimport ( from .memory cimport ( H3MemoryManager, int_mv, - empty_memory_view, # todo: want to get rid of this! ) # todo: add notes about Cython exception handling @@ -214,7 +212,7 @@ cpdef H3int[:] compact(const H3int[:] hu): # note: open to better ideas! if len(hu) == 0: - return empty_memory_view() + return H3MemoryManager(0).create_mv() for h in hu: ## todo: should we have an array version? would that be faster? check_cell(h) @@ -242,7 +240,7 @@ cpdef H3int[:] uncompact(const H3int[:] hc, int res): if len(hc) == 0: - return empty_memory_view() + return H3MemoryManager(0).create_mv() for h in hc: check_cell(h) diff --git a/src/h3/_cy/geo.pyx b/src/h3/_cy/geo.pyx index 619ec53..ef77259 100644 --- a/src/h3/_cy/geo.pyx +++ b/src/h3/_cy/geo.pyx @@ -12,9 +12,6 @@ from .util cimport ( coord2deg, ) -from libc cimport stdlib -from libc.stdint cimport uint64_t - from .error_system cimport check_for_error from .memory cimport H3MemoryManager diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd index bc78c0a..8c5b17f 100644 --- a/src/h3/_cy/memory.pxd +++ b/src/h3/_cy/memory.pxd @@ -9,7 +9,6 @@ cdef class H3MemoryManager: cdef int[:] int_mv(size_t n) -cdef H3int[:] empty_memory_view() cdef H3int[:] simple_mv(size_t n) """ diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index 976fac0..b026801 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -1,5 +1,3 @@ -from libc cimport stdlib -from cython.view cimport array from .h3lib cimport H3int, H3str, isValidCell, isValidDirectedEdge cimport h3lib From 7811697188eea571eb4954eee6f875d5d2f1c1ab Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 18:49:01 -0700 Subject: [PATCH 049/177] mv_from_iter should be under memory module --- src/h3/_cy/__init__.py | 5 ++++- src/h3/_cy/memory.pxd | 1 + src/h3/_cy/memory.pyx | 14 ++++++++++++++ src/h3/_cy/util.pyx | 17 ----------------- src/h3/api/basic_int/_binding.py | 2 +- src/h3/api/basic_str/_binding.py | 2 +- 6 files changed, 21 insertions(+), 20 deletions(-) diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index 8496c05..8b83289 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -69,7 +69,10 @@ from .util import ( c_version, hex2int, int2hex, - from_iter, +) + +from .memory import ( + mv_from_iter, ) from .error_system import ( diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd index 8c5b17f..91e6de0 100644 --- a/src/h3/_cy/memory.pxd +++ b/src/h3/_cy/memory.pxd @@ -10,6 +10,7 @@ cdef class H3MemoryManager: cdef int[:] int_mv(size_t n) cdef H3int[:] simple_mv(size_t n) +cpdef H3int[:] mv_from_iter(hexes) """ todo: read: https://cython.readthedocs.io/en/latest/src/tutorial/pxd_files.html diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index 989a0e0..afc353b 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -133,3 +133,17 @@ cdef int[:] int_mv(size_t n): arr.callback_free_data = stdlib.free return arr + + +cpdef H3int[:] mv_from_iter(hexes): + """ hexes needs to be an iterable that knows its size... + or should we have it match the np.fromiter function, which infers if not available? + """ + # cdef array x # this needs to be commented out to avoid an error + + x = simple_mv(len(hexes)) + + for i,h in enumerate(hexes): + x[i] = h + + return x diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index b026801..16c6df4 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -9,9 +9,6 @@ from .error_system import ( H3CellInvalidError, ) -from .memory cimport simple_mv - - cdef h3lib.LatLng deg2coord(double lat, double lng) nogil: cdef: h3lib.LatLng c @@ -85,17 +82,3 @@ cdef check_distance(int k): raise H3DomainError( 'Grid distances must be nonnegative. Received: {}'.format(k) ) - - -cpdef H3int[:] from_iter(hexes): - """ hexes needs to be an iterable that knows its size... - or should we have it match the np.fromiter function, which infers if not available? - """ - # cdef array x # this needs to be commented out to avoid an error - - x = simple_mv(len(hexes)) - - for i,h in enumerate(hexes): - x[i] = h - - return x diff --git a/src/h3/api/basic_int/_binding.py b/src/h3/api/basic_int/_binding.py index a232287..3f46a5a 100644 --- a/src/h3/api/basic_int/_binding.py +++ b/src/h3/api/basic_int/_binding.py @@ -24,7 +24,7 @@ def _id(x): def _in_collection(hexes): it = list(hexes) - return _cy.from_iter(it) + return _cy.mv_from_iter(it) _binding = _API_FUNCTIONS( diff --git a/src/h3/api/basic_str/_binding.py b/src/h3/api/basic_str/_binding.py index 765fdbb..a3c33d4 100644 --- a/src/h3/api/basic_str/_binding.py +++ b/src/h3/api/basic_str/_binding.py @@ -21,7 +21,7 @@ from .._api_template import _API_FUNCTIONS def _in_collection(hexes): it = [_cy.hex2int(h) for h in hexes] - return _cy.from_iter(it) + return _cy.mv_from_iter(it) def _out_unordered(mv): From 8a8813339cafb0fbef880452b21f589502ad62e9 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 18:54:17 -0700 Subject: [PATCH 050/177] move around --- src/h3/_cy/memory.pxd | 1 - src/h3/_cy/memory.pyx | 34 +++++++++++++++++----------------- 2 files changed, 17 insertions(+), 18 deletions(-) diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd index 91e6de0..c733302 100644 --- a/src/h3/_cy/memory.pxd +++ b/src/h3/_cy/memory.pxd @@ -9,7 +9,6 @@ cdef class H3MemoryManager: cdef int[:] int_mv(size_t n) -cdef H3int[:] simple_mv(size_t n) cpdef H3int[:] mv_from_iter(hexes) """ diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index afc353b..d609b73 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -56,23 +56,6 @@ cdef H3int[:] empty_memory_view(): return (a)[:0] -cdef H3int[:] simple_mv(size_t n): - # cdef: - # array x - - if n == 0: - return empty_memory_view() - - ptr = stdlib.calloc(n, sizeof(H3int)) - if not ptr: - raise MemoryError() - - x = ptr - x.callback_free_data = stdlib.free - - return x - - cdef class H3MemoryManager: def __cinit__(self, size_t n): self.n = n @@ -135,6 +118,23 @@ cdef int[:] int_mv(size_t n): return arr +cdef H3int[:] simple_mv(size_t n): + # cdef: + # array x + + if n == 0: + return empty_memory_view() + + ptr = stdlib.calloc(n, sizeof(H3int)) + if not ptr: + raise MemoryError() + + x = ptr + x.callback_free_data = stdlib.free + + return x + + cpdef H3int[:] mv_from_iter(hexes): """ hexes needs to be an iterable that knows its size... or should we have it match the np.fromiter function, which infers if not available? From 11aa2eb14b4a607d18fa8daeb590575b0a4b387a Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 18:58:47 -0700 Subject: [PATCH 051/177] rename to iter_to_mv --- src/h3/_cy/__init__.py | 2 +- src/h3/_cy/cells.pyx | 24 ++++++++++++------------ src/h3/_cy/edges.pyx | 2 +- src/h3/_cy/geo.pyx | 2 +- src/h3/_cy/memory.pxd | 6 +++--- src/h3/_cy/memory.pyx | 4 ++-- src/h3/api/basic_int/_binding.py | 2 +- src/h3/api/basic_str/_binding.py | 2 +- 8 files changed, 22 insertions(+), 22 deletions(-) diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index 8b83289..e61bb4e 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -72,7 +72,7 @@ from .util import ( ) from .memory import ( - mv_from_iter, + iter_to_mv, ) from .error_system import ( diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 7e961cf..2a05cd2 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -84,7 +84,7 @@ cpdef H3int[:] disk(H3int h, int k): check_for_error( h3lib.gridDisk(h, k, hmm.ptr) ) - mv = hmm.create_mv() + mv = hmm.to_mv() return mv @@ -120,7 +120,7 @@ cpdef H3int[:] _ring_fallback(H3int h, int k): if v != k: hmm.ptr[i] = 0 - mv = hmm.create_mv() + mv = hmm.to_mv() return mv @@ -137,7 +137,7 @@ cpdef H3int[:] ring(H3int h, int k): if err: mv = _ring_fallback(h, k) else: - mv = hmm.create_mv() + mv = hmm.to_mv() return mv @@ -178,7 +178,7 @@ cpdef H3int[:] children(H3int h, res=None): check_for_error( h3lib.cellToChildren(h, res, hmm.ptr) ) - mv = hmm.create_mv() + mv = hmm.to_mv() return mv @@ -212,7 +212,7 @@ cpdef H3int[:] compact(const H3int[:] hu): # note: open to better ideas! if len(hu) == 0: - return H3MemoryManager(0).create_mv() + return H3MemoryManager(0).to_mv() for h in hu: ## todo: should we have an array version? would that be faster? check_cell(h) @@ -222,7 +222,7 @@ cpdef H3int[:] compact(const H3int[:] hu): check_for_error( h3lib.compactCells(&hu[0], hmm.ptr, n) ) - mv = hmm.create_mv() + mv = hmm.to_mv() return mv @@ -240,7 +240,7 @@ cpdef H3int[:] uncompact(const H3int[:] hc, int res): if len(hc) == 0: - return H3MemoryManager(0).create_mv() + return H3MemoryManager(0).to_mv() for h in hc: check_cell(h) @@ -261,8 +261,8 @@ cpdef H3int[:] uncompact(const H3int[:] hc, int res): ) # todo: again! doesn't work if i have this before the error check! - # why isn't hmm.create_mv() robust to failures before it? - mv = hmm.create_mv() + # why isn't hmm.to_mv() robust to failures before it? + mv = hmm.to_mv() return mv @@ -341,7 +341,7 @@ cpdef H3int[:] line(H3int start, H3int end): could_not_find_line(err, start, end) # todo: probably here too? - mv = hmm.create_mv() + mv = hmm.to_mv() return mv @@ -356,7 +356,7 @@ cpdef H3int[:] get_pentagon_indexes(int res): check_for_error( h3lib.getPentagons(res, hmm.ptr) ) - mv = hmm.create_mv() + mv = hmm.to_mv() return mv @@ -368,7 +368,7 @@ cpdef H3int[:] get_res0_indexes(): check_for_error( h3lib.getRes0Cells(hmm.ptr) ) - mv = hmm.create_mv() + mv = hmm.to_mv() return mv diff --git a/src/h3/_cy/edges.pyx b/src/h3/_cy/edges.pyx index c3445eb..7f1701e 100644 --- a/src/h3/_cy/edges.pyx +++ b/src/h3/_cy/edges.pyx @@ -66,7 +66,7 @@ cpdef H3int[:] edges_from_cell(H3int origin): hmm = H3MemoryManager(6) h3lib.originToDirectedEdges(origin, hmm.ptr) - mv = hmm.create_mv() + mv = hmm.to_mv() return mv diff --git a/src/h3/_cy/geo.pyx b/src/h3/_cy/geo.pyx index ef77259..f294b12 100644 --- a/src/h3/_cy/geo.pyx +++ b/src/h3/_cy/geo.pyx @@ -168,7 +168,7 @@ def polyfill_polygon(outer, int res, holes=None, bool lnglat_order=False): check_for_error( h3lib.polygonToCells(&gp.gp, res, 0, hmm.ptr) ) - mv = hmm.create_mv() + mv = hmm.to_mv() return mv diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd index c733302..12554fc 100644 --- a/src/h3/_cy/memory.pxd +++ b/src/h3/_cy/memory.pxd @@ -5,11 +5,11 @@ cdef class H3MemoryManager: size_t n H3int* ptr - cdef H3int[:] create_mv(self) + cdef H3int[:] to_mv(self) cdef int[:] int_mv(size_t n) -cpdef H3int[:] mv_from_iter(hexes) +cpdef H3int[:] iter_to_mv(hexes) """ todo: read: https://cython.readthedocs.io/en/latest/src/tutorial/pxd_files.html @@ -22,5 +22,5 @@ https://cython.readthedocs.io/en/latest/src/tutorial/memory_allocation.html - there's gotta be a cleaner way to create a empty_memory_view() - abolish any appearance of &thing[0]. (i.e., identical interfaces) - can i make the interface for all these memory views identical? -- also, what's going on with the segfault stuff when we `.create_mv()` before checking an error? why isn't it robust to that? +- also, what's going on with the segfault stuff when we `.to_mv()` before checking an error? why isn't it robust to that? """ diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index d609b73..6cae150 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -64,7 +64,7 @@ cdef class H3MemoryManager: if (self.n > 0) and (not self.ptr): raise MemoryError() - cdef H3int[:] create_mv(self): + cdef H3int[:] to_mv(self): cdef: array x @@ -135,7 +135,7 @@ cdef H3int[:] simple_mv(size_t n): return x -cpdef H3int[:] mv_from_iter(hexes): +cpdef H3int[:] iter_to_mv(hexes): """ hexes needs to be an iterable that knows its size... or should we have it match the np.fromiter function, which infers if not available? """ diff --git a/src/h3/api/basic_int/_binding.py b/src/h3/api/basic_int/_binding.py index 3f46a5a..adfdb6e 100644 --- a/src/h3/api/basic_int/_binding.py +++ b/src/h3/api/basic_int/_binding.py @@ -24,7 +24,7 @@ def _id(x): def _in_collection(hexes): it = list(hexes) - return _cy.mv_from_iter(it) + return _cy.iter_to_mv(it) _binding = _API_FUNCTIONS( diff --git a/src/h3/api/basic_str/_binding.py b/src/h3/api/basic_str/_binding.py index a3c33d4..e5b563b 100644 --- a/src/h3/api/basic_str/_binding.py +++ b/src/h3/api/basic_str/_binding.py @@ -21,7 +21,7 @@ from .._api_template import _API_FUNCTIONS def _in_collection(hexes): it = [_cy.hex2int(h) for h in hexes] - return _cy.mv_from_iter(it) + return _cy.iter_to_mv(it) def _out_unordered(mv): From bf5fb8a079b46484d6470f24872e831f769b65e1 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 23:25:28 -0700 Subject: [PATCH 052/177] memory allocator options --- src/h3/_cy/geo.pyx | 17 +++++++--- src/h3/_cy/memory.pxd | 3 -- src/h3/_cy/memory.pyx | 74 +++++++++++++++++++++++++++++++++++++------ 3 files changed, 76 insertions(+), 18 deletions(-) diff --git a/src/h3/_cy/geo.pyx b/src/h3/_cy/geo.pyx index f294b12..f6a5221 100644 --- a/src/h3/_cy/geo.pyx +++ b/src/h3/_cy/geo.pyx @@ -1,4 +1,3 @@ -from libc cimport stdlib from libc.stdint cimport uint64_t cimport h3lib @@ -16,6 +15,14 @@ from .error_system cimport check_for_error from .memory cimport H3MemoryManager +# TODO: We might be OK with taking the GIL for the functions in this module +from libc.stdlib cimport ( + # malloc as h3_malloc, # not used + calloc as h3_calloc, + realloc as h3_realloc, + free as h3_free, +) + cpdef H3int geo_to_h3(double lat, double lng, int res) except 1: cdef: @@ -68,7 +75,7 @@ cdef h3lib.GeoLoop make_geoloop(geos, bool lnglat_order=False) except *: gl.numVerts = len(geos) # todo: need for memory management - gl.verts = stdlib.calloc(gl.numVerts, sizeof(h3lib.LatLng)) + gl.verts = h3_calloc(gl.numVerts, sizeof(h3lib.LatLng)) if lnglat_order: latlng = (g[::-1] for g in geos) @@ -82,7 +89,7 @@ cdef h3lib.GeoLoop make_geoloop(geos, bool lnglat_order=False) except *: cdef free_geoloop(h3lib.GeoLoop* gl): - stdlib.free(gl.verts) + h3_free(gl.verts) gl.verts = NULL @@ -115,7 +122,7 @@ cdef class GeoPolygon: self.gp.holes = NULL if len(holes) > 0: - self.gp.holes = stdlib.calloc(len(holes), sizeof(h3lib.GeoLoop)) + self.gp.holes = h3_calloc(len(holes), sizeof(h3lib.GeoLoop)) for i, hole in enumerate(holes): self.gp.holes[i] = make_geoloop(hole, lnglat_order) @@ -126,7 +133,7 @@ cdef class GeoPolygon: for i in range(self.gp.numHoles): free_geoloop(&self.gp.holes[i]) - stdlib.free(self.gp.holes) + h3_free(self.gp.holes) def polyfill_polygon(outer, int res, holes=None, bool lnglat_order=False): diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd index 12554fc..0d1d568 100644 --- a/src/h3/_cy/memory.pxd +++ b/src/h3/_cy/memory.pxd @@ -14,9 +14,6 @@ cpdef H3int[:] iter_to_mv(hexes) """ todo: read: https://cython.readthedocs.io/en/latest/src/tutorial/pxd_files.html -todo: should i be allocating with python memory functions? -https://cython.readthedocs.io/en/latest/src/tutorial/memory_allocation.html - ## things i'm not happy about with this current situation - there's gotta be a cleaner way to create a empty_memory_view() diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index 6cae150..246801a 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -1,7 +1,61 @@ -from libc cimport stdlib from cython.view cimport array from .h3lib cimport H3int +""" +### Memory allocation options + +We have a few options for the memory allocation functions. +There's a trade-off between using the Python allocators which let Python +track memory usage and offers some optimizations vs the system +allocators, which do not need to acquire the GIL. +""" + +""" +System allocation functions. These do not acquire the GIL. +""" +from libc.stdlib cimport ( + # malloc as h3_malloc, # not used + calloc as h3_calloc, + realloc as h3_realloc, + free as h3_free, +) + + +""" +PyMem_Raw* functions should just be wrappers around system allocators +also given in libc.stdlib. These functions do not acquire the GIL. + +Note that these do not have a calloc function until py 3.5 and Cython 3.0, +so we would need to zero-out memory manually. + +https://python.readthedocs.io/en/stable/c-api/memory.html#raw-memory-interface +""" +# from cpython.mem cimport ( +# PyMem_RawMalloc as h3_malloc, +# # PyMem_RawCalloc as h3_calloc, # only in py3.5 (and cython 3.0?) +# PyMem_RawRealloc as h3_realloc, +# PyMem_RawFree as h3_free, +# ) + + +""" +These functions use the Python allocator (instead of the system allocator), +which offers some optimizations for Python, and allows Python to track +memory usage. However, these functions must acquire the GIL. + +Note that these do not have a calloc function until py 3.5 and Cython 3.0, +so we would need to zero-out memory manually. + +https://cython.readthedocs.io/en/stable/src/tutorial/memory_allocation.html +https://python.readthedocs.io/en/stable/c-api/memory.html#memory-interface +""" +# from cpython.mem cimport ( +# PyMem_Malloc as h3_malloc, +# # PyMem_Calloc as h3_calloc, # only in Python >=3.5 (and Cython >=3.0?) +# PyMem_Realloc as h3_realloc, +# PyMem_Free as h3_free, +# ) + cdef size_t move_nonzeros(H3int* a, size_t n): """ Move nonzero elements to front of array `a` of length `n`. @@ -59,7 +113,7 @@ cdef H3int[:] empty_memory_view(): cdef class H3MemoryManager: def __cinit__(self, size_t n): self.n = n - self.ptr = stdlib.calloc(self.n, sizeof(H3int)) + self.ptr = h3_calloc(self.n, sizeof(H3int)) if (self.n > 0) and (not self.ptr): raise MemoryError() @@ -70,18 +124,18 @@ cdef class H3MemoryManager: self.n = move_nonzeros(self.ptr, self.n) if self.n <= 0: - stdlib.free(self.ptr) + h3_free(self.ptr) self.ptr = NULL self.n = 0 return empty_memory_view() - self.ptr = stdlib.realloc(self.ptr, self.n*sizeof(H3int)) + self.ptr = h3_realloc(self.ptr, self.n*sizeof(H3int)) if self.ptr is NULL: raise MemoryError() x = self.ptr - x.callback_free_data = stdlib.free + x.callback_free_data = h3_free # responsibility for the memory moves from this object to the array/memoryview self.ptr = NULL @@ -94,7 +148,7 @@ cdef class H3MemoryManager: # should be NULL, and deallocing on NULL is fine. # If the pointer is *not* NULL, then this means the MemoryManager # has is still responsible for the memory (it hasn't given the memory away to another object). - stdlib.free(self.ptr) + h3_free(self.ptr) self.ptr = NULL @@ -108,12 +162,12 @@ cdef int[:] int_mv(size_t n): if n <= 0: raise MemoryError() - ptr = stdlib.calloc(n, sizeof(int)) + ptr = h3_calloc(n, sizeof(int)) if ptr is NULL: raise MemoryError() arr = ptr - arr.callback_free_data = stdlib.free + arr.callback_free_data = h3_free return arr @@ -125,12 +179,12 @@ cdef H3int[:] simple_mv(size_t n): if n == 0: return empty_memory_view() - ptr = stdlib.calloc(n, sizeof(H3int)) + ptr = h3_calloc(n, sizeof(H3int)) if not ptr: raise MemoryError() x = ptr - x.callback_free_data = stdlib.free + x.callback_free_data = h3_free return x From b8f53dbd805bea299c2307dcfa67cfae7c130ffb Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 23:46:07 -0700 Subject: [PATCH 053/177] _remove_zeros helper method --- src/h3/_cy/memory.pxd | 2 ++ src/h3/_cy/memory.pyx | 18 ++++++++++-------- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd index 0d1d568..685059c 100644 --- a/src/h3/_cy/memory.pxd +++ b/src/h3/_cy/memory.pxd @@ -6,11 +6,13 @@ cdef class H3MemoryManager: H3int* ptr cdef H3int[:] to_mv(self) + cdef _remove_zeros(self) # not sure i really want this exposed here cdef int[:] int_mv(size_t n) cpdef H3int[:] iter_to_mv(hexes) + """ todo: read: https://cython.readthedocs.io/en/latest/src/tutorial/pxd_files.html diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index 246801a..f5619e2 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -118,22 +118,25 @@ cdef class H3MemoryManager: if (self.n > 0) and (not self.ptr): raise MemoryError() - cdef H3int[:] to_mv(self): - cdef: - array x - + cdef _remove_zeros(self): self.n = move_nonzeros(self.ptr, self.n) if self.n <= 0: h3_free(self.ptr) self.ptr = NULL self.n = 0 - return empty_memory_view() self.ptr = h3_realloc(self.ptr, self.n*sizeof(H3int)) - - if self.ptr is NULL: + if not self.ptr: raise MemoryError() + cdef H3int[:] to_mv(self): + cdef: + array x + + self._remove_zeros() + if self.n == 0: + return empty_memory_view() + x = self.ptr x.callback_free_data = h3_free @@ -149,7 +152,6 @@ cdef class H3MemoryManager: # If the pointer is *not* NULL, then this means the MemoryManager # has is still responsible for the memory (it hasn't given the memory away to another object). h3_free(self.ptr) - self.ptr = NULL """ From e1f56db442d784db854283ba8f1e56c864ad0383 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Jul 2022 23:55:59 -0700 Subject: [PATCH 054/177] little cleanup --- src/h3/_cy/memory.pxd | 1 - src/h3/_cy/memory.pyx | 29 +++++++++++++++++------------ 2 files changed, 17 insertions(+), 13 deletions(-) diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd index 685059c..68d6380 100644 --- a/src/h3/_cy/memory.pxd +++ b/src/h3/_cy/memory.pxd @@ -6,7 +6,6 @@ cdef class H3MemoryManager: H3int* ptr cdef H3int[:] to_mv(self) - cdef _remove_zeros(self) # not sure i really want this exposed here cdef int[:] int_mv(size_t n) diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index f5619e2..f2837ce 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -110,6 +110,21 @@ cdef H3int[:] empty_memory_view(): return (a)[:0] +cdef (H3int*, size_t) _remove_zeros(H3int* ptr, size_t n): + n = move_nonzeros(ptr, n) + if n <= 0: + h3_free(ptr) + ptr = NULL + n = 0 + + ptr = h3_realloc(ptr, n*sizeof(H3int)) + if not ptr: + raise MemoryError() + + return ptr, n + + + cdef class H3MemoryManager: def __cinit__(self, size_t n): self.n = n @@ -118,22 +133,12 @@ cdef class H3MemoryManager: if (self.n > 0) and (not self.ptr): raise MemoryError() - cdef _remove_zeros(self): - self.n = move_nonzeros(self.ptr, self.n) - if self.n <= 0: - h3_free(self.ptr) - self.ptr = NULL - self.n = 0 - - self.ptr = h3_realloc(self.ptr, self.n*sizeof(H3int)) - if not self.ptr: - raise MemoryError() - cdef H3int[:] to_mv(self): cdef: array x - self._remove_zeros() + self.ptr, self.n = _remove_zeros(self.ptr, self.n) + if self.n == 0: return empty_memory_view() From bfa13ed6d172f1c19cf86f10cea5d669dbf26fe5 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 31 Jul 2022 00:04:46 -0700 Subject: [PATCH 055/177] add method: _create_mv --- src/h3/_cy/memory.pxd | 1 + src/h3/_cy/memory.pyx | 14 +++++++++++--- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd index 68d6380..672c8f2 100644 --- a/src/h3/_cy/memory.pxd +++ b/src/h3/_cy/memory.pxd @@ -6,6 +6,7 @@ cdef class H3MemoryManager: H3int* ptr cdef H3int[:] to_mv(self) + cdef H3int[:] _create_mv(self) cdef int[:] int_mv(size_t n) diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index f2837ce..f17b323 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -123,22 +123,26 @@ cdef (H3int*, size_t) _remove_zeros(H3int* ptr, size_t n): return ptr, n +""" +TODO: think about the case when n=0 +"Requesting zero elements or elements of size zero bytes returns a distinct non-NULL pointer if possible, as if PyMem_RawCalloc(1, 1) had been called instead." +do we not actually need to special case it? +""" cdef class H3MemoryManager: def __cinit__(self, size_t n): self.n = n self.ptr = h3_calloc(self.n, sizeof(H3int)) + # todo: avoid n=0 special case because of allocation non-null pointer guarantee? if (self.n > 0) and (not self.ptr): raise MemoryError() - cdef H3int[:] to_mv(self): + cdef H3int[:] _create_mv(self): cdef: array x - self.ptr, self.n = _remove_zeros(self.ptr, self.n) - if self.n == 0: return empty_memory_view() @@ -151,6 +155,10 @@ cdef class H3MemoryManager: return x + cdef H3int[:] to_mv(self): + self.ptr, self.n = _remove_zeros(self.ptr, self.n) + return self._create_mv() + def __dealloc__(self): # If the memory has been handed off to a memoryview, this pointer # should be NULL, and deallocing on NULL is fine. From 49e114732b636d7217639729d63715a7829bf224 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 31 Jul 2022 00:10:27 -0700 Subject: [PATCH 056/177] don't need the n==0 case --- src/h3/_cy/memory.pyx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index f17b323..073d7e2 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -112,7 +112,7 @@ cdef H3int[:] empty_memory_view(): cdef (H3int*, size_t) _remove_zeros(H3int* ptr, size_t n): n = move_nonzeros(ptr, n) - if n <= 0: + if n == 0: h3_free(ptr) ptr = NULL n = 0 @@ -135,8 +135,7 @@ cdef class H3MemoryManager: self.n = n self.ptr = h3_calloc(self.n, sizeof(H3int)) - # todo: avoid n=0 special case because of allocation non-null pointer guarantee? - if (self.n > 0) and (not self.ptr): + if not self.ptr: raise MemoryError() cdef H3int[:] _create_mv(self): From 865326af426f81fcda484190df07eed52841e845 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 31 Jul 2022 00:10:51 -0700 Subject: [PATCH 057/177] another comment on n==0 --- src/h3/_cy/memory.pyx | 6 ------ 1 file changed, 6 deletions(-) diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index 073d7e2..d6496ab 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -123,12 +123,6 @@ cdef (H3int*, size_t) _remove_zeros(H3int* ptr, size_t n): return ptr, n -""" -TODO: think about the case when n=0 -"Requesting zero elements or elements of size zero bytes returns a distinct non-NULL pointer if possible, as if PyMem_RawCalloc(1, 1) had been called instead." -do we not actually need to special case it? - -""" cdef class H3MemoryManager: def __cinit__(self, size_t n): From 2d8f4167eab26615136e1b8bd1d52285252feded Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 31 Jul 2022 00:15:41 -0700 Subject: [PATCH 058/177] mv is better than x --- src/h3/_cy/memory.pyx | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index d6496ab..dbdb6f1 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -134,19 +134,19 @@ cdef class H3MemoryManager: cdef H3int[:] _create_mv(self): cdef: - array x + array mv if self.n == 0: return empty_memory_view() - x = self.ptr - x.callback_free_data = h3_free + mv = self.ptr + mv.callback_free_data = h3_free # responsibility for the memory moves from this object to the array/memoryview self.ptr = NULL self.n = 0 - return x + return mv cdef H3int[:] to_mv(self): self.ptr, self.n = _remove_zeros(self.ptr, self.n) @@ -182,7 +182,7 @@ cdef int[:] int_mv(size_t n): cdef H3int[:] simple_mv(size_t n): # cdef: - # array x + # array mv if n == 0: return empty_memory_view() @@ -191,10 +191,10 @@ cdef H3int[:] simple_mv(size_t n): if not ptr: raise MemoryError() - x = ptr - x.callback_free_data = h3_free + mv = ptr + mv.callback_free_data = h3_free - return x + return mv cpdef H3int[:] iter_to_mv(hexes): @@ -203,9 +203,9 @@ cpdef H3int[:] iter_to_mv(hexes): """ # cdef array x # this needs to be commented out to avoid an error - x = simple_mv(len(hexes)) + mv = simple_mv(len(hexes)) for i,h in enumerate(hexes): - x[i] = h + mv[i] = h - return x + return mv From 3b3f9272f46f351ebc9d8cbd66803810a472c3d8 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 31 Jul 2022 00:33:56 -0700 Subject: [PATCH 059/177] organize --- src/h3/_cy/memory.pxd | 4 +++- src/h3/_cy/memory.pyx | 26 +++++++++++--------------- 2 files changed, 14 insertions(+), 16 deletions(-) diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd index 672c8f2..4f10c05 100644 --- a/src/h3/_cy/memory.pxd +++ b/src/h3/_cy/memory.pxd @@ -6,7 +6,10 @@ cdef class H3MemoryManager: H3int* ptr cdef H3int[:] to_mv(self) + + # private methods cdef H3int[:] _create_mv(self) + cdef _remove_zeros(self) cdef int[:] int_mv(size_t n) @@ -18,7 +21,6 @@ todo: read: https://cython.readthedocs.io/en/latest/src/tutorial/pxd_files.html ## things i'm not happy about with this current situation -- there's gotta be a cleaner way to create a empty_memory_view() - abolish any appearance of &thing[0]. (i.e., identical interfaces) - can i make the interface for all these memory views identical? - also, what's going on with the segfault stuff when we `.to_mv()` before checking an error? why isn't it robust to that? diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index dbdb6f1..b02c5f0 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -110,20 +110,6 @@ cdef H3int[:] empty_memory_view(): return (a)[:0] -cdef (H3int*, size_t) _remove_zeros(H3int* ptr, size_t n): - n = move_nonzeros(ptr, n) - if n == 0: - h3_free(ptr) - ptr = NULL - n = 0 - - ptr = h3_realloc(ptr, n*sizeof(H3int)) - if not ptr: - raise MemoryError() - - return ptr, n - - cdef class H3MemoryManager: def __cinit__(self, size_t n): self.n = n @@ -132,6 +118,16 @@ cdef class H3MemoryManager: if not self.ptr: raise MemoryError() + cdef _remove_zeros(self): + self.n = move_nonzeros(self.ptr, self.n) + if self.n == 0: + h3_free(self.ptr) + self.ptr = NULL + + self.ptr = h3_realloc(self.ptr, self.n*sizeof(H3int)) + if not self.ptr: + raise MemoryError() + cdef H3int[:] _create_mv(self): cdef: array mv @@ -149,7 +145,7 @@ cdef class H3MemoryManager: return mv cdef H3int[:] to_mv(self): - self.ptr, self.n = _remove_zeros(self.ptr, self.n) + self._remove_zeros() return self._create_mv() def __dealloc__(self): From 50c649c6b62b3ba77966b11f439cab178a8c8684 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 31 Jul 2022 00:43:26 -0700 Subject: [PATCH 060/177] avoiding superfluous methods in the memory manager, because I'm not sure there's a way to make them private --- src/h3/_cy/memory.pxd | 5 ---- src/h3/_cy/memory.pyx | 59 +++++++++++++++++++++++-------------------- 2 files changed, 31 insertions(+), 33 deletions(-) diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd index 4f10c05..31aecd0 100644 --- a/src/h3/_cy/memory.pxd +++ b/src/h3/_cy/memory.pxd @@ -7,11 +7,6 @@ cdef class H3MemoryManager: cdef H3int[:] to_mv(self) - # private methods - cdef H3int[:] _create_mv(self) - cdef _remove_zeros(self) - - cdef int[:] int_mv(size_t n) cpdef H3int[:] iter_to_mv(hexes) diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index b02c5f0..0e406b4 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -110,43 +110,46 @@ cdef H3int[:] empty_memory_view(): return (a)[:0] +cdef _remove_zeros(H3MemoryManager x): + x.n = move_nonzeros(x.ptr, x.n) + if x.n == 0: + h3_free(x.ptr) + x.ptr = NULL + + x.ptr = h3_realloc(x.ptr, x.n*sizeof(H3int)) + if not x.ptr: + raise MemoryError() + + +cdef H3int[:] _create_mv(H3MemoryManager x): + cdef: + array mv + + if x.n == 0: + return empty_memory_view() + + mv = x.ptr + mv.callback_free_data = h3_free + + # responsibility for the memory moves from this object to the array/memoryview + x.ptr = NULL + x.n = 0 + + return mv + + cdef class H3MemoryManager: def __cinit__(self, size_t n): self.n = n self.ptr = h3_calloc(self.n, sizeof(H3int)) + # todo: do we actually have a memory leak when n = 0 because of the non-null pointer thing? if not self.ptr: raise MemoryError() - cdef _remove_zeros(self): - self.n = move_nonzeros(self.ptr, self.n) - if self.n == 0: - h3_free(self.ptr) - self.ptr = NULL - - self.ptr = h3_realloc(self.ptr, self.n*sizeof(H3int)) - if not self.ptr: - raise MemoryError() - - cdef H3int[:] _create_mv(self): - cdef: - array mv - - if self.n == 0: - return empty_memory_view() - - mv = self.ptr - mv.callback_free_data = h3_free - - # responsibility for the memory moves from this object to the array/memoryview - self.ptr = NULL - self.n = 0 - - return mv - cdef H3int[:] to_mv(self): - self._remove_zeros() - return self._create_mv() + _remove_zeros(self) + return _create_mv(self) def __dealloc__(self): # If the memory has been handed off to a memoryview, this pointer From 6462bf78a3fc28e8d3ab9d37418212e5e3f19ae6 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Tue, 23 Aug 2022 02:31:19 -0400 Subject: [PATCH 061/177] Merge `dev_v4` into `master` (#250) * WIP: Starting work on v4, The Sequel (#238) * cimport for h3fake2 doesn't seem to work * back to where we were * meh, close to what i was hoping for * h3fake2 in github actions * comment out current bindings that consume the h3c v3 library * don't need the coveragerc file at the moment; clear out c files in /tests * sdist needs h3fake2 * try CIBW_BEFORE_BUILD to get h3fake2 * need h3fake2 for cibuildwheel tests * update h3 C library * comment out most of h3lib.pxd * calling from v4 c lib works! (tests dont' work yet tho) * tests shall pass * starting to move over first few functions * little steps * util submodule fully moved over; some hackery with h3fake2 errors * getting even trickier with h3fake2 errors * few more simple functions * geo_to_h3 and h3_to_geo * grid_distance function * grid_disk * parents and kids * compact/uncompact * getNumCells * comment out sdist test temporarily * commenting out `make_sdist` seems to have turned off the other CI jobs * no, it was that we're pushing to the dev branch * keep the sdist job in there, but commented out * ajfriend/more v4 funcs (#241) * get_pentagon_indexes and get_res0_indexes * line * cell area functions * get_faces (#248) * initial pass * thoughts * the results of thinking * this commit is associated with the previous commits * nogil * i'm a bill * remove the typical nonsense * v4: local ij functions to v4 cython (#240) * move local ij functions to v4 implementation * revert some changes and add gridPathCells * swap implementation * revert gridPathCells * ring (#251) * Uncomment cython example, and exclude sdist from wheels test temporarilty (#252) * uncomment cython test * exclude make_sdist temporarily from the wheels tests * v4: polygonToCells (#254) * v4: geo boundary, set to multi polygon (#255) * v4: cell boundary * v4: h3_set_to_multi_polygon * v4: convert edge from h3fake2 (#253) * v4: convert edge from h3fake2 * on error not neighbors * except * * check for neighbor error * Fix sdist build (#239) * make sure `make_sdist` CI job still broken * reproduce locally * update h3lib * still seems broken * try sdist on mac and ubuntu * pyest! * debugging * ensurepath * Disable building docs * just build sdist once * colon Co-authored-by: Isaac Brodsky * remove h3fake2 transitional library (#257) * Remove more sdist files (#259) * remove scripts/examples/apps * BUILD_FUZZERS OFF * ENABLE_FORMAT off * turn off all the things (and sort options) * mac attack * see if there's a build time difference * back to the future * New error system (#260) * starting to play around with new error system * move enum to h3lib.pxd * this structure is weird :( * error system gets its own file * go back to using H3ErrorCodes * extern the H3ErrorCodes * remove H3Index in favor of just H3int * " to ' * import ordering * something * exception hierarchy * formatting * errors list * remove H3ResolutionError * remove H3EdgeError * remove H3CellError * remove H3DistanceError * H3FailedError * domain error * H3UnrecognizedException * most of em done * remove H3ValueError * remove some checks * ideas ideas * document what the function raises? * thoughts * lint * one half idea for DRYing (kinda) * potentially make the E_SUCCESS path faster * typos * maple syrup * cimport H3ErrorCodes as ec * clean up * whitespace * clarify cases * trying new error idiom * thanks comment * notes * applied idiom a few times now * alternative idiom? * handling some more potential errors * idioms and ideas * clean * removing check * interesting allocation example * lint * just trying to beat 2.7 for sport right now * works? * bow to lint * using enum values directly! * now that's a hierarchy * remove raise_with_msg * ij funcs * lint * remove some checks * remove err * comment * cleaned up `ring`, and i think i fixed a memory leak bug * think i fixed another memory leak bug * another memory leak bug * memory leaks! * clean * removing some comments * meh * H3Exception shouldn't be appearing as a concrete object * renaming some base exceptions * clean up * don't have a test for this anyway * documented * puttering around * words * backing up this nonsense with an airtight argument * air toight * todos * more words * skepticism * rewording * editing * ordering * tests on the error codes * more error code tests * note * address some comments * we raise! * lint * comments * Squash #261: Use new H3MemoryManager system (#268) * Squash #261: Use new H3MemoryManager system Co-authored-by: AJ Friend * add some error checks * comments * comments * clearer logical flow * arrays are different from memoryviews! * little cleaner * Revert "comments" This reverts commit 80c3f4d38213bae0b497db702233bc2ee5bb2f2e. * Revert "Revert "comments"" This reverts commit a9d6590b04eeeffedf765c9011ae5e20484a8651. * Revert "comments" This reverts commit 24904bdceaec46417a39df271b3b7e77ea7cbfcc. * comments * arrays are different from memoryviews! * try _copy_to_mv * i don't get enough opportunities to consider using the word "penultimate" * ugh, and there i go using it incorrectly... * hmmm. was this really all it was? * That's what it was! This reverts commit 7e72adb59036fd783eaa452ba05f9a65fbaae591. * clarify branches * remove simple_mv * moving around * clean up * comments * comments * comments Co-authored-by: Isaac Brodsky * remove: from h3 import h3 (#270) * is_valid_cell (#269) * Remove alias functions (#271) * remove alias function hex_range * note test_k_ring and test_hex_range are the same * remove test_hex_range * duplicate tests * remove test_hex_range2 * same test * remove test_hex_range_pentagon * remove alias: k_ring_distances * tests are the same! * same test * combine tests * remove alias: h3_is_res_class_iii * lint * Update most functions to v4.0 names (#272) * grid_distance * cell_to_parent * get_resolution * is_pentagon * is_res_class_III * get_pentagons * get_res0_cells * get_base_cell_number * compact and uncompact * get_faces * cell_to_boundary * cell_to_latlng * latlng_to_cell * cell_to_children * int_to_string and string_to_int * cell_to_center_child * moving things around * is_valid_directed_edge * grid_path_cells * moving around * cells_to_multi_polygon * are_neighbor_cells * cell_to_local_ij and local_ij_to_cell * get_icosahedron_faces * great_circle_distance * get_num_cells * note * remove hex_range_distances and hex_ranges (easily implementable by user) * grid_ring * grid_disk * moving around * origin_to_directed_edges * directed_edge_to_boundary * cells_to_directed_edge * directed_edge_to_cells * todo: directedEdgeToCells * get_directed_edge_origin * get_directed_edge_destination * grouping functions * more grouping * _binding to _b * todos * average_hexagon_area * average_edge_length * average_edge_length and edge_length * average_hexagon_edge_length * ordering * more ordering * Get the makefile working on Linux (#274) * bump core lib to 4.0 rc5 (#275) * bump core lib to 4.0 rc5 * more pythonic names for string<->int conversion functions * cython hex2int to str_to_int to match the python functions * better argument names for great_circle_distance * great_circle_distance comments * revert great_circle_distance tuple unpacking since it breaks python2. drop python 2 before release * polygon_to_cells (#276) * start converting tests over * converted main tests * linting * better null island test * test_compact_and_uncompact_cells * convert a few more tests * add h3.Polygon class * lint * migrating some tests * this shift_circular_list thing makes these tests too hard to understand... * remove shift_circular_list and convert a few more tests * last of the tests in test_h3.py converted * last of the tests converted * note for polygons_to_cells in the future * Try out a __repr__ for h3.Polygon * test_polygon_class.py * use `cells` instead of `hexes` throughout the library and tests * docstring for Polygon * docstrings for functions * use `res` convention for resolution parameters Co-authored-by: Isaac Brodsky Co-authored-by: David Ellis --- .coveragerc | 3 - .flake8 | 2 + .github/workflows/coverage-lint.yml | 4 +- .github/workflows/tests.yml | 4 +- .github/workflows/wheels.yml | 18 +- CHANGELOG.md | 2 +- CMakeLists.txt | 20 +- MANIFEST.in | 3 - docs/api_comparison.md | 32 +- docs/api_reference.md | 83 ++- makefile | 30 +- readme.md | 2 +- src/h3/__init__.py | 30 +- src/h3/_cy/CMakeLists.txt | 7 +- src/h3/_cy/__init__.py | 107 ++-- src/h3/_cy/cells.pxd | 39 +- src/h3/_cy/cells.pyx | 392 ++++++------ src/h3/_cy/edges.pxd | 16 +- src/h3/_cy/edges.pyx | 114 ++-- src/h3/_cy/error_system.pxd | 3 + src/h3/_cy/error_system.pyx | 231 +++++++ src/h3/_cy/geo.pxd | 6 +- src/h3/_cy/geo.pyx | 231 +++---- src/h3/_cy/h3lib.pxd | 243 ++++---- src/h3/_cy/memory.pxd | 12 + src/h3/_cy/memory.pyx | 248 ++++++++ src/h3/_cy/to_multipoly.pyx | 16 +- src/h3/_cy/unstable_vect.pyx | 89 --- src/h3/_cy/util.pxd | 16 +- src/h3/_cy/util.pyx | 151 +---- src/h3/_polygon.py | 52 ++ src/h3/_version.py | 37 +- src/h3/api/_api_template.py | 370 +++++------ src/h3/api/basic_int/_binding.py | 6 +- src/h3/api/basic_int/_public_api.py | 109 ++-- src/h3/api/basic_str/_binding.py | 14 +- src/h3/unstable/__init__.py | 9 - src/h3/unstable/v4.py | 125 ---- src/h3/unstable/vect.py | 105 ---- src/h3lib | 2 +- tests/cython_example.pyx | 6 +- tests/test_basic_int.py | 22 +- tests/test_basic_str.py | 5 +- tests/test_cells_and_edges.py | 354 +++++------ tests/test_collection_inputs.py | 36 +- tests/test_cython.py | 8 +- tests/test_error_codes.py | 67 ++ tests/test_h3.py | 911 +++++++++------------------- tests/test_length_area.py | 41 +- tests/test_memview_int.py | 15 +- tests/test_numpy_int.py | 21 +- tests/test_polyfill.py | 150 +++-- tests/test_polygon_class.py | 27 + tests/test_to_multipoly.py | 61 +- tests/test_unstable_vect.py | 69 --- 55 files changed, 2275 insertions(+), 2501 deletions(-) delete mode 100644 .coveragerc create mode 100644 src/h3/_cy/error_system.pxd create mode 100644 src/h3/_cy/error_system.pyx create mode 100644 src/h3/_cy/memory.pxd create mode 100644 src/h3/_cy/memory.pyx delete mode 100644 src/h3/_cy/unstable_vect.pyx create mode 100644 src/h3/_polygon.py delete mode 100644 src/h3/unstable/__init__.py delete mode 100644 src/h3/unstable/v4.py delete mode 100644 src/h3/unstable/vect.py create mode 100644 tests/test_error_codes.py create mode 100644 tests/test_polygon_class.py delete mode 100644 tests/test_unstable_vect.py diff --git a/.coveragerc b/.coveragerc deleted file mode 100644 index fbf9e0e..0000000 --- a/.coveragerc +++ /dev/null @@ -1,3 +0,0 @@ -[run] -omit = - */h3/unstable/* diff --git a/.flake8 b/.flake8 index 0729f41..fedf9fd 100644 --- a/.flake8 +++ b/.flake8 @@ -12,3 +12,5 @@ ignore = E201, # E241 multiple spaces after ',' E241, + # E731 do not assign a lambda expression, use a def + E731, diff --git a/.github/workflows/coverage-lint.yml b/.github/workflows/coverage-lint.yml index e1d0bbd..6d33368 100644 --- a/.github/workflows/coverage-lint.yml +++ b/.github/workflows/coverage-lint.yml @@ -2,9 +2,9 @@ name: coverage-lint on: push: - branches: [master] + branches: [master, dev_v4] pull_request: - branches: [master] + branches: [master, dev_v4] jobs: tests: diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index f2c5682..072e21c 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -2,9 +2,9 @@ name: tests on: push: - branches: [master] + branches: [master, dev_v4] pull_request: - branches: [master] + branches: [master, dev_v4] jobs: tests: diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 5f75525..a02f51d 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -2,9 +2,9 @@ name: wheels on: push: - branches: [master] + branches: [master, dev_v4] pull_request: - branches: [master] + branches: [master, dev_v4] types: # Opened, synchronize, and reopened are the default types # We add ready_for_review to additionally trigger when converting from draft to non-draft @@ -19,22 +19,32 @@ on: jobs: make_sdist: - name: SDist + name: "SDist: ${{ matrix.os }}" if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }} - runs-on: ubuntu-latest + runs-on: ${{ matrix.os }} + + strategy: + matrix: + os: [ubuntu-latest] steps: - uses: actions/checkout@v3 with: submodules: recursive + - name: Setup Python + uses: actions/setup-python@v3.1.2 + - name: Make sdist run: | + python --version + pipx --version pipx run build --sdist - name: Install from sdist run: | pip install --upgrade pip setuptools wheel + pip install pytest cp dist/h3-*.tar.gz h3.tar.gz pip install h3.tar.gz[all] diff --git a/CHANGELOG.md b/CHANGELOG.md index 7bf87cf..cbab906 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -65,7 +65,7 @@ avoid adding features or APIs which do not map onto the ## [3.6.2] - 2020-06-02 -- Improve error reporting on `hex2int` (https://github.com/uber/h3-py/pull/127) +- Improve error reporting on `str_to_int` (https://github.com/uber/h3-py/pull/127) - Build Linux wheels for Python 2.7 ## [3.6.1] - 2020-05-29 diff --git a/CMakeLists.txt b/CMakeLists.txt index 00d9fe4..85ea71c 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -7,10 +7,22 @@ set(CMAKE_POSITION_INDEPENDENT_CODE ON) set(CMAKE_BUILD_TYPE Release) # Avoid building tooling we won't need for release -set(BUILD_BENCHMARKS OFF CACHE BOOL "" FORCE) -set(BUILD_FILTERS OFF CACHE BOOL "" FORCE) -set(BUILD_GENERATORS OFF CACHE BOOL "" FORCE) -set(BUILD_TESTING OFF CACHE BOOL "" FORCE) +# See all options with `cmake -LA` in an `h3/build` directory, +# or at https://h3geo.org/docs/next/core-library/compilation-options/ +macro(turn_off option_name) + set(${option_name} OFF CACHE BOOL "" FORCE) +endmacro() +turn_off(BUILD_ALLOC_TESTS) +turn_off(BUILD_BENCHMARKS) +turn_off(BUILD_FILTERS) +turn_off(BUILD_FUZZERS) +turn_off(BUILD_GENERATORS) +turn_off(BUILD_TESTING) +turn_off(ENABLE_COVERAGE) +turn_off(ENABLE_DOCS) +turn_off(ENABLE_FORMAT) +turn_off(ENABLE_LIBFUZZER) +turn_off(ENABLE_LINTING) # Build the core library as static set(BUILD_SHARED_LIBS OFF) diff --git a/MANIFEST.in b/MANIFEST.in index 47de939..6ccde1f 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -19,9 +19,6 @@ include src/h3lib/README.md include src/h3lib/VERSION include src/h3lib/CMakeLists.txt -graft src/h3lib/scripts -graft src/h3lib/examples graft src/h3lib/cmake graft src/h3lib/src/h3lib -graft src/h3lib/src/apps exclude MANIFEST.in diff --git a/docs/api_comparison.md b/docs/api_comparison.md index 3700f1c..e3ce64b 100644 --- a/docs/api_comparison.md +++ b/docs/api_comparison.md @@ -37,7 +37,7 @@ needs, based on speed and convenience. ```{tip} Note that the APIs are all 100% compatible, and it is easy to convert -between them with functions like `h3_to_string` (links!) and `string_to_h3`. +between them with functions like `int_to_str` (links!) and `str_to_int`. For example, one common pattern is to use `h3.api.numpy_int` for any computationally-heavy work, and convert the output to `str` and `list`/`set` @@ -54,11 +54,11 @@ using `list` and `set` for collections. ```python >>> import h3 ->>> h = h3.geo_to_h3(0, 0, 0) +>>> h = h3.latlng_to_cell(0, 0, 0) >>> h '8075fffffffffff' ->>> h3.hex_ring(h, 1) +>>> h3.grid_ring(h, 1) {'8055fffffffffff', '8059fffffffffff', '807dfffffffffff', @@ -87,11 +87,11 @@ H3 indexes are represented as Python `int`s, using `list` and `set` for collecti ```python >>> import h3.api.basic_int as h3 ->>> h = h3.geo_to_h3(0, 0, 0) +>>> h = h3.latlng_to_cell(0, 0, 0) >>> h 578536630256664575 ->>> h3.hex_ring(h, 1) +>>> h3.grid_ring(h, 1) {577973680303243263, 578044049047420927, 578677367745019903, @@ -110,11 +110,11 @@ no-copy `numpy` arrays instead of Python `list`s and `set`s. ```python >>> import h3.api.numpy_int as h3 ->>> h = h3.geo_to_h3(0, 0, 0) +>>> h = h3.latlng_to_cell(0, 0, 0) >>> h 578536630256664575 ->>> h3.hex_ring(h, 1) +>>> h3.grid_ring(h, 1) array([578782920861286399, 578044049047420927, 577973680303243263, 578677367745019903, 579169948954263551], dtype=uint64) ``` @@ -141,11 +141,11 @@ In fact, `h3.api.numpy_int` is essentially just a light wrapper around ```python >>> import h3.api.memview_int as h3 ->>> h = h3.geo_to_h3(0, 0, 0) +>>> h = h3.latlng_to_cell(0, 0, 0) >>> h 578536630256664575 ->>> mv = h3.hex_ring(h, 1) +>>> mv = h3.grid_ring(h, 1) >>> mv @@ -175,8 +175,8 @@ For example, consider the setup: ```python >>> import h3.api.memview_int as h3 >>> import numpy as np ->>> h = h3.geo_to_h3(0, 0, 0) ->>> mv = h3.hex_ring(h, 1) +>>> h = h3.latlng_to_cell(0, 0, 0) +>>> mv = h3.grid_ring(h, 1) >>> list(mv) [578782920861286399, 578044049047420927, @@ -200,7 +200,7 @@ Running `a = np.asarray(mv)` **does not create a copy**, so modifying `mv` also modifies `a`: ```python ->>> mv = h3.hex_ring(h, 1) +>>> mv = h3.grid_ring(h, 1) >>> a = np.asarray(mv) >>> mv[0] = 0 >>> a @@ -228,15 +228,15 @@ import h3.api.numpy_int def compute(h3_lib, N=100): - h = h3_lib.geo_to_h3(0, 0, 9) - out = h3_lib.k_ring(h, N) - out = h3_lib.compact(out) + h = h3_lib.latlng_to_cell(0, 0, 9) + out = h3_lib.grid_disk(h, N) + out = h3_lib.compact_cells(out) return out def compute_and_convert(h3_lib, N=100): out = compute(h3_lib, N) - out = [h3.h3_to_string(h) for h in out] + out = [h3.int_to_str(h) for h in out] return out ``` diff --git a/docs/api_reference.md b/docs/api_reference.md index fee1b42..526c85b 100644 --- a/docs/api_reference.md +++ b/docs/api_reference.md @@ -19,11 +19,10 @@ but we'll try to group functions in a reasonably logical manner. .. currentmodule:: h3 .. autosummary:: - h3_is_valid - h3_is_pentagon - h3_is_res_class_III - h3_is_res_class_iii - h3_unidirectional_edge_is_valid + is_valid_cell + is_pentagon + is_res_class_III + is_valid_directed_edge versions ``` @@ -33,16 +32,16 @@ but we'll try to group functions in a reasonably logical manner. .. currentmodule:: h3 .. autosummary:: - geo_to_h3 - h3_to_geo - h3_to_string - string_to_h3 - get_res0_indexes - get_pentagon_indexes - num_hexagons - h3_get_resolution - compact - uncompact + latlng_to_cell + cell_to_latlng + int_to_str + str_to_int + get_res0_cells + get_pentagons + get_num_cells + get_resolution + compact_cells + uncompact_cells ``` ### Geographic coordinates @@ -53,17 +52,15 @@ Functions relating H3 objects to geographic (lat/lng) coordinates. .. currentmodule:: h3 .. autosummary:: - point_dist - hex_area + great_circle_distance + average_hexagon_area cell_area edge_length - exact_edge_length - h3_to_geo_boundary - get_h3_unidirectional_edge_boundary - polyfill - polyfill_geojson - polyfill_polygon - h3_set_to_multi_polygon + average_hexagon_edge_length + cell_to_boundary + directed_edge_to_boundary + polygon_to_cells + cells_to_polygons ``` ### Hierarchical relationships @@ -72,9 +69,9 @@ Functions relating H3 objects to geographic (lat/lng) coordinates. .. currentmodule:: h3 .. autosummary:: - h3_to_parent - h3_to_children - h3_to_center_child + cell_to_parent + cell_to_children + cell_to_center_child ``` ### Cell grid relationships @@ -83,15 +80,11 @@ Functions relating H3 objects to geographic (lat/lng) coordinates. .. currentmodule:: h3 .. autosummary:: - hex_range - hex_range_distances - hex_ranges - hex_ring - k_ring - k_ring_distances - h3_distance - h3_indexes_are_neighbors - h3_line + grid_ring + grid_disk + grid_distance + are_neighbor_cells + grid_path_cells ``` ### Edges @@ -100,11 +93,11 @@ Functions relating H3 objects to geographic (lat/lng) coordinates. .. currentmodule:: h3 .. autosummary:: - get_h3_unidirectional_edge - get_destination_h3_index_from_unidirectional_edge - get_h3_indexes_from_unidirectional_edge - get_h3_unidirectional_edges_from_hexagon - get_origin_h3_index_from_unidirectional_edge + cells_to_directed_edge + get_directed_edge_destination + directed_edge_to_cells + origin_to_directed_edges + get_directed_edge_origin ``` ### IJ-indexing @@ -113,10 +106,10 @@ Functions relating H3 objects to geographic (lat/lng) coordinates. .. currentmodule:: h3 .. autosummary:: - h3_get_base_cell - h3_get_faces - experimental_h3_to_local_ij - experimental_local_ij_to_h3 + get_base_cell_number + get_icosahedron_faces + cell_to_local_ij + local_ij_to_cell ``` diff --git a/makefile b/makefile index 6e44c02..cf71860 100644 --- a/makefile +++ b/makefile @@ -1,31 +1,33 @@ .PHONY: init clear rebuild purge test lint lab ipython +PYTHON=$(shell command -v python || command -v python3) + build-docs: - env/bin/jupyter-book build docs/ --warningiserror --keep-going --all + ./env/bin/jupyter-book build docs/ --warningiserror --keep-going --all open: open docs/_build/html/index.html - init: purge git submodule update --init - python -m venv env - env/bin/pip install --upgrade pip wheel setuptools - env/bin/pip install .[all] - env/bin/pip install -r requirements.in + $(PYTHON) -m venv env + ./env/bin/pip install --upgrade pip wheel setuptools + ./env/bin/pip install .[all] + ./env/bin/pip install -r requirements.in clear: - -env/bin/pip uninstall -y h3 + -./env/bin/pip uninstall -y h3 -@rm -rf MANIFEST -@rm -rf annotations -@rm -rf .pytest_cache tests/__pycache__ __pycache__ _skbuild dist .coverage -@find . -type d -name '*.egg-info' | xargs rm -r -@find . -type f -name '*.pyc' | xargs rm -r -@find . -type d -name '*.ipynb_checkpoints' | xargs rm -r + -@find ./tests -type f -name '*.c' | xargs rm -r rebuild: clear - env/bin/pip install .[all] + ./env/bin/pip install .[all] purge: clear -@rm -rf env @@ -35,13 +37,13 @@ annotations: rebuild cp _skbuild/*/cmake-build/src/h3/_cy/*.html ./annotations test: - env/bin/cythonize -i tests/cython_example.pyx - env/bin/pytest tests --cov=h3 --cov-report term-missing --durations=10 + ./env/bin/cythonize -i tests/cython_example.pyx + ./env/bin/pytest tests --cov=h3 --cov-report term-missing --durations=10 lint: - env/bin/flake8 src/h3 setup.py tests - env/bin/pylint --disable=all --enable=import-error tests/ + ./env/bin/flake8 src/h3 setup.py tests + ./env/bin/pylint --disable=all --enable=import-error tests/ lab: - env/bin/pip install jupyterlab - env/bin/jupyter lab + ./env/bin/pip install jupyterlab + ./env/bin/jupyter lab diff --git a/readme.md b/readme.md index e060f05..3ab3803 100644 --- a/readme.md +++ b/readme.md @@ -41,7 +41,7 @@ conda install h3-py >>> import h3 >>> lat, lng = 37.769377, -122.388903 >>> resolution = 9 ->>> h3.geo_to_h3(lat, lng, resolution) +>>> h3.latlng_to_cell(lat, lng, resolution) '89283082e73ffff' ``` diff --git a/src/h3/__init__.py b/src/h3/__init__.py index 717f9cb..366ab02 100644 --- a/src/h3/__init__.py +++ b/src/h3/__init__.py @@ -2,15 +2,29 @@ from .api.basic_str import * from ._version import __version__ - -#todo: remove in 4.0; only here for backward compatibility -from .api import basic_str as h3 - +from ._polygon import Polygon from ._cy import ( + UnknownH3ErrorCode, + H3BaseException, + + H3GridNavigationError, + H3MemoryError, H3ValueError, - H3CellError, - H3ResolutionError, - H3EdgeError, - H3DistanceError, + + H3FailedError, + H3DomainError, + H3LatLngDomainError, + H3ResDomainError, + H3CellInvalidError, + H3DirEdgeInvalidError, + H3UndirEdgeInvalidError, + H3VertexInvalidError, + H3PentagonError, + H3DuplicateInputError, + H3NotNeighborsError, + H3ResMismatchError, + H3MemoryAllocError, + H3MemoryBoundsError, + H3OptionInvalidError, ) diff --git a/src/h3/_cy/CMakeLists.txt b/src/h3/_cy/CMakeLists.txt index 0d7e78c..3cf59d5 100644 --- a/src/h3/_cy/CMakeLists.txt +++ b/src/h3/_cy/CMakeLists.txt @@ -22,7 +22,9 @@ add_cython_file(geo) add_cython_file(cells) add_cython_file(edges) add_cython_file(to_multipoly) -add_cython_file(unstable_vect) +add_cython_file(error_system) +add_cython_file(memory) + # Include pyx and pxd files in distribution for use by Cython API install( @@ -36,6 +38,9 @@ install( h3lib.pxd util.pxd util.pyx + error_system.pyx + memory.pxd + memory.pyx DESTINATION src/h3/_cy ) diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index bb4dfc0..b3647aa 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -14,65 +14,86 @@ function interface and input conversion (string to int, for instance). """ from .cells import ( - is_cell, + is_valid_cell, is_pentagon, - get_base_cell, - resolution, - parent, - distance, - disk, - ring, - children, - compact, - uncompact, - num_hexagons, - mean_hex_area, + get_base_cell_number, + get_resolution, + cell_to_parent, + grid_distance, + grid_disk, + grid_ring, + cell_to_children, + compact_cells, + uncompact_cells, + get_num_cells, + average_hexagon_area, cell_area, - line, + grid_path_cells, is_res_class_iii, - get_pentagon_indexes, - get_res0_indexes, - center_child, - get_faces, - experimental_h3_to_local_ij, - experimental_local_ij_to_h3, + get_pentagons, + get_res0_cells, + cell_to_center_child, + get_icosahedron_faces, + cell_to_local_ij, + local_ij_to_cell, ) from .edges import ( - are_neighbors, - edge, - is_edge, - edge_origin, - edge_destination, - edge_cells, - edges_from_cell, - mean_edge_length, + are_neighbor_cells, + cells_to_directed_edge, + is_valid_directed_edge, + get_directed_edge_origin, + get_directed_edge_destination, + directed_edge_to_cells, + origin_to_directed_edges, + average_hexagon_edge_length, edge_length, ) from .geo import ( - geo_to_h3, - h3_to_geo, - polyfill_polygon, - polyfill_geojson, - polyfill, - cell_boundary, - edge_boundary, - point_dist, + latlng_to_cell, + cell_to_latlng, + polygon_to_cells, + cell_to_boundary, + directed_edge_to_boundary, + great_circle_distance, ) from .to_multipoly import ( - h3_set_to_multi_polygon + cells_to_multi_polygon ) from .util import ( c_version, - hex2int, - int2hex, - from_iter, + str_to_int, + int_to_str, +) + +from .memory import ( + iter_to_mv, +) + +from .error_system import ( + UnknownH3ErrorCode, + H3BaseException, + + H3GridNavigationError, + H3MemoryError, H3ValueError, - H3CellError, - H3ResolutionError, - H3EdgeError, - H3DistanceError, + + H3FailedError, + H3DomainError, + H3LatLngDomainError, + H3ResDomainError, + H3CellInvalidError, + H3DirEdgeInvalidError, + H3UndirEdgeInvalidError, + H3VertexInvalidError, + H3PentagonError, + H3DuplicateInputError, + H3NotNeighborsError, + H3ResMismatchError, + H3MemoryAllocError, + H3MemoryBoundsError, + H3OptionInvalidError, ) diff --git a/src/h3/_cy/cells.pxd b/src/h3/_cy/cells.pxd index 1071938..b6a36d1 100644 --- a/src/h3/_cy/cells.pxd +++ b/src/h3/_cy/cells.pxd @@ -1,25 +1,24 @@ from .h3lib cimport bool, int64_t, H3int -cpdef bool is_cell(H3int h) +cpdef bool is_valid_cell(H3int h) cpdef bool is_pentagon(H3int h) -cpdef int get_base_cell(H3int h) except -1 -cpdef int resolution(H3int h) except -1 -cpdef int distance(H3int h1, H3int h2) except -1 -cpdef H3int[:] disk(H3int h, int k) -cpdef H3int[:] _ring_fallback(H3int h, int k) -cpdef H3int[:] ring(H3int h, int k) -cpdef H3int parent(H3int h, res=*) except 0 -cpdef H3int[:] children(H3int h, res=*) -cpdef H3int center_child(H3int h, res=*) except 0 -cpdef H3int[:] compact(const H3int[:] hu) -cpdef H3int[:] uncompact(const H3int[:] hc, int res) -cpdef int64_t num_hexagons(int resolution) except -1 -cpdef double mean_hex_area(int resolution, unit=*) except -1 +cpdef int get_base_cell_number(H3int h) except -1 +cpdef int get_resolution(H3int h) except -1 +cpdef int grid_distance(H3int h1, H3int h2) except -1 +cpdef H3int[:] grid_disk(H3int h, int k) +cpdef H3int[:] grid_ring(H3int h, int k) +cpdef H3int cell_to_parent(H3int h, res=*) except 0 +cpdef H3int[:] cell_to_children(H3int h, res=*) +cpdef H3int cell_to_center_child(H3int h, res=*) except 0 +cpdef H3int[:] compact_cells(const H3int[:] hu) +cpdef H3int[:] uncompact_cells(const H3int[:] hc, int res) +cpdef int64_t get_num_cells(int resolution) except -1 +cpdef double average_hexagon_area(int resolution, unit=*) except -1 cpdef double cell_area(H3int h, unit=*) except -1 -cpdef H3int[:] line(H3int start, H3int end) +cpdef H3int[:] grid_path_cells(H3int start, H3int end) cpdef bool is_res_class_iii(H3int h) -cpdef H3int[:] get_pentagon_indexes(int res) -cpdef H3int[:] get_res0_indexes() -cpdef get_faces(H3int h) -cpdef (int, int) experimental_h3_to_local_ij(H3int origin, H3int h) except * -cpdef H3int experimental_local_ij_to_h3(H3int origin, int i, int j) except 0 +cpdef H3int[:] get_pentagons(int res) +cpdef H3int[:] get_res0_cells() +cpdef get_icosahedron_faces(H3int h) +cpdef (int, int) cell_to_local_ij(H3int origin, H3int h) except * +cpdef H3int local_ij_to_cell(H3int origin, int i, int j) except 0 diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 4206b81..6a21576 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -1,75 +1,88 @@ cimport h3lib -from .h3lib cimport bool, int64_t, H3int -from libc cimport stdlib +from .h3lib cimport bool, int64_t, H3int, H3ErrorCodes from .util cimport ( check_cell, check_res, check_distance, - create_ptr, - create_mv, - empty_memory_view, # want to drop this import if possible ) -from .util import H3ValueError, H3ResolutionError +from .error_system cimport ( + check_for_error, + check_for_error_msg, +) + +from .memory cimport ( + H3MemoryManager, + int_mv, +) # todo: add notes about Cython exception handling # bool is a python type, so we don't need the except clause -cpdef bool is_cell(H3int h): +cpdef bool is_valid_cell(H3int h): """Validates an H3 cell (hexagon or pentagon) Returns ------- boolean """ - return h3lib.h3IsValid(h) == 1 + return h3lib.isValidCell(h) == 1 + cpdef bool is_pentagon(H3int h): - return h3lib.h3IsPentagon(h) == 1 + return h3lib.isPentagon(h) == 1 -cpdef int get_base_cell(H3int h) except -1: + +cpdef int get_base_cell_number(H3int h) except -1: check_cell(h) - return h3lib.h3GetBaseCell(h) + return h3lib.getBaseCellNumber(h) -cpdef int resolution(H3int h) except -1: +cpdef int get_resolution(H3int h) except -1: """Returns the resolution of an H3 Index 0--15 """ check_cell(h) - return h3lib.h3GetResolution(h) + return h3lib.getResolution(h) -cpdef int distance(H3int h1, H3int h2) except -1: - """ compute the hex-distance between two hexagons +cpdef int grid_distance(H3int h1, H3int h2) except -1: + """ Compute the grid distance between two cells """ + cdef: + int64_t distance + check_cell(h1) check_cell(h2) - d = h3lib.h3Distance(h1,h2) + check_for_error( + h3lib.gridDistance(h1, h2, &distance) + ) - if d < 0: - s = 'Cells are too far apart to compute distance: {} and {}' - s = s.format(hex(h1), hex(h2)) - raise H3ValueError(s) + return distance - return d - -cpdef H3int[:] disk(H3int h, int k): +cpdef H3int[:] grid_disk(H3int h, int k): """ Return cells at grid distance `<= k` from `h`. """ + cdef: + int64_t n + check_cell(h) check_distance(k) - n = h3lib.maxKringSize(k) + check_for_error( + h3lib.maxGridDiskSize(k, &n) + ) - ptr = create_ptr(n) # todo: return a "smart" pointer that knows its length? - h3lib.kRing(h, k, ptr) - mv = create_mv(ptr, n) + hmm = H3MemoryManager(n) + check_for_error( + h3lib.gridDisk(h, k, hmm.ptr) + ) + mv = hmm.to_mv() return mv @@ -79,34 +92,37 @@ cpdef H3int[:] _ring_fallback(H3int h, int k): `ring` tries to call `h3lib.hexRing` first; if that fails, we call this function, which relies on `h3lib.kRingDistances`. - Failures for `h3lib.hexRing` happen when the algortihm runs into a pentagon. + Failures for `h3lib.hexRing` happen when the algorithm runs into a pentagon. """ + cdef: + int64_t n + int[:] distances ## todo: weird, this needs to be specified to avoid errors. cython bug? + check_cell(h) check_distance(k) - n = h3lib.maxKringSize(k) - # array of h3 cells - ptr = create_ptr(n) + check_for_error( + h3lib.maxGridDiskSize(k, &n) + ) + hmm = H3MemoryManager(n) - # array of cell distances from `h` - dist_ptr = stdlib.calloc(n, sizeof(int)) - if dist_ptr is NULL: - raise MemoryError() - - h3lib.kRingDistances(h, k, ptr, dist_ptr) - - distances = dist_ptr - distances.callback_free_data = stdlib.free + # parallel array of cell distances from `h`. + # idea: instead of a memoryview object, have a my_mv object that can return a ptr, but does the correct logic when it has length 0 + # then can always just return the pointer, instead of the weird &mv[0] syntax + distances = int_mv(n) + check_for_error( + h3lib.gridDiskDistances(h, k, hmm.ptr, &distances[0]) + ) for i,v in enumerate(distances): if v != k: - ptr[i] = 0 + hmm.ptr[i] = 0 - mv = create_mv(ptr, n) + mv = hmm.to_mv() return mv -cpdef H3int[:] ring(H3int h, int k): +cpdef H3int[:] grid_ring(H3int h, int k): """ Return cells at grid distance `== k` from `h`. Collection is "hollow" for k >= 1. """ @@ -114,133 +130,157 @@ cpdef H3int[:] ring(H3int h, int k): check_distance(k) n = 6*k if k > 0 else 1 - ptr = create_ptr(n) - - flag = h3lib.hexRing(h, k, ptr) - - # if we drop into the failure state, we might be tempted to not create - # this mv, but creating the mv is exactly what guarantees that we'll free - # the memory. context manager would be better here, if we can figure out - # how to do that - mv = create_mv(ptr, n) - - if flag != 0: + hmm = H3MemoryManager(n) + err = h3lib.gridRingUnsafe(h, k, hmm.ptr) + if err: mv = _ring_fallback(h, k) + else: + mv = hmm.to_mv() return mv +cpdef H3int cell_to_parent(H3int h, res=None) except 0: + cdef: + H3int parent -cpdef H3int parent(H3int h, res=None) except 0: - check_cell(h) + check_cell(h) # todo: do we want to check for validity here? or leave correctness to the user? if res is None: - res = resolution(h) - 1 - if res > resolution(h): + res = get_resolution(h) - 1 + + err = h3lib.cellToParent(h, res, &parent) + if err: msg = 'Invalid parent resolution {} for cell {}.' msg = msg.format(res, hex(h)) - raise H3ResolutionError(msg) + check_for_error_msg(err, msg) - check_res(res) + return parent - return h3lib.h3ToParent(h, res) -cpdef H3int[:] children(H3int h, res=None): +cpdef H3int[:] cell_to_children(H3int h, res=None): + cdef: + int64_t n + check_cell(h) if res is None: - res = resolution(h) + 1 - if res < resolution(h): + res = get_resolution(h) + 1 + + err = h3lib.cellToChildrenSize(h, res, &n) + if err: msg = 'Invalid child resolution {} for cell {}.' msg = msg.format(res, hex(h)) - raise H3ResolutionError(msg) + check_for_error_msg(err, msg) - check_res(res) - - n = h3lib.maxH3ToChildrenSize(h, res) - - ptr = create_ptr(n) - h3lib.h3ToChildren(h, res, ptr) - mv = create_mv(ptr, n) + hmm = H3MemoryManager(n) + check_for_error( + h3lib.cellToChildren(h, res, hmm.ptr) + ) + mv = hmm.to_mv() return mv -cpdef H3int center_child(H3int h, res=None) except 0: + +cpdef H3int cell_to_center_child(H3int h, res=None) except 0: + cdef: + H3int child + check_cell(h) if res is None: - res = resolution(h) + 1 - if res < resolution(h): + res = get_resolution(h) + 1 + + err = h3lib.cellToCenterChild(h, res, &child) + if err: msg = 'Invalid child resolution {} for cell {}.' msg = msg.format(res, hex(h)) - raise H3ResolutionError(msg) + check_for_error_msg(err, msg) - check_res(res) - - return h3lib.h3ToCenterChild(h, res) + return child -cpdef H3int[:] compact(const H3int[:] hu): +cpdef H3int[:] compact_cells(const H3int[:] hu): + # todo: fix this with my own Cython object "wrapper" class? + # everything has a .ptr interface? # todo: the Clib can handle 0-len arrays because it **avoids** # dereferencing the pointer, but Cython's syntax of # `&hu[0]` **requires** a dereference. For Cython, checking for array # length of zero and returning early seems like the easiest solution. # note: open to better ideas! + if len(hu) == 0: - return empty_memory_view() + return H3MemoryManager(0).to_mv() for h in hu: ## todo: should we have an array version? would that be faster? check_cell(h) - ptr = create_ptr(len(hu)) - flag = h3lib.compact(&hu[0], ptr, len(hu)) - mv = create_mv(ptr, len(hu)) - - if flag != 0: - raise H3ValueError('Could not compact set of hexagons!') + cdef size_t n = len(hu) + hmm = H3MemoryManager(n) + check_for_error( + h3lib.compactCells(&hu[0], hmm.ptr, n) + ) + mv = hmm.to_mv() return mv + # todo: https://stackoverflow.com/questions/50684977/cython-exception-type-for-a-function-returning-a-typed-memoryview # apparently, memoryviews are python objects, so we don't need to do the except clause -cpdef H3int[:] uncompact(const H3int[:] hc, int res): +cpdef H3int[:] uncompact_cells(const H3int[:] hc, int res): # todo: the Clib can handle 0-len arrays because it **avoids** # dereferencing the pointer, but Cython's syntax of # `&hc[0]` **requires** a dereference. For Cython, checking for array # length of zero and returning early seems like the easiest solution. # note: open to better ideas! + cdef: + int64_t n + + if len(hc) == 0: - return empty_memory_view() + return H3MemoryManager(0).to_mv() for h in hc: check_cell(h) - N = h3lib.maxUncompactSize(&hc[0], len(hc), res) - - ptr = create_ptr(N) - flag = h3lib.uncompact( - &hc[0], len(hc), - ptr, N, - res + check_for_error( + h3lib.uncompactCellsSize(&hc[0], len(hc), res, &n) ) - mv = create_mv(ptr, N) - if flag != 0: - raise H3ValueError('Could not uncompact set of hexagons!') + hmm = H3MemoryManager(n) + check_for_error( + h3lib.uncompactCells( + &hc[0], # todo: symmetry here with the wrapper object might be nice. hc.ptr / hc.n + len(hc), + hmm.ptr, + hmm.n, + res + ) + ) + + mv = hmm.to_mv() return mv -cpdef int64_t num_hexagons(int resolution) except -1: - check_res(resolution) +cpdef int64_t get_num_cells(int resolution) except -1: + cdef: + int64_t num_cells - return h3lib.numHexagons(resolution) + check_for_error( + h3lib.getNumCells(resolution, &num_cells) + ) + + return num_cells -cpdef double mean_hex_area(int resolution, unit='km^2') except -1: - check_res(resolution) +cpdef double average_hexagon_area(int resolution, unit='km^2') except -1: + cdef: + double area - area = h3lib.hexAreaKm2(resolution) + check_for_error( + h3lib.getHexagonAreaAvgKm2(resolution, &area) + ) # todo: multiple units convert = { @@ -251,125 +291,129 @@ cpdef double mean_hex_area(int resolution, unit='km^2') except -1: try: area *= convert[unit] except: - raise H3ValueError('Unknown unit: {}'.format(unit)) + raise ValueError('Unknown unit: {}'.format(unit)) return area cpdef double cell_area(H3int h, unit='km^2') except -1: - check_cell(h) + cdef: + double area if unit == 'rads^2': - area = h3lib.cellAreaRads2(h) + err = h3lib.cellAreaRads2(h, &area) elif unit == 'km^2': - area = h3lib.cellAreaKm2(h) + err = h3lib.cellAreaKm2(h, &area) elif unit == 'm^2': - area = h3lib.cellAreaM2(h) + err = h3lib.cellAreaM2(h, &area) else: - raise H3ValueError('Unknown unit: {}'.format(unit)) + raise ValueError('Unknown unit: {}'.format(unit)) + + check_for_error(err) return area -cpdef H3int[:] line(H3int start, H3int end): - check_cell(start) - check_cell(end) +cdef _could_not_find_line(err, start, end): + msg = "Couldn't find line between cells {} and {}" + msg = msg.format(hex(start), hex(end)) - n = h3lib.h3LineSize(start, end) + check_for_error_msg(err, msg) - if n < 0: - s = "Couldn't find line between cells {} and {}" - s = s.format(hex(start), hex(end)) - raise H3ValueError(s) +cpdef H3int[:] grid_path_cells(H3int start, H3int end): + cdef: + int64_t n - ptr = create_ptr(n) - flag = h3lib.h3Line(start, end, ptr) - mv = create_mv(ptr, n) + # todo: can we segfault here with invalid inputs? + # Can we trust the c library to validate the start/end cells? + # probably applies to all size/work pairs of functions... + err = h3lib.gridPathCellsSize(start, end, &n) - if flag != 0: - s = "Couldn't find line between cells {} and {}" - s = s.format(hex(start), hex(end)) - raise H3ValueError(s) + _could_not_find_line(err, start, end) + + hmm = H3MemoryManager(n) + err = h3lib.gridPathCells(start, end, hmm.ptr) + + _could_not_find_line(err, start, end) + + # todo: probably here too? + mv = hmm.to_mv() return mv cpdef bool is_res_class_iii(H3int h): - return h3lib.h3IsResClassIII(h) == 1 + return h3lib.isResClassIII(h) == 1 -cpdef H3int[:] get_pentagon_indexes(int res): - check_res(res) +cpdef H3int[:] get_pentagons(int res): + n = h3lib.pentagonCount() - n = h3lib.pentagonIndexCount() - - ptr = create_ptr(n) - h3lib.getPentagonIndexes(res, ptr) - mv = create_mv(ptr, n) + hmm = H3MemoryManager(n) + check_for_error( + h3lib.getPentagons(res, hmm.ptr) + ) + mv = hmm.to_mv() return mv -cpdef H3int[:] get_res0_indexes(): - n = h3lib.res0IndexCount() +cpdef H3int[:] get_res0_cells(): + n = h3lib.res0CellCount() - ptr = create_ptr(n) - h3lib.getRes0Indexes(ptr) - mv = create_mv(ptr, n) + hmm = H3MemoryManager(n) + check_for_error( + h3lib.getRes0Cells(hmm.ptr) + ) + mv = hmm.to_mv() return mv +# oh, this is returning a set?? +# todo: convert to int[:]? +cpdef get_icosahedron_faces(H3int h): + cdef: + int n + int[:] faces ## todo: weird, this needs to be specified to avoid errors. cython bug? -cpdef get_faces(H3int h): - check_cell(h) + check_for_error( + h3lib.maxFaceCount(h, &n) + ) - n = h3lib.maxFaceCount(h) + faces = int_mv(n) + check_for_error( + h3lib.getIcosahedronFaces(h, &faces[0]) + ) - cdef int* ptr = stdlib.calloc(n, sizeof(int)) - if (n > 0) and (not ptr): - raise MemoryError() + # todo: wait? do faces start from 0 or 1? + # we could do this check/processing in the int_mv object + out = {f for f in faces if f >= 0} - h3lib.h3GetFaces(h, ptr) + return out - faces = ptr - faces = {f for f in faces if f >= 0} - stdlib.free(ptr) - return faces - - -cpdef (int, int) experimental_h3_to_local_ij(H3int origin, H3int h) except *: +cpdef (int, int) cell_to_local_ij(H3int origin, H3int h) except *: cdef: - int flag h3lib.CoordIJ c - check_cell(origin) - check_cell(h) - - flag = h3lib.experimentalH3ToLocalIj(origin, h, &c) - - if flag != 0: - s = "Couldn't find local (i,j) between cells {} and {}." - s = s.format(hex(origin), hex(h)) - raise H3ValueError(s) + err = h3lib.cellToLocalIj(origin, h, 0, &c) + if err: + msg = "Couldn't find local (i,j) between cells {} and {}." + msg = msg.format(hex(origin), hex(h)) + check_for_error_msg(err, msg) return c.i, c.j - -cpdef H3int experimental_local_ij_to_h3(H3int origin, int i, int j) except 0: +cpdef H3int local_ij_to_cell(H3int origin, int i, int j) except 0: cdef: - int flag h3lib.CoordIJ c H3int out - check_cell(origin) - c.i, c.j = i, j - flag = h3lib.experimentalLocalIjToH3(origin, &c, &out) - - if flag != 0: - s = "Couldn't find cell at local ({},{}) from cell {}." - s = s.format(i, j, hex(origin)) - raise H3ValueError(s) + err = h3lib.localIjToCell(origin, &c, 0, &out) + if err: + msg = "Couldn't find cell at local ({},{}) from cell {}." + msg = msg.format(i, j, hex(origin)) + check_for_error_msg(err, msg) return out diff --git a/src/h3/_cy/edges.pxd b/src/h3/_cy/edges.pxd index 465b82d..b7fcf84 100644 --- a/src/h3/_cy/edges.pxd +++ b/src/h3/_cy/edges.pxd @@ -1,11 +1,11 @@ from .h3lib cimport bool, H3int -cpdef bool are_neighbors(H3int h1, H3int h2) -cpdef H3int edge(H3int origin, H3int destination) except 1 -cpdef bool is_edge(H3int e) -cpdef H3int edge_origin(H3int e) except 1 -cpdef H3int edge_destination(H3int e) except 1 -cpdef (H3int, H3int) edge_cells(H3int e) except * -cpdef H3int[:] edges_from_cell(H3int origin) -cpdef double mean_edge_length(int resolution, unit=*) except -1 +cpdef bool are_neighbor_cells(H3int h1, H3int h2) +cpdef H3int cells_to_directed_edge(H3int origin, H3int destination) except * +cpdef bool is_valid_directed_edge(H3int e) +cpdef H3int get_directed_edge_origin(H3int e) except 1 +cpdef H3int get_directed_edge_destination(H3int e) except 1 +cpdef (H3int, H3int) directed_edge_to_cells(H3int e) except * +cpdef H3int[:] origin_to_directed_edges(H3int origin) +cpdef double average_hexagon_edge_length(int resolution, unit=*) except -1 cpdef double edge_length(H3int e, unit=*) except -1 diff --git a/src/h3/_cy/edges.pyx b/src/h3/_cy/edges.pyx index 6560006..bd0aa7c 100644 --- a/src/h3/_cy/edges.pyx +++ b/src/h3/_cy/edges.pyx @@ -1,71 +1,86 @@ cimport h3lib from .h3lib cimport bool, H3int -from .util cimport ( - check_cell, - check_edge, - check_res, - create_ptr, - create_mv, -) +from .error_system cimport check_for_error -from .util import H3ValueError +from .memory cimport H3MemoryManager -cpdef bool are_neighbors(H3int h1, H3int h2): - check_cell(h1) - check_cell(h2) +# todo: make bint +cpdef bool are_neighbor_cells(H3int h1, H3int h2): + cdef: + int out - return h3lib.h3IndexesAreNeighbors(h1, h2) == 1 + err = h3lib.areNeighborCells(h1, h2, &out) + + # note: we are intentionally not raising an error here, and just + # returning false. + # todo: is this choice consistent across the Python and C libs? + if err: + return False + + return out == 1 -cpdef H3int edge(H3int origin, H3int destination) except 1: - check_cell(origin) - check_cell(destination) +cpdef H3int cells_to_directed_edge(H3int origin, H3int destination) except *: + cdef: + int neighbor_out + H3int out - if h3lib.h3IndexesAreNeighbors(origin, destination) != 1: - s = 'Cells are not neighbors: {} and {}' - s = s.format(hex(origin), hex(destination)) - raise H3ValueError(s) + check_for_error( + h3lib.cellsToDirectedEdge(origin, destination, &out) + ) - return h3lib.getH3UnidirectionalEdge(origin, destination) + return out -cpdef bool is_edge(H3int e): - return h3lib.h3UnidirectionalEdgeIsValid(e) == 1 +cpdef bool is_valid_directed_edge(H3int e): + return h3lib.isValidDirectedEdge(e) == 1 -cpdef H3int edge_origin(H3int e) except 1: - # without the check, with an invalid input, the function will just return 0 - check_edge(e) +cpdef H3int get_directed_edge_origin(H3int e) except 1: + cdef: + H3int out - return h3lib.getOriginH3IndexFromUnidirectionalEdge(e) + check_for_error( + h3lib.getDirectedEdgeOrigin(e, &out) + ) -cpdef H3int edge_destination(H3int e) except 1: - check_edge(e) + return out - return h3lib.getDestinationH3IndexFromUnidirectionalEdge(e) +cpdef H3int get_directed_edge_destination(H3int e) except 1: + cdef: + H3int out -cpdef (H3int, H3int) edge_cells(H3int e) except *: - check_edge(e) + check_for_error( + h3lib.getDirectedEdgeDestination(e, &out) + ) - return edge_origin(e), edge_destination(e) + return out -cpdef H3int[:] edges_from_cell(H3int origin): +cpdef (H3int, H3int) directed_edge_to_cells(H3int e) except *: + # todo: use directed_edge_to_cells in h3lib + return get_directed_edge_origin(e), get_directed_edge_destination(e) + +cpdef H3int[:] origin_to_directed_edges(H3int origin): """ Returns the 6 (or 5 for pentagons) directed edges for the given origin cell """ - check_cell(origin) - ptr = create_ptr(6) - h3lib.getH3UnidirectionalEdgesFromHexagon(origin, ptr) - mv = create_mv(ptr, 6) + hmm = H3MemoryManager(6) + check_for_error( + h3lib.originToDirectedEdges(origin, hmm.ptr) + ) + mv = hmm.to_mv() return mv -cpdef double mean_edge_length(int resolution, unit='km') except -1: - check_res(resolution) +cpdef double average_hexagon_edge_length(int resolution, unit='km') except -1: + cdef: + double length - length = h3lib.edgeLengthKm(resolution) + check_for_error( + h3lib.getHexagonEdgeLengthAvgKm(resolution, &length) + ) # todo: multiple units convert = { @@ -76,25 +91,24 @@ cpdef double mean_edge_length(int resolution, unit='km') except -1: try: length *= convert[unit] except: - raise H3ValueError('Unknown unit: {}'.format(unit)) + raise ValueError('Unknown unit: {}'.format(unit)) return length cpdef double edge_length(H3int e, unit='km') except -1: - check_edge(e) - - # todo: maybe kick this logic up to the python level - # it might be a little cleaner, because we can do the "switch statement" - # with a dict, but would require exposing more C functions + cdef: + double length if unit == 'rads': - length = h3lib.exactEdgeLengthRads(e) + err = h3lib.edgeLengthRads(e, &length) elif unit == 'km': - length = h3lib.exactEdgeLengthKm(e) + err = h3lib.edgeLengthKm(e, &length) elif unit == 'm': - length = h3lib.exactEdgeLengthM(e) + err = h3lib.edgeLengthM(e, &length) else: - raise H3ValueError('Unknown unit: {}'.format(unit)) + raise ValueError('Unknown unit: {}'.format(unit)) + + check_for_error(err) return length diff --git a/src/h3/_cy/error_system.pxd b/src/h3/_cy/error_system.pxd new file mode 100644 index 0000000..af8c709 --- /dev/null +++ b/src/h3/_cy/error_system.pxd @@ -0,0 +1,3 @@ +from .h3lib cimport H3Error +cdef check_for_error(H3Error err) +cdef check_for_error_msg(H3Error err, str msg) diff --git a/src/h3/_cy/error_system.pyx b/src/h3/_cy/error_system.pyx new file mode 100644 index 0000000..fbdd918 --- /dev/null +++ b/src/h3/_cy/error_system.pyx @@ -0,0 +1,231 @@ +""" +Exceptions from the h3-py library have three possible sources: + +- the Python code +- the Cython code +- the underlying H3 C library code + +The Python and Cython `h3-py` code will only raise standard Python +built-in exceptions; **no custom** exception classes will be used. + +Conversely, many functions in the H3 C library return a `uint32_t` +error code (aliased as type `H3Error`). +When these errors happen (and `h3-py` can't recover from them internally), +they are passed up to the Python/Cython code, where their +`uint32_t` error values are converted to **custom** Python exception types. +These custom exception classes all inherit from `H3BaseException`. + +There is a 1-1 correspondence between the concrete subclasses of +`H3BaseException` and the H3 C library `H3ErrorCodes` values. +The correspondence is intentional, so that the user can refer to the +H3 C library documentation on these errors. + +The (`uint32_t` <-> Exception) correspondence should be clear from +the names of each error/exception, but the explicit mapping is given by +a dictionary in the code below. + +Note that some "abstract" subclasses of `H3BaseException` are also included to +group the exceptions by type. (We say "abstract" because Python has no easy +way to make true abstract exception classes.) + +These "abstract" exceptions will never be raised directly by `h3-py`, but they +allow the user to catch general groups of errors. +Note that `h3-py` will only ever directly raise +the "concrete" exception classes. + +Summarizing, all exceptions originating from the C library inherit from +`H3BaseException`, which has both "abstract" and "concrete" subclasses. + +**Abstract classes**: + +- H3BaseException +- H3ValueError +- H3MemoryError +- H3GridNavigationError + +**Concrete classes**: + +- H3FailedError +- H3DomainError +- H3LatLngDomainError +- H3ResDomainError +- H3CellInvalidError +- H3DirEdgeInvalidError +- H3UndirEdgeInvalidError +- H3VertexInvalidError +- H3PentagonError +- H3DuplicateInputError +- H3NotNeighborsError +- H3ResMismatchError +- H3MemoryAllocError +- H3MemoryBoundsError +- H3OptionInvalidError + + +# TODO: add tests verifying that concrete exception classes have the right error codes associated with them +""" + +from contextlib import contextmanager + +from .h3lib cimport ( + H3Error, + + # H3ErrorCodes enum values + E_SUCCESS, + E_FAILED, + E_DOMAIN, + E_LATLNG_DOMAIN, + E_RES_DOMAIN, + E_CELL_INVALID, + E_DIR_EDGE_INVALID, + E_UNDIR_EDGE_INVALID, + E_VERTEX_INVALID, + E_PENTAGON, + E_DUPLICATE_INPUT, + E_NOT_NEIGHBORS, + E_RES_MISMATCH, + E_MEMORY_ALLOC, + E_MEMORY_BOUNDS, + E_OPTION_INVALID, +) + +@contextmanager +def _the_error(obj): + """ + Syntactic maple syrup for grouping exception definitions. + The associated `with` statement ends up as a not-half-bad + approximation to a valid sentence fragment. + + This provides sort of a "pretend scope", in that it allows for + block indentation which helps to visually indicate the "scope" + of the `... as e` statement. Just note that Python doesn't treat the + `with` block as a "true" separate scope. + + Note that this doesn't actually do anything context-manager-y, outside + of the variable assignment and block indentation. + """ + yield obj + + +# +# Base exception for C library error codes +# +class H3BaseException(Exception): + """ Base H3 exception class. + + Concrete subclasses of this class correspond to specific + error codes from the C library. + + Base/abstract subclasses will have `h3_error_code = None`, while + concrete subclasses will have `h3_error_code` equal to their associated + C library error code. + """ + h3_error_code = None + + +# +# A few "abstract" exceptions; organizational. +# +with _the_error(H3BaseException) as e: + class H3ValueError(e, ValueError): ... + class H3MemoryError(e, MemoryError): ... + class H3GridNavigationError(e, RuntimeError): ... + + +# +# Concrete exceptions +# +class UnknownH3ErrorCode(H3BaseException): + """ + Indicates that the h3-py Python bindings have received an + unrecognized error code from the C library. + + This should never happen. Please report if you get this error. + + Note that this exception is *outside* of the + H3BaseException class hierarchy. + """ + pass + +with _the_error(H3BaseException) as e: + class H3FailedError(e): ... + +with _the_error(H3GridNavigationError) as e: + class H3PentagonError(e): ... + +with _the_error(H3MemoryError) as e: + class H3MemoryAllocError(e): ... + class H3MemoryBoundsError(e): ... + +with _the_error(H3ValueError) as e: + class H3DomainError(e): ... + class H3LatLngDomainError(e): ... + class H3ResDomainError(e): ... + class H3CellInvalidError(e): ... + class H3DirEdgeInvalidError(e): ... + class H3UndirEdgeInvalidError(e): ... + class H3VertexInvalidError(e): ... + class H3DuplicateInputError(e): ... + class H3NotNeighborsError(e): ... + class H3ResMismatchError(e): ... + class H3OptionInvalidError(e): ... + + +""" +This defines a mapping between uint32_t error codes and concrete Python +exception classes. +Note that we intentionally omit E_SUCCESS, as it isn't an actual error. +""" +error_mapping = { + E_FAILED: H3FailedError, + E_DOMAIN: H3DomainError, + E_LATLNG_DOMAIN: H3LatLngDomainError, + E_RES_DOMAIN: H3ResDomainError, + E_CELL_INVALID: H3CellInvalidError, + E_DIR_EDGE_INVALID: H3DirEdgeInvalidError, + E_UNDIR_EDGE_INVALID: H3UndirEdgeInvalidError, + E_VERTEX_INVALID: H3VertexInvalidError, + E_PENTAGON: H3PentagonError, + E_DUPLICATE_INPUT: H3DuplicateInputError, + E_NOT_NEIGHBORS: H3NotNeighborsError, + E_RES_MISMATCH: H3ResMismatchError, + E_MEMORY_ALLOC: H3MemoryAllocError, + E_MEMORY_BOUNDS: H3MemoryBoundsError, + E_OPTION_INVALID: H3OptionInvalidError, +} + +# Go back and modify the class definitions so that each concrete exception +# stores its associated error code. +for code, ex in error_mapping.items(): + ex.h3_error_code = code + + +# +# Helper functions +# + +# TODO: Move the helpers to util? +# TODO: Unclear how/where to expose these functions. cdef/cpdef? + +cdef code_to_exception(H3Error err): + if err == E_SUCCESS: + return None + elif err in error_mapping: + return error_mapping[err] + else: + raise UnknownH3ErrorCode(err) + +cdef check_for_error(H3Error err): + ex = code_to_exception(err) + if ex: + raise ex + +# todo: There's no easy way to do `*args` in `cdef` functions, but I'm also +# not sure this even needs to be a Cython `cdef` function at all, or that +# any of the other helper functions need to be in Cython. +# todo: Revisit after we've played with this a bit. +# todo: also: maybe the extra messages aren't that much more helpful... +cdef check_for_error_msg(H3Error err, str msg): + ex = code_to_exception(err) + if ex: + raise ex(msg) diff --git a/src/h3/_cy/geo.pxd b/src/h3/_cy/geo.pxd index 1a2c1c3..40dfc34 100644 --- a/src/h3/_cy/geo.pxd +++ b/src/h3/_cy/geo.pxd @@ -1,7 +1,7 @@ from .h3lib cimport H3int -cpdef H3int geo_to_h3(double lat, double lng, int res) except 1 -cpdef (double, double) h3_to_geo(H3int h) except * -cpdef double point_dist( +cpdef H3int latlng_to_cell(double lat, double lng, int res) except 1 +cpdef (double, double) cell_to_latlng(H3int h) except * +cpdef double great_circle_distance( double lat1, double lng1, double lat2, double lng2, unit=*) except -1 diff --git a/src/h3/_cy/geo.pyx b/src/h3/_cy/geo.pyx index dc2c1d7..a606c41 100644 --- a/src/h3/_cy/geo.pyx +++ b/src/h3/_cy/geo.pyx @@ -1,226 +1,185 @@ +from libc.stdint cimport uint64_t + cimport h3lib from h3lib cimport bool, H3int + from .util cimport ( check_cell, check_edge, check_res, - create_ptr, - create_mv, deg2coord, coord2deg, ) -from libc cimport stdlib -from .util import H3ValueError +from .error_system cimport check_for_error + +from .memory cimport H3MemoryManager + +# TODO: We might be OK with taking the GIL for the functions in this module +from libc.stdlib cimport ( + # malloc as h3_malloc, # not used + calloc as h3_calloc, + realloc as h3_realloc, + free as h3_free, +) -cpdef H3int geo_to_h3(double lat, double lng, int res) except 1: +cpdef H3int latlng_to_cell(double lat, double lng, int res) except 1: cdef: - h3lib.GeoCoord c - - check_res(res) + h3lib.LatLng c + H3int out c = deg2coord(lat, lng) - return h3lib.geoToH3(&c, res) + check_for_error( + h3lib.latLngToCell(&c, res, &out) + ) + + return out -cpdef (double, double) h3_to_geo(H3int h) except *: +cpdef (double, double) cell_to_latlng(H3int h) except *: """Map an H3 cell into its centroid geo-coordinate (lat/lng)""" cdef: - h3lib.GeoCoord c + h3lib.LatLng c check_cell(h) + # todo: think about: if you give this an invalid cell, should it still return a lat/lng? + # idea: safe and unsafe APIs? - h3lib.h3ToGeo(h, &c) + check_for_error( + h3lib.cellToLatLng(h, &c) + ) return coord2deg(c) -cdef h3lib.Geofence make_geofence(geos, bool lnglat_order=False) except *: +cdef h3lib.GeoLoop make_geoloop(latlngs) except *: """ - - The returned `Geofence` must be freed with a call to `free_geofence`. + The returned `GeoLoop` must be freed with a call to `free_geoloop`. Parameters ---------- - geos : list or tuple - GeoFence: A sequence of >= 3 (lat, lng) pairs where the last + latlngs : list or tuple + GeoLoop: A sequence of >= 3 (lat, lng) pairs where the last element may or may not be same as the first (to form a closed loop). The order of the pairs may be either clockwise or counterclockwise. - lnglat_order : bool - If True, assume coordinate pairs like (lng, lat) - If False, assume coordinate pairs like (lat, lng) """ cdef: - h3lib.Geofence gf + h3lib.GeoLoop gl - gf.numVerts = len(geos) + gl.numVerts = len(latlngs) - gf.verts = stdlib.calloc(gf.numVerts, sizeof(h3lib.GeoCoord)) + # todo: need for memory management + # can automatically free? + gl.verts = h3_calloc(gl.numVerts, sizeof(h3lib.LatLng)) - if lnglat_order: - latlng = (g[::-1] for g in geos) - else: - latlng = geos + for i, (lat, lng) in enumerate(latlngs): + gl.verts[i] = deg2coord(lat, lng) - for i, (lat, lng) in enumerate(latlng): - gf.verts[i] = deg2coord(lat, lng) - - return gf + return gl -cdef free_geofence(h3lib.Geofence* gf): - stdlib.free(gf.verts) - gf.verts = NULL +cdef free_geoloop(h3lib.GeoLoop* gl): + h3_free(gl.verts) + gl.verts = NULL cdef class GeoPolygon: cdef: h3lib.GeoPolygon gp - def __cinit__(self, outer, holes=None, bool lnglat_order=False): + def __cinit__(self, outer, holes=None): """ Parameters ---------- outer : list or tuple - GeoFence - A GeoFence is a sequence of >= 3 (lat, lng) pairs where the last + GeoLoop + A GeoLoop is a sequence of >= 3 (lat, lng) pairs where the last element may or may not be same as the first (to form a closed loop). The order of the pairs may be either clockwise or counterclockwise. holes : list or tuple - A sequence of GeoFences - lnglat_order : bool - If True, assume coordinate pairs like (lng, lat) - If False, assume coordinate pairs like (lat, lng) - + A sequence of GeoLoops """ if holes is None: holes = [] - self.gp.geofence = make_geofence(outer, lnglat_order) + self.gp.geoloop = make_geoloop(outer) self.gp.numHoles = len(holes) self.gp.holes = NULL if len(holes) > 0: - self.gp.holes = stdlib.calloc(len(holes), sizeof(h3lib.Geofence)) + self.gp.holes = h3_calloc(len(holes), sizeof(h3lib.GeoLoop)) for i, hole in enumerate(holes): - self.gp.holes[i] = make_geofence(hole, lnglat_order) + self.gp.holes[i] = make_geoloop(hole) def __dealloc__(self): - free_geofence(&self.gp.geofence) + free_geoloop(&self.gp.geoloop) for i in range(self.gp.numHoles): - free_geofence(&self.gp.holes[i]) + free_geoloop(&self.gp.holes[i]) - stdlib.free(self.gp.holes) + h3_free(self.gp.holes) -def polyfill_polygon(outer, int res, holes=None, bool lnglat_order=False): - """ Set of hexagons whose center is contained in a polygon. +def polygon_to_cells(outer, int res, holes=None): + """ Get the set of cells whose center is contained in a polygon. - The polygon is defined as in the GeoJson standard, with an exterior - LinearRing `outer` and a list of LinearRings `holes`, which define any - holes in the polygon. + The polygon is defined similarity to the GeoJson standard, with an exterior + `outer` ring of lat/lng points, and a list of `holes`, each of which are also + rings of lat/lng points. - Each LinearRing may be in clockwise or counter-clockwise order + Each ring may be in clockwise or counter-clockwise order (right-hand rule or not), and may or may not be a closed loop (where the last element is equal to the first). - The GeoJSON spec requires the right-hand rule, and a closed loop, but - this function will work with any input format. + The GeoJSON spec requires the right-hand rule and a closed loop, but + this function relaxes those constraints. + + Unlike the GeoJson standard, the elements of the lat/lng pairs of each + ring are in lat/lng order, instead of lng/lat order. + + We'll handle translation to different formats in the Python code, + rather than the Cython code. Parameters ---------- outer : list or tuple - A LinearRing, a sequence of (lat/lng) or (lng/lat) pairs + A ring given by a sequence of lat/lng pairs. res : int The resolution of the output hexagons holes : list or tuple - A collection of LinearRings, describing any holes in the polygon - lnglat_order : bool - If True, assume coordinate pairs like (lng, lat) - If False, assume coordinate pairs like (lat, lng) + A collection of rings, each given by a sequence of lat/lng pairs. + These describe any the "holes" in the polygon. """ + cdef: + uint64_t n check_res(res) - gp = GeoPolygon(outer, holes=holes, lnglat_order=lnglat_order) + gp = GeoPolygon(outer, holes=holes) - n = h3lib.maxPolyfillSize(&gp.gp, res) - ptr = create_ptr(n) + check_for_error( + h3lib.maxPolygonToCellsSize(&gp.gp, res, 0, &n) + ) - h3lib.polyfill(&gp.gp, res, ptr) - mv = create_mv(ptr, n) + hmm = H3MemoryManager(n) + check_for_error( + h3lib.polygonToCells(&gp.gp, res, 0, hmm.ptr) + ) + mv = hmm.to_mv() return mv -def polyfill_geojson(geojson, int res): - """ Set of hexagons whose center is contained in a GeoJson Polygon object. - - The polygon is defined exactly as in the GeoJson standard, so - `geojson` should be a dictionary like: - { - 'type': 'Polygon', - 'coordinates': [...] - } - - 'coordinates' should be a list of LinearRings, where the first ring describes - the exterior boundary of the Polygon, and any subsequent LinearRings - describe holes in the polygon. - - Note that we don't provide an option for the order of the coordinates, - as the GeoJson standard requires them to be in lng/lat order. - - Parameters - ---------- - geojson : dict - res : int - The resolution of the output hexagons - """ - - # todo: this one could handle multipolygons... - - if geojson['type'] != 'Polygon': - raise ValueError('Only Polygon GeoJSON supported') - - coords = geojson['coordinates'] - - out = polyfill_polygon(coords[0], res, holes=coords[1:], lnglat_order=True) - - return out - - -def polyfill(dict geojson, int res, bool geo_json_conformant=False): - """ Light wrapper around `polyfill_geojson` to provide backward compatibility. - """ - - try: - gj_type = geojson['type'] - except KeyError: - raise KeyError("`geojson` dict must have key 'type'.") from None - - if gj_type != 'Polygon': - raise ValueError('Only Polygon GeoJSON supported') - - if geo_json_conformant: - out = polyfill_geojson(geojson, res) - else: - coords = geojson['coordinates'] - out = polyfill_polygon(coords[0], res, holes=coords[1:], lnglat_order=False) - - return out - - -def cell_boundary(H3int h, bool geo_json=False): +def cell_to_boundary(H3int h, bool geo_json=False): """Compose an array of geo-coordinates that outlines a hexagonal cell""" cdef: - h3lib.GeoBoundary gb + h3lib.CellBoundary gb check_cell(h) - h3lib.h3ToGeoBoundary(h, &gb) + h3lib.cellToBoundary(h, &gb) verts = tuple( coord2deg(gb.verts[i]) @@ -235,17 +194,17 @@ def cell_boundary(H3int h, bool geo_json=False): return verts -def edge_boundary(H3int edge, bool geo_json=False): - """ Returns the GeoBoundary containing the coordinates of the edge +def directed_edge_to_boundary(H3int edge, bool geo_json=False): + """ Returns the CellBoundary containing the coordinates of the edge """ cdef: - h3lib.GeoBoundary gb + h3lib.CellBoundary gb check_edge(edge) - h3lib.getH3UnidirectionalEdgeBoundary(edge, &gb) + h3lib.directedEdgeToBoundary(edge, &gb) - # todo: move this verts transform into the GeoBoundary object + # todo: move this verts transform into the CellBoundary object verts = tuple( coord2deg(gb.verts[i]) for i in range(gb.num_verts) @@ -259,7 +218,7 @@ def edge_boundary(H3int edge, bool geo_json=False): return verts -cpdef double point_dist( +cpdef double great_circle_distance( double lat1, double lng1, double lat2, double lng2, unit='km') except -1: @@ -267,12 +226,12 @@ cpdef double point_dist( b = deg2coord(lat2, lng2) if unit == 'rads': - d = h3lib.pointDistRads(&a, &b) + d = h3lib.greatCircleDistanceRads(&a, &b) elif unit == 'km': - d = h3lib.pointDistKm(&a, &b) + d = h3lib.greatCircleDistanceKm(&a, &b) elif unit == 'm': - d = h3lib.pointDistM(&a, &b) + d = h3lib.greatCircleDistanceM(&a, &b) else: - raise H3ValueError('Unknown unit: {}'.format(unit)) + raise ValueError('Unknown unit: {}'.format(unit)) return d diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index 5fa05cc..00fff60 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -1,168 +1,181 @@ -from libc cimport stdint from cpython cimport bool -from libc.stdint cimport int64_t +from libc.stdint cimport uint32_t, uint64_t, int64_t -ctypedef stdint.uint64_t H3int ctypedef basestring H3str -cdef extern from "h3api.h": +cdef extern from 'h3api.h': cdef int H3_VERSION_MAJOR cdef int H3_VERSION_MINOR cdef int H3_VERSION_PATCH - ctypedef stdint.uint64_t H3Index + ctypedef uint64_t H3int 'H3Index' - ctypedef struct GeoCoord: + ctypedef uint32_t H3Error + ctypedef enum H3ErrorCodes: + E_SUCCESS = 0 + E_FAILED = 1 + E_DOMAIN = 2 + E_LATLNG_DOMAIN = 3 + E_RES_DOMAIN = 4 + E_CELL_INVALID = 5 + E_DIR_EDGE_INVALID = 6 + E_UNDIR_EDGE_INVALID = 7 + E_VERTEX_INVALID = 8 + E_PENTAGON = 9 + E_DUPLICATE_INPUT = 10 + E_NOT_NEIGHBORS = 11 + E_RES_MISMATCH = 12 + E_MEMORY_ALLOC = 13 + E_MEMORY_BOUNDS = 14 + E_OPTION_INVALID = 15 + + ctypedef struct LatLng: double lat # in radians - double lng "lon" # in radians + double lng # in radians - ctypedef struct GeoBoundary: - int num_verts "numVerts" - GeoCoord verts[10] # MAX_CELL_BNDRY_VERTS - - ctypedef struct Geofence: - int numVerts - GeoCoord *verts - - ctypedef struct GeoPolygon: - Geofence geofence - int numHoles - Geofence *holes - - ctypedef struct GeoMultiPolygon: - int numPolygons - GeoPolygon *polygons - - ctypedef struct LinkedGeoCoord: - GeoCoord data "vertex" - LinkedGeoCoord *next - - # renaming these for clarity - ctypedef struct LinkedGeoLoop: - LinkedGeoCoord *data "first" - LinkedGeoCoord *_data_last "last" # not needed in Cython bindings - LinkedGeoLoop *next - - ctypedef struct LinkedGeoPolygon: - LinkedGeoLoop *data "first" - LinkedGeoLoop *_data_last "last" # not needed in Cython bindings - LinkedGeoPolygon *next + ctypedef struct CellBoundary: + int num_verts 'numVerts' + LatLng verts[10] # MAX_CELL_BNDRY_VERTS ctypedef struct CoordIJ: int i int j - H3Index geoToH3(const GeoCoord *g, int res) nogil + ctypedef struct LinkedLatLng: + LatLng data 'vertex' + LinkedLatLng *next - void h3ToGeo(H3Index h3, GeoCoord *g) nogil + # renaming these for clarity + ctypedef struct LinkedGeoLoop: + LinkedLatLng *data 'first' + LinkedLatLng *_data_last 'last' # not needed in Cython bindings + LinkedGeoLoop *next - void h3ToGeoBoundary(H3Index h3, GeoBoundary *gp) + ctypedef struct LinkedGeoPolygon: + LinkedGeoLoop *data 'first' + LinkedGeoLoop *_data_last 'last' # not needed in Cython bindings + LinkedGeoPolygon *next - int maxKringSize(int k) + ctypedef struct GeoLoop: + int numVerts + LatLng *verts - int hexRange(H3Index origin, int k, H3Index *out) + ctypedef struct GeoPolygon: + GeoLoop geoloop + int numHoles + GeoLoop *holes - int hexRangeDistances(H3Index origin, int k, H3Index *out, int *distances) - - int h3Distance(H3Index origin, H3Index h3) - - int hexRanges(H3Index *h3Set, int length, int k, H3Index *out) - - void kRing(H3Index origin, int k, H3Index *out) - - void kRingDistances(H3Index origin, int k, H3Index *out, int *distances) - - int hexRing(H3Index origin, int k, H3Index *out) - - int maxPolyfillSize(const GeoPolygon *geoPolygon, int res) - - void polyfill(const GeoPolygon *geoPolygon, int res, H3Index *out) - - void h3SetToLinkedGeo(const H3Index *h3Set, const int numHexes, LinkedGeoPolygon *out) - - void destroyLinkedPolygon(LinkedGeoPolygon *polygon) + int isValidCell(H3int h) nogil + int isPentagon(H3int h) nogil + int isResClassIII(H3int h) nogil + int isValidDirectedEdge(H3int edge) nogil double degsToRads(double degrees) nogil - double radsToDegs(double radians) nogil - stdint.int64_t numHexagons(int res) + int getResolution(H3int h) nogil + int getBaseCellNumber(H3int h) nogil - int h3GetResolution(H3Index h) nogil + H3Error latLngToCell(const LatLng *g, int res, H3int *out) nogil + H3Error cellToLatLng(H3int h, LatLng *) nogil + H3Error gridDistance(H3int h1, H3int h2, int64_t *distance) nogil - int h3GetBaseCell(H3Index h) + H3Error maxGridDiskSize(int k, int64_t *out) nogil # num/out/N? + H3Error gridDisk(H3int h, int k, H3int *out) nogil - H3Index stringToH3(const char *str) + H3Error cellToParent( H3int h, int parentRes, H3int *parent) nogil + H3Error cellToCenterChild(H3int h, int childRes, H3int *child) nogil - void h3ToString(H3Index h, char *str, size_t sz) + H3Error cellToChildrenSize(H3int h, int childRes, int64_t *num) nogil # num/out/N? + H3Error cellToChildren( H3int h, int childRes, H3int *children) nogil - int h3IsValid(H3Index h) + H3Error compactCells( + const H3int *cells_u, + H3int *cells_c, + const int num_u + ) nogil + H3Error uncompactCellsSize( + const H3int *cells_c, + const int64_t num_c, + const int res, + int64_t *num_u + ) nogil + H3Error uncompactCells( + const H3int *cells_c, + const int num_c, + H3int *cells_u, + const int num_u, + const int res + ) nogil - H3Index h3ToParent(H3Index h, int parentRes) nogil + H3Error getNumCells(int res, int64_t *out) nogil + int pentagonCount() nogil + int res0CellCount() nogil + H3Error getPentagons(int res, H3int *out) nogil + H3Error getRes0Cells(H3int *out) nogil - int maxH3ToChildrenSize(H3Index h, int childRes) + H3Error gridPathCellsSize(H3int start, H3int end, int64_t *size) nogil + H3Error gridPathCells(H3int start, H3int end, H3int *out) nogil - void h3ToChildren(H3Index h, int childRes, H3Index *children) + H3Error getHexagonAreaAvgKm2(int res, double *out) nogil + H3Error getHexagonAreaAvgM2(int res, double *out) nogil - int compact(const H3Index *h3Set, H3Index *compactedSet, const int numHexes) + H3Error cellAreaRads2(H3int h, double *out) nogil + H3Error cellAreaKm2(H3int h, double *out) nogil + H3Error cellAreaM2(H3int h, double *out) nogil - int maxUncompactSize(const H3Index *compactedSet, const int numHexes, const int res) + H3Error maxFaceCount(H3int h, int *out) nogil + H3Error getIcosahedronFaces(H3int h3, int *out) nogil - int uncompact(const H3Index *compactedSet, const int numHexes, H3Index *h3Set, const int maxHexes, const int res) + H3Error cellToLocalIj(H3int origin, H3int h3, uint32_t mode, CoordIJ *out) nogil + H3Error localIjToCell(H3int origin, const CoordIJ *ij, uint32_t mode, H3int *out) nogil - int h3IsResClassIII(H3Index h) + H3Error gridDiskDistances(H3int origin, int k, H3int *out, int *distances) nogil + H3Error gridRingUnsafe(H3int origin, int k, H3int *out) nogil - int h3IsPentagon(H3Index h) + H3Error areNeighborCells(H3int origin, H3int destination, int *out) nogil + H3Error cellsToDirectedEdge(H3int origin, H3int destination, H3int *out) nogil + H3Error getDirectedEdgeOrigin(H3int edge, H3int *out) nogil + H3Error getDirectedEdgeDestination(H3int edge, H3int *out) nogil + H3Error originToDirectedEdges(H3int origin, H3int *edges) nogil + # todo: directedEdgeToCells - int pentagonIndexCount() + H3Error getHexagonEdgeLengthAvgKm(int res, double *out) nogil + H3Error getHexagonEdgeLengthAvgM(int res, double *out) nogil - void getPentagonIndexes(int res, H3Index *out) + H3Error edgeLengthRads(H3int edge, double *out) nogil + H3Error edgeLengthKm(H3int edge, double *out) nogil + H3Error edgeLengthM(H3int edge, double *out) nogil - int res0IndexCount() + H3Error cellToBoundary(H3int h3, CellBoundary *gp) nogil + H3Error directedEdgeToBoundary(H3int edge, CellBoundary *gb) nogil - void getRes0Indexes(H3Index *out) + double greatCircleDistanceRads(const LatLng *a, const LatLng *b) nogil + double greatCircleDistanceKm(const LatLng *a, const LatLng *b) nogil + double greatCircleDistanceM(const LatLng *a, const LatLng *b) nogil - H3Index h3ToCenterChild(H3Index h, int res) + H3Error cellsToLinkedMultiPolygon(const H3int *h3Set, const int numCells, LinkedGeoPolygon *out) + void destroyLinkedMultiPolygon(LinkedGeoPolygon *polygon) - int h3IndexesAreNeighbors(H3Index origin, H3Index destination) + H3Error maxPolygonToCellsSize(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t *count) + H3Error polygonToCells(const GeoPolygon *geoPolygon, int res, uint32_t flags, H3int *out) - H3Index getH3UnidirectionalEdge(H3Index origin, H3Index destination) + # ctypedef struct GeoMultiPolygon: + # int numPolygons + # GeoPolygon *polygons - int h3UnidirectionalEdgeIsValid(H3Index edge) + # int hexRange(H3int origin, int k, H3int *out) - H3Index getOriginH3IndexFromUnidirectionalEdge(H3Index edge) + # int hexRangeDistances(H3int origin, int k, H3int *out, int *distances) - H3Index getDestinationH3IndexFromUnidirectionalEdge(H3Index edge) + # int hexRanges(H3int *h3Set, int length, int k, H3int *out) - void getH3IndexesFromUnidirectionalEdge(H3Index edge, H3Index *originDestination) + # void h3SetToLinkedGeo(const H3int *h3Set, const int numCells, LinkedGeoPolygon *out) - void getH3UnidirectionalEdgesFromHexagon(H3Index origin, H3Index *edges) + # void destroyLinkedPolygon(LinkedGeoPolygon *polygon) - void getH3UnidirectionalEdgeBoundary(H3Index edge, GeoBoundary *gb) + # H3int stringToH3(const char *str) - int h3LineSize(H3Index start, H3Index end) - int h3Line(H3Index start, H3Index end, H3Index *out) + # void h3ToString(H3int h, char *str, size_t sz) - int maxFaceCount(H3Index h3) - void h3GetFaces(H3Index h3, int *out) - - int experimentalH3ToLocalIj(H3Index origin, H3Index h3, CoordIJ *out) - int experimentalLocalIjToH3(H3Index origin, const CoordIJ *ij, H3Index *out) - - double hexAreaKm2(int res) nogil - double hexAreaM2(int res) nogil - - double cellAreaRads2(H3Index h) nogil - double cellAreaKm2(H3Index h) nogil - double cellAreaM2(H3Index h) nogil - - double edgeLengthKm(int res) nogil - double edgeLengthM(int res) nogil - - double exactEdgeLengthRads(H3Index edge) nogil - double exactEdgeLengthKm(H3Index edge) nogil - double exactEdgeLengthM(H3Index edge) nogil - - double pointDistRads(const GeoCoord *a, const GeoCoord *b) nogil - double pointDistKm(const GeoCoord *a, const GeoCoord *b) nogil - double pointDistM(const GeoCoord *a, const GeoCoord *b) nogil + # void getH3intesFromUnidirectionalEdge(H3int edge, H3int *originDestination) diff --git a/src/h3/_cy/memory.pxd b/src/h3/_cy/memory.pxd new file mode 100644 index 0000000..5e259e2 --- /dev/null +++ b/src/h3/_cy/memory.pxd @@ -0,0 +1,12 @@ +from .h3lib cimport H3int + +cdef class H3MemoryManager: + cdef: + size_t n + H3int* ptr + + cdef H3int[:] to_mv(self) + cdef H3int[:] to_mv_keep_zeros(self) + +cdef int[:] int_mv(size_t n) +cpdef H3int[:] iter_to_mv(cells) diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx new file mode 100644 index 0000000..0852105 --- /dev/null +++ b/src/h3/_cy/memory.pyx @@ -0,0 +1,248 @@ +from cython.view cimport array +from .h3lib cimport H3int + +""" +### Memory allocation options + +We have a few options for the memory allocation functions. +There's a trade-off between using the Python allocators which let Python +track memory usage and offers some optimizations vs the system +allocators, which do not need to acquire the GIL. +""" + +""" +System allocation functions. These do not acquire the GIL. +""" +from libc.stdlib cimport ( + # malloc as h3_malloc, # not used + calloc as h3_calloc, + realloc as h3_realloc, + free as h3_free, +) + + +""" +PyMem_Raw* functions should just be wrappers around system allocators +also given in libc.stdlib. These functions do not acquire the GIL. + +Note that these do not have a calloc function until py 3.5 and Cython 3.0, +so we would need to zero-out memory manually. + +https://python.readthedocs.io/en/stable/c-api/memory.html#raw-memory-interface +""" +# from cpython.mem cimport ( +# PyMem_RawMalloc as h3_malloc, +# # PyMem_RawCalloc as h3_calloc, # only in Python >=3.5 (and Cython >=3.0?) +# PyMem_RawRealloc as h3_realloc, +# PyMem_RawFree as h3_free, +# ) + + +""" +These functions use the Python allocator (instead of the system allocator), +which offers some optimizations for Python, and allows Python to track +memory usage. However, these functions must acquire the GIL. + +Note that these do not have a calloc function until py 3.5 and Cython 3.0, +so we would need to zero-out memory manually. + +https://cython.readthedocs.io/en/stable/src/tutorial/memory_allocation.html +https://python.readthedocs.io/en/stable/c-api/memory.html#memory-interface +""" +# from cpython.mem cimport ( +# PyMem_Malloc as h3_malloc, +# # PyMem_Calloc as h3_calloc, # only in Python >=3.5 (and Cython >=3.0?) +# PyMem_Realloc as h3_realloc, +# PyMem_Free as h3_free, +# ) + + +cdef size_t move_nonzeros(H3int* a, size_t n): + """ Move nonzero elements to front of array `a` of length `n`. + Return the number of nonzero elements. + + Loop invariant: Everything *before* `i` or *after* `j` is "done". + Move `i` and `j` inwards until they equal, and exit. + You can move `i` forward until there's a zero in front of it. + You can move `j` backward until there's a nonzero to the left of it. + Anything to the right of `j` is "junk" that can be reallocated. + + | a | b | 0 | c | d | ... | + ^ ^ + i j + + + | a | b | d | c | d | ... | + ^ ^ + i j + """ + cdef: + size_t i = 0 + size_t j = n + + while i < j: + if a[j-1] == 0: + j -= 1 + continue + + if a[i] != 0: + i += 1 + continue + + # if we're here, we know: + # a[i] == 0 + # a[j-1] != 0 + # i < j + # so we can swap! (actually, move a[j-1] -> a[i]) + a[i] = a[j-1] + j -= 1 + + return i + + +cdef H3int[:] empty_memory_view(): + # todo: get rid of this? + # there's gotta be a better way to do this... + # create an empty cython.view.array? + cdef: + H3int a[1] + + return (a)[:0] + + +cdef _remove_zeros(H3MemoryManager x): + x.n = move_nonzeros(x.ptr, x.n) + + if x.n == 0: + h3_free(x.ptr) + x.ptr = NULL + else: + x.ptr = h3_realloc(x.ptr, x.n*sizeof(H3int)) + if not x.ptr: + raise MemoryError() + + +cdef H3int[:] _copy_to_mv(const H3int* ptr, size_t n): + cdef: + array arr + + arr = ptr + arr.callback_free_data = h3_free + + return arr + + +cdef H3int[:] _create_mv(H3MemoryManager x): + if x.n == 0: + h3_free(x.ptr) + x.ptr = NULL + mv = empty_memory_view() + else: + mv = _copy_to_mv(x.ptr, x.n) + + # responsibility for the memory moves from this object to the array/memoryview + x.ptr = NULL + x.n = 0 + + return mv + + +""" +TODO: The not None declaration for the argument automatically rejects None values as input, which would otherwise be allowed. The reason why None is allowed by default is that it is conveniently used for return arguments: + https://cython.readthedocs.io/en/latest/src/userguide/memoryviews.html#syntax + +TODO: potential optimization: https://cython.readthedocs.io/en/latest/src/userguide/memoryviews.html#performance-disabling-initialization-checks + +## future improvements: + +- abolish any appearance of &thing[0]. (i.e., identical interfaces) +- can i make the interface for all these memory views identical? +""" + +cdef class H3MemoryManager: + """ + Cython object in charge of allocating and freeing memory for arrays + of H3 indexes. + + Initially allocates memory and provides access through `self.ptr` and + `self.n`. + + The `to_mv()` function removes responsibility for the allocated memory + from this object to a memory view object. A memory view object automatically + deallocates its memory during garbage collection. + + If the H3MemoryManager is garbage collected before running `to_mv()`, + it will deallocate its memory itself. + + This pattern is useful for a few reasons: + + - provide convenient access to the raw memory pointer and length for passing + to h3lib functions + - remove zeroes from the array output (some h3lib functions may return + results with zeros/H3NULL values) + - cython and python array types have weird interfaces; memoryviews are + much cleaner + + If we find a better way to do these then this class may no longer be + necessary. + + TODO: consider a context manager pattern + """ + def __cinit__(self, size_t n): + self.n = n + self.ptr = h3_calloc(self.n, sizeof(H3int)) + + if not self.ptr: + raise MemoryError() + + cdef H3int[:] to_mv_keep_zeros(self): + # todo: this could be a private method + return _create_mv(self) + + cdef H3int[:] to_mv(self): + _remove_zeros(self) + return _create_mv(self) + + def __dealloc__(self): + # If the memory has been handed off to a memoryview, this pointer + # should be NULL, and deallocing on NULL is fine. + # If the pointer is *not* NULL, then this means the MemoryManager + # has is still responsible for the memory (it hasn't given the memory away to another object). + h3_free(self.ptr) + + +""" +todo: combine with the H3MemoryManager using fused types? +https://cython.readthedocs.io/en/stable/src/userguide/fusedtypes.html +""" +cdef int[:] int_mv(size_t n): + cdef: + array arr + + if n == 0: + raise MemoryError() + else: + ptr = h3_calloc(n, sizeof(int)) + if ptr is NULL: + raise MemoryError() + + arr = ptr + arr.callback_free_data = h3_free + + return arr + + +cpdef H3int[:] iter_to_mv(cells): + """ cells needs to be an iterable that knows its size... + or should we have it match the np.fromiter function, which infers if not available? + """ + cdef: + H3int[:] mv + + n = len(cells) + mv = H3MemoryManager(n).to_mv_keep_zeros() + + for i,h in enumerate(cells): + mv[i] = h + + return mv diff --git a/src/h3/_cy/to_multipoly.pyx b/src/h3/_cy/to_multipoly.pyx index 8e5ca55..d19bda8 100644 --- a/src/h3/_cy/to_multipoly.pyx +++ b/src/h3/_cy/to_multipoly.pyx @@ -23,7 +23,7 @@ cdef walk_loops(const h3lib.LinkedGeoLoop* L): return out -cdef walk_coords(const h3lib.LinkedGeoCoord* L): +cdef walk_coords(const h3lib.LinkedLatLng* L): out = [] while L: out += [coord2deg(L.data)] @@ -32,20 +32,20 @@ cdef walk_coords(const h3lib.LinkedGeoCoord* L): return out # todo: tuples instead of lists? -def _to_multi_polygon(const H3int[:] hexes): +def _to_multi_polygon(const H3int[:] cells): cdef: h3lib.LinkedGeoPolygon polygon - for h in hexes: + for h in cells: check_cell(h) - h3lib.h3SetToLinkedGeo(&hexes[0], len(hexes), &polygon) + h3lib.cellsToLinkedMultiPolygon(&cells[0], len(cells), &polygon) out = walk_polys(&polygon) # we're still responsible for cleaning up the passed in `polygon`, # but not a problem here, since it is stack allocated - h3lib.destroyLinkedPolygon(&polygon) + h3lib.destroyLinkedMultiPolygon(&polygon) return out @@ -59,12 +59,12 @@ def _geojson_loop(loop): return loop -def h3_set_to_multi_polygon(const H3int[:] hexes, geo_json=False): +def cells_to_multi_polygon(const H3int[:] cells, geo_json=False): # todo: gotta be a more elegant way to handle these... - if len(hexes) == 0: + if len(cells) == 0: return [] - multipoly = _to_multi_polygon(hexes) + multipoly = _to_multi_polygon(cells) if geo_json: multipoly = [ diff --git a/src/h3/_cy/unstable_vect.pyx b/src/h3/_cy/unstable_vect.pyx deleted file mode 100644 index 316ac12..0000000 --- a/src/h3/_cy/unstable_vect.pyx +++ /dev/null @@ -1,89 +0,0 @@ -cimport h3lib -from h3lib cimport H3int -from .util cimport deg2coord - -from cython cimport boundscheck, wraparound -from libc.math cimport sqrt, sin, cos, asin - -cdef double haversineDistance(double th1, double ph1, double th2, double ph2) nogil: - cdef: - double dx, dy, dz - double R = 6371.0088 - - ph1 -= ph2 - - dz = sin(th1) - sin(th2) - dx = cos(ph1) * cos(th1) - cos(th2) - dy = sin(ph1) * cos(th1) - - return asin(sqrt(dx*dx + dy*dy + dz*dz) / 2)*2*R - - -@boundscheck(False) -@wraparound(False) -cpdef void haversine_vect( - const H3int[:] a, - const H3int[:] b, - double[:] out -) nogil: - - cdef h3lib.GeoCoord p1, p2 - - with nogil: - # todo: add these back in when cython 3.0 comes out - #assert len(a) == len(b) - #assert len(a) <= len(out) - - for i in range(len(a)): - h3lib.h3ToGeo(a[i], &p1) - h3lib.h3ToGeo(b[i], &p2) - out[i] = haversineDistance( - p1.lat, p1.lng, - p2.lat, p2.lng - ) - - -@boundscheck(False) -@wraparound(False) -cpdef void geo_to_h3_vect( - const double[:] lat, - const double[:] lng, - int res, - H3int[:] out -) nogil: - - cdef h3lib.GeoCoord c - - with nogil: - for i in range(len(lat)): - c = deg2coord(lat[i], lng[i]) - out[i] = h3lib.geoToH3(&c, res) - - -@boundscheck(False) -@wraparound(False) -cpdef void h3_to_parent_vect( - const H3int[:] h, - int[:] res, - H3int[:] out -) nogil: - - cdef Py_ssize_t i - - with nogil: - for i in range(len(h)): - out[i] = h3lib.h3ToParent(h[i], res[i]) - - -@boundscheck(False) -@wraparound(False) -cpdef void h3_get_resolution_vect( - const H3int[:] h, - int[:] out, -) nogil: - - cdef Py_ssize_t i - - with nogil: - for i in range(len(h)): - out[i] = h3lib.h3GetResolution(h[i]) diff --git a/src/h3/_cy/util.pxd b/src/h3/_cy/util.pxd index 06cc26a..15e97ad 100644 --- a/src/h3/_cy/util.pxd +++ b/src/h3/_cy/util.pxd @@ -1,18 +1,12 @@ -from .h3lib cimport H3int, H3str, GeoCoord +from .h3lib cimport H3int, H3str, LatLng -cdef GeoCoord deg2coord(double lat, double lng) nogil -cdef (double, double) coord2deg(GeoCoord c) nogil - -cpdef H3int hex2int(H3str h) except? 0 -cpdef H3str int2hex(H3int x) - -cdef H3int* create_ptr(size_t n) except? NULL -cdef H3int[:] create_mv(H3int* ptr, size_t n) +cdef LatLng deg2coord(double lat, double lng) nogil +cdef (double, double) coord2deg(LatLng c) nogil +cpdef H3int str_to_int(H3str h) except? 0 +cpdef H3str int_to_str(H3int x) cdef check_cell(H3int h) cdef check_edge(H3int e) cdef check_res(int res) cdef check_distance(int k) - -cdef H3int[:] empty_memory_view() # want to drop this if possible diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index dbf17da..8bc061d 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -1,13 +1,17 @@ -from libc cimport stdlib -from cython.view cimport array -from .h3lib cimport H3int, H3str, h3IsValid, h3UnidirectionalEdgeIsValid +from .h3lib cimport H3int, H3str, isValidCell, isValidDirectedEdge cimport h3lib +from .error_system import ( + H3ResDomainError, + H3DomainError, + H3DirEdgeInvalidError, + H3CellInvalidError, +) -cdef h3lib.GeoCoord deg2coord(double lat, double lng) nogil: +cdef h3lib.LatLng deg2coord(double lat, double lng) nogil: cdef: - h3lib.GeoCoord c + h3lib.LatLng c c.lat = h3lib.degsToRads(lat) c.lng = h3lib.degsToRads(lng) @@ -15,7 +19,7 @@ cdef h3lib.GeoCoord deg2coord(double lat, double lng) nogil: return c -cdef (double, double) coord2deg(h3lib.GeoCoord c) nogil: +cdef (double, double) coord2deg(h3lib.LatLng c) nogil: return ( h3lib.radsToDegs(c.lat), h3lib.radsToDegs(c.lng) @@ -32,11 +36,11 @@ cpdef basestring c_version(): return '{}.{}.{}'.format(*v) -cpdef H3int hex2int(H3str h) except? 0: +cpdef H3int str_to_int(H3str h) except? 0: return int(h, 16) -cpdef H3str int2hex(H3int x): +cpdef H3str int_to_str(H3int x): """ Convert H3 integer to hex string representation Need to be careful in Python 2 because `hex(x)` may return a string @@ -48,21 +52,6 @@ cpdef H3str int2hex(H3int x): return '{:x}'.format(x) -class H3ValueError(ValueError): - pass - -class H3CellError(H3ValueError): - pass - -class H3EdgeError(H3ValueError): - pass - -class H3ResolutionError(H3ValueError): - pass - -class H3DistanceError(H3ValueError): - pass - cdef check_cell(H3int h): """ Check if valid H3 "cell" (hexagon or pentagon). @@ -72,126 +61,24 @@ cdef check_cell(H3int h): we want the error message to be informative to the user in either case. - We use the builtin `hex` function instead of `int2hex` to + We use the builtin `hex` function instead of `int_to_str` to prepend `0x` to indicate that this **integer** representation is incorrect, but in a format that is easily compared to `str` inputs. """ - if h3IsValid(h) == 0: - raise H3CellError('Integer is not a valid H3 cell: {}'.format(hex(h))) + if isValidCell(h) == 0: + raise H3CellInvalidError('Integer is not a valid H3 cell: {}'.format(hex(h))) cdef check_edge(H3int e): - if h3UnidirectionalEdgeIsValid(e) == 0: - raise H3EdgeError('Integer is not a valid H3 edge: {}'.format(hex(e))) + if isValidDirectedEdge(e) == 0: + raise H3DirEdgeInvalidError('Integer is not a valid H3 edge: {}'.format(hex(e))) cdef check_res(int res): if (res < 0) or (res > 15): - raise H3ResolutionError(res) + raise H3ResDomainError(res) cdef check_distance(int k): if k < 0: - raise H3DistanceError( + raise H3DomainError( 'Grid distances must be nonnegative. Received: {}'.format(k) ) - - -## todo: can i turn these two into a context manager? -cdef H3int* create_ptr(size_t n) except? NULL: - cdef H3int* ptr = stdlib.calloc(n, sizeof(H3int)) - if (n > 0) and (not ptr): - raise MemoryError() - - return ptr - - -cdef H3int[:] create_mv(H3int* ptr, size_t n): - cdef: - array x - - n = move_nonzeros(ptr, n) - if n <= 0: - stdlib.free(ptr) - return empty_memory_view() - - ptr = stdlib.realloc(ptr, n*sizeof(H3int)) - - if ptr is NULL: - raise MemoryError() - - x = ptr - x.callback_free_data = stdlib.free - - return x - - -cpdef H3int[:] from_iter(hexes): - """ hexes needs to be an iterable that knows its size... - or should we have it match the np.fromiter function, which infers if not available? - """ - cdef: - array x - size_t n - n = len(hexes) - - if n == 0: - return empty_memory_view() - - x = create_ptr(n) - x.callback_free_data = stdlib.free - - for i,h in enumerate(hexes): - x[i] = h - - return x - - -cdef size_t move_nonzeros(H3int* a, size_t n): - """ Move nonzero elements to front of array `a` of length `n`. - Return the number of nonzero elements. - - Loop invariant: Everything *before* `i` or *after* `j` is "done". - Move `i` and `j` inwards until they equal, and exit. - You can move `i` forward until there's a zero in front of it. - You can move `j` backward until there's a nonzero to the left of it. - Anything to the right of `j` is "junk" that can be reallocated. - - | a | b | 0 | c | d | ... | - ^ ^ - i j - - - | a | b | d | c | d | ... | - ^ ^ - i j - """ - cdef: - size_t i = 0 - size_t j = n - - while i < j: - if a[j-1] == 0: - j -= 1 - continue - - if a[i] != 0: - i += 1 - continue - - # if we're here, we know: - # a[i] == 0 - # a[j-1] != 0 - # i < j - # so we can swap! (actually, move a[j-1] -> a[i]) - a[i] = a[j-1] - j -= 1 - - return i - - -cdef H3int[:] empty_memory_view(): - # there's gotta be a better way to do this... - # create an empty cython.view.array? - cdef: - H3int a[1] - - return (a)[:0] diff --git a/src/h3/_polygon.py b/src/h3/_polygon.py new file mode 100644 index 0000000..6ef2e94 --- /dev/null +++ b/src/h3/_polygon.py @@ -0,0 +1,52 @@ +class Polygon: + """ + Container for loops of lat/lng points describing a polygon. + + Attributes + ---------- + outer : list[tuple[float, float]] + List of lat/lng points describing the outer loop of the Polygon + + holes : list[list[tuple[float, float]]] + List of loops of lat/lng points describing the holes of the Polygon + + Examples + -------- + + A polygon with a single outer ring consisting of 4 points, having no holes: + + >>> h3.Polygon( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)], + ... ) + + + The same polygon, but with one hole consisting of 3 points: + + >>> h3.Polygon( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)], + ... [(37.76, -122.51), (37.76, -122.44), (37.81, -122.51)], + ... ) + + + The same as above, but with one additional hole, made up of 5 points: + + >>> h3.Polygon( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)], + ... [(37.76, -122.51), (37.76, -122.44), (37.81, -122.51)], + ... [(37.71, -122.43), (37.71, -122.37), (37.73, -122.37), (37.75, -122.41), + ... (37.73, -122.43)], + ... ) + + + """ + def __init__(self, outer, *holes): + self.outer = outer + self.holes = holes + + def __repr__(self): + s = ''.format( + len(self.outer), + tuple(map(len, self.holes)), + ) + + return s diff --git a/src/h3/_version.py b/src/h3/_version.py index eb5cae0..41540d5 100644 --- a/src/h3/_version.py +++ b/src/h3/_version.py @@ -1,24 +1,25 @@ -__version__ = '3.7.4' +__version__ = '4.0.0' __description__ = 'Hierarchical hexagonal geospatial indexing system' __url__ = 'https://github.com/uber/h3-py' -__license__ = "Apache 2.0 License" +__license__ = 'Apache 2.0 License' __author__ = 'Uber Technologies' __author_email__ = 'AJ Friend ' __classifiers__ = [ - "Development Status :: 5 - Production/Stable", - "Intended Audience :: Developers", - "Intended Audience :: Science/Research", - "License :: OSI Approved :: Apache Software License", - "Programming Language :: C", - "Programming Language :: Cython", - "Programming Language :: Python :: 2.7", - "Programming Language :: Python :: 3.5", - "Programming Language :: Python :: 3.6", - "Programming Language :: Python :: 3.7", - "Programming Language :: Python :: 3.8", - "Programming Language :: Python :: 3.9", - "Operating System :: MacOS :: MacOS X", - "Operating System :: POSIX :: Linux", - "Operating System :: Microsoft :: Windows", - "Topic :: Scientific/Engineering :: GIS", + 'Development Status :: 5 - Production/Stable', + 'Intended Audience :: Developers', + 'Intended Audience :: Science/Research', + 'License :: OSI Approved :: Apache Software License', + 'Programming Language :: C', + 'Programming Language :: Cython', + 'Programming Language :: Python :: 2.7', + 'Programming Language :: Python :: 3.5', + 'Programming Language :: Python :: 3.6', + 'Programming Language :: Python :: 3.7', + 'Programming Language :: Python :: 3.8', + 'Programming Language :: Python :: 3.9', + 'Programming Language :: Python :: 3.10', + 'Operating System :: MacOS :: MacOS X', + 'Operating System :: POSIX :: Linux', + 'Operating System :: Microsoft :: Windows', + 'Topic :: Scientific/Engineering :: GIS', ] diff --git a/src/h3/api/_api_template.py b/src/h3/api/_api_template.py index 499c040..7baa27e 100644 --- a/src/h3/api/_api_template.py +++ b/src/h3/api/_api_template.py @@ -38,6 +38,7 @@ be skipped due to it being inside the `_api_functions` function. """ from .. import _cy +from .._polygon import Polygon class _API_FUNCTIONS(object): @@ -78,7 +79,7 @@ class _API_FUNCTIONS(object): return v @staticmethod - def string_to_h3(h): + def str_to_int(h): """ Converts a hexadecimal string to an H3 64-bit integer index. @@ -92,10 +93,10 @@ class _API_FUNCTIONS(object): int Unsigned 64-bit integer """ - return _cy.hex2int(h) + return _cy.str_to_int(h) @staticmethod - def h3_to_string(x): + def int_to_str(x): """ Converts an H3 64-bit integer index to a hexadecimal string. @@ -109,10 +110,10 @@ class _API_FUNCTIONS(object): str Hexadecimal string like ``'89754e64993ffff'`` """ - return _cy.int2hex(x) + return _cy.int_to_str(x) @staticmethod - def num_hexagons(resolution): + def get_num_cells(res): """ Return the total number of *cells* (hexagons and pentagons) for the given resolution. @@ -121,10 +122,10 @@ class _API_FUNCTIONS(object): ------- int """ - return _cy.num_hexagons(resolution) + return _cy.get_num_cells(res) @staticmethod - def hex_area(resolution, unit='km^2'): + def average_hexagon_area(res, unit='km^2'): """ Return the average area of an H3 *hexagon* for the given resolution. @@ -135,11 +136,10 @@ class _API_FUNCTIONS(object): ------- float """ - # todo: `mean_hex_area` in 4.0 - return _cy.mean_hex_area(resolution, unit) + return _cy.average_hexagon_area(res, unit) @staticmethod - def edge_length(resolution, unit='km'): + def average_hexagon_edge_length(res, unit='km'): """ Return the average *hexagon* edge length for the given resolution. @@ -150,10 +150,9 @@ class _API_FUNCTIONS(object): ------- float """ - # todo: `mean_edge_length` in 4.0 - return _cy.mean_edge_length(resolution, unit) + return _cy.average_hexagon_edge_length(res, unit) - def h3_is_valid(self, h): + def is_valid_cell(self, h): """ Validates an H3 cell (hexagon or pentagon). @@ -163,11 +162,11 @@ class _API_FUNCTIONS(object): """ try: h = self._in_scalar(h) - return _cy.is_cell(h) + return _cy.is_valid_cell(h) except (ValueError, TypeError): return False - def h3_unidirectional_edge_is_valid(self, edge): + def is_valid_directed_edge(self, edge): """ Validates an H3 unidirectional edge. @@ -177,11 +176,11 @@ class _API_FUNCTIONS(object): """ try: e = self._in_scalar(edge) - return _cy.is_edge(e) + return _cy.is_valid_directed_edge(e) except (ValueError, TypeError): return False - def geo_to_h3(self, lat, lng, resolution): + def latlng_to_cell(self, lat, lng, res): """ Return the cell containing the (lat, lng) point for a given resolution. @@ -191,9 +190,9 @@ class _API_FUNCTIONS(object): H3Cell """ - return self._out_scalar(_cy.geo_to_h3(lat, lng, resolution)) + return self._out_scalar(_cy.latlng_to_cell(lat, lng, res)) - def h3_to_geo(self, h): + def cell_to_latlng(self, h): """ Return the center point of an H3 cell as a lat/lng pair. @@ -208,9 +207,9 @@ class _API_FUNCTIONS(object): lng : float Longitude """ - return _cy.h3_to_geo(self._in_scalar(h)) + return _cy.cell_to_latlng(self._in_scalar(h)) - def h3_get_resolution(self, h): + def get_resolution(self, h): """ Return the resolution of an H3 cell. @@ -223,9 +222,9 @@ class _API_FUNCTIONS(object): int """ # todo: could also work for edges - return _cy.resolution(self._in_scalar(h)) + return _cy.get_resolution(self._in_scalar(h)) - def h3_to_parent(self, h, res=None): + def cell_to_parent(self, h, res=None): """ Get the parent of a cell. @@ -241,12 +240,12 @@ class _API_FUNCTIONS(object): H3Cell """ h = self._in_scalar(h) - p = _cy.parent(h, res) + p = _cy.cell_to_parent(h, res) p = self._out_scalar(p) return p - def h3_distance(self, h1, h2): + def grid_distance(self, h1, h2): """ Compute the H3 distance between two cells. @@ -254,7 +253,7 @@ class _API_FUNCTIONS(object): path between the cells in the graph formed by connecting adjacent cells. - This function will return an H3ValueError if the + This function will raise an exception if the cells are too far apart to compute the distance. Parameters @@ -269,11 +268,11 @@ class _API_FUNCTIONS(object): h1 = self._in_scalar(h1) h2 = self._in_scalar(h2) - d = _cy.distance(h1, h2) + d = _cy.grid_distance(h1, h2) return d - def h3_to_geo_boundary(self, h, geo_json=False): + def cell_to_boundary(self, h, geo_json=False): """ Return tuple of lat/lng pairs describing the cell boundary. @@ -291,9 +290,9 @@ class _API_FUNCTIONS(object): ------- tuple of (float, float) tuples """ - return _cy.cell_boundary(self._in_scalar(h), geo_json) + return _cy.cell_to_boundary(self._in_scalar(h), geo_json) - def k_ring(self, h, k=1): + def grid_disk(self, h, k=1): """ Return unordered set of cells with H3 distance ``<= k`` from ``h``. That is, the "filled-in" disk. @@ -308,24 +307,11 @@ class _API_FUNCTIONS(object): ------- unordered collection of H3Cell """ - mv = _cy.disk(self._in_scalar(h), k) + mv = _cy.grid_disk(self._in_scalar(h), k) return self._out_unordered(mv) - def hex_range(self, h, k=1): - """ - Alias for `k_ring`. - "Filled-in" disk. - - Notes - ----- - This name differs from the C API. - """ - mv = _cy.disk(self._in_scalar(h), k) - - return self._out_unordered(mv) - - def hex_ring(self, h, k=1): + def grid_ring(self, h, k=1): """ Return unordered set of cells with H3 distance ``== k`` from ``h``. That is, the "hollow" ring. @@ -340,55 +326,13 @@ class _API_FUNCTIONS(object): ------- unordered collection of H3Cell """ - mv = _cy.ring(self._in_scalar(h), k) + mv = _cy.grid_ring(self._in_scalar(h), k) return self._out_unordered(mv) - def hex_range_distances(self, h, K): + def cell_to_children(self, h, res=None): """ - Ordered list of the "hollow" rings around ``h``, - up to and including distance ``K``. - - Parameters - ---------- - h : H3Cell - K : int - Largest distance considered. - - Returns - ------- - ordered collection of (unordered collection of H3Cell) - """ - h = self._in_scalar(h) - - out = [ - self._out_unordered(_cy.ring(h, k)) - for k in range(K + 1) - ] - - return out - - def hex_ranges(self, hexes, K): - """ - Returns the dictionary ``{h: hex_range_distances(h, K) for h in hexes}`` - - Returns - ------- - Dict[H3Cell, List[ UnorderedCollection[H3Cell] ]] - """ - # todo: can we drop this function? the user can implement if needed. - # TODO: should we call `out_scalar` on the dict keys? - out = {h: self.hex_range_distances(h, K) for h in hexes} - - return out - - def k_ring_distances(self, h, K): - """Alias for `hex_range_distances`.""" - return self.hex_range_distances(h, K) - - def h3_to_children(self, h, res=None): - """ - Children of a hexagon. + Children of a cell. Parameters ---------- @@ -401,12 +345,12 @@ class _API_FUNCTIONS(object): ------- unordered collection of H3Cell """ - mv = _cy.children(self._in_scalar(h), res) + mv = _cy.cell_to_children(self._in_scalar(h), res) return self._out_unordered(mv) # todo: nogil for expensive C operation? - def compact(self, hexes): + def compact_cells(self, cells): """ Compact a collection of H3 cells by combining smaller cells into larger cells, if all child cells @@ -414,27 +358,27 @@ class _API_FUNCTIONS(object): Parameters ---------- - hexes : iterable of H3Cell + cells : iterable of H3 Cells Returns ------- unordered collection of H3Cell """ - # todo: does compact work on mixed-resolution collections? - hu = self._in_collection(hexes) - hc = _cy.compact(hu) + # todo: does compact_cells work on mixed-resolution collections? + hu = self._in_collection(cells) + hc = _cy.compact_cells(hu) return self._out_unordered(hc) - def uncompact(self, hexes, res): + def uncompact_cells(self, cells, res): """ - Reverse the `compact` operation. + Reverse the `compact_cells` operation. Return a collection of H3 cells, all of resolution ``res``. Parameters ---------- - hexes : iterable of H3Cell + cells : iterable of H3Cell res : int Resolution of desired output cells. @@ -445,93 +389,82 @@ class _API_FUNCTIONS(object): Raises ------ todo: add test to make sure an error is returned when input - contains hex smaller than output res. + contains cell smaller than output res. https://github.com/uber/h3/blob/master/src/h3lib/lib/h3Index.c#L425 """ - hc = self._in_collection(hexes) - hu = _cy.uncompact(hc, res) + hc = self._in_collection(cells) + hu = _cy.uncompact_cells(hc, res) return self._out_unordered(hu) - def h3_set_to_multi_polygon(self, hexes, geo_json=False): + def polygon_to_cells(self, polygon, res): """ - Get GeoJSON-like MultiPolygon describing the outline of the area + Return the set of H3 cells at a given resolution whose center points + are contained within a `h3.Polygon` + + Parameters + ---------- + Polygon : h3.Polygon + A polygon described by an outer ring and optional holes + + res : int + Resolution of the output cells + + Examples + -------- + + >>> poly = h3.Polygon( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), + ... (37.82, -122.54)], + ... ) + >>> h3.polygon_to_cells(poly, 6) + {'862830807ffffff', + '862830827ffffff', + '86283082fffffff', + '862830877ffffff', + '862830947ffffff', + '862830957ffffff', + '86283095fffffff'} + """ + mv = _cy.polygon_to_cells(polygon.outer, res, holes=polygon.holes) + + return self._out_unordered(mv) + + # def polygons_to_cells(self, polygons, res): + # # todo: have to figure out how to concat memoryviews cleanly + # # or some other approach + # pass + + def cells_to_polygons(self, cells): + """ + Return a list of h3.Polygon objects describing the area covered by a set of H3 cells. Parameters ---------- - hexes : unordered collection of H3Cell - geo_json : bool, optional - If `True`, output geo sequences will be lng/lat pairs, with the - last the same as the first. - If `False`, output geo sequences will be lat/lng pairs, with the - last distinct from the first. - Defaults to `False` + cells : iterable of H3 cells Returns ------- - list - List of "polygons". - Each polygon is a list of "geo sequences" like - ``[outer, hole1, hole2, ...]``. The holes may not be present. - Each geo sequence is a list of lat/lng or lng/lat pairs. + list[h3.Polygon] + List of h3.Polygon objects + + Examples + -------- + + >>> cells = ['8428309ffffffff', '842830dffffffff'] + >>> h3.cells_to_polygons(cells) + [] + """ - # todo: this function output does not match with `polyfill`. - # This function returns a list of polygons, while `polyfill` returns - # a GeoJSON-like dictionary object. - hexes = self._in_collection(hexes) - return _cy.h3_set_to_multi_polygon(hexes, geo_json=geo_json) + cells = self._in_collection(cells) + geos = _cy.cells_to_multi_polygon(cells) - def polyfill_polygon(self, outer, res, holes=None, lnglat_order=False): - mv = _cy.polyfill_polygon(outer, res, holes=holes, lnglat_order=lnglat_order) + polys = [Polygon(*geo) for geo in geos] - return self._out_unordered(mv) + return polys - def polyfill_geojson(self, geojson, res): - mv = _cy.polyfill_geojson(geojson, res) - - return self._out_unordered(mv) - - def polyfill(self, geojson, res, geo_json_conformant=False): - """ - Get set of hexagons whose *centers* are contained within - a GeoJSON-style polygon. - - Parameters - ---------- - geojson : dict - GeoJSON-style input dictionary describing a polygon (optionally - including holes). - - Dictionary should be formatted like: - - .. code-block:: text - - { - 'type': 'Polygon', - 'coordinates': [outer, hole1, hole2, ...], - } - - `outer`, `hole1`, etc., are lists of geo coordinate tuples. - The holes are optional. - - res : int - Desired output resolution for cells. - geo_json_conformant : bool, optional - When ``True``, ``outer``, ``hole1``, etc. must be sequences of - lng/lat pairs, with the last the same as the first. - When ``False``, they must be sequences of lat/lng pairs, - with the last not needing to match the first. - - Returns - ------- - unordered collection of H3Cell - """ - mv = _cy.polyfill(geojson, res, geo_json_conformant=geo_json_conformant) - - return self._out_unordered(mv) - - def h3_is_pentagon(self, h): + def is_pentagon(self, h): """ Identify if an H3 cell is a pentagon. @@ -546,12 +479,12 @@ class _API_FUNCTIONS(object): Notes ----- - A pentagon should *also* pass ``h3_is_cell()``. + A pentagon should *also* pass ``is_valid_cell()``. Will return ``False`` for valid H3Edge. """ return _cy.is_pentagon(self._in_scalar(h)) - def h3_get_base_cell(self, h): + def get_base_cell_number(self, h): """ Return the base cell *number* (``0`` to ``121``) of the given cell. @@ -571,9 +504,9 @@ class _API_FUNCTIONS(object): ------- int """ - return _cy.get_base_cell(self._in_scalar(h)) + return _cy.get_base_cell_number(self._in_scalar(h)) - def h3_indexes_are_neighbors(self, h1, h2): + def are_neighbor_cells(self, h1, h2): """ Returns ``True`` if ``h1`` and ``h2`` are neighboring cells. @@ -589,9 +522,9 @@ class _API_FUNCTIONS(object): h1 = self._in_scalar(h1) h2 = self._in_scalar(h2) - return _cy.are_neighbors(h1, h2) + return _cy.are_neighbor_cells(h1, h2) - def get_h3_unidirectional_edge(self, origin, destination): + def cells_to_directed_edge(self, origin, destination): """ Create an H3 Index denoting a unidirectional edge. @@ -614,12 +547,12 @@ class _API_FUNCTIONS(object): """ o = self._in_scalar(origin) d = self._in_scalar(destination) - e = _cy.edge(o, d) + e = _cy.cells_to_directed_edge(o, d) e = self._out_scalar(e) return e - def get_origin_h3_index_from_unidirectional_edge(self, e): + def get_directed_edge_origin(self, e): """ Origin cell from an H3 directed edge. @@ -632,12 +565,12 @@ class _API_FUNCTIONS(object): H3Cell """ e = self._in_scalar(e) - o = _cy.edge_origin(e) + o = _cy.get_directed_edge_origin(e) o = self._out_scalar(o) return o - def get_destination_h3_index_from_unidirectional_edge(self, e): + def get_directed_edge_destination(self, e): """ Destination cell from an H3 directed edge. @@ -650,12 +583,12 @@ class _API_FUNCTIONS(object): H3Cell """ e = self._in_scalar(e) - d = _cy.edge_destination(e) + d = _cy.get_directed_edge_destination(e) d = self._out_scalar(d) return d - def get_h3_indexes_from_unidirectional_edge(self, e): + def directed_edge_to_cells(self, e): """ Return (origin, destination) tuple from H3 directed edge @@ -671,12 +604,12 @@ class _API_FUNCTIONS(object): Destination cell of edge """ e = self._in_scalar(e) - o, d = _cy.edge_cells(e) + o, d = _cy.directed_edge_to_cells(e) o, d = self._out_scalar(o), self._out_scalar(d) return o, d - def get_h3_unidirectional_edges_from_hexagon(self, origin): + def origin_to_directed_edges(self, origin): """ Return all directed edges starting from ``origin`` cell. @@ -688,14 +621,14 @@ class _API_FUNCTIONS(object): ------- unordered collection of H3Edge """ - mv = _cy.edges_from_cell(self._in_scalar(origin)) + mv = _cy.origin_to_directed_edges(self._in_scalar(origin)) return self._out_unordered(mv) - def get_h3_unidirectional_edge_boundary(self, edge, geo_json=False): - return _cy.edge_boundary(self._in_scalar(edge), geo_json=geo_json) + def directed_edge_to_boundary(self, edge, geo_json=False): + return _cy.directed_edge_to_boundary(self._in_scalar(edge), geo_json=geo_json) - def h3_line(self, start, end): + def grid_path_cells(self, start, end): """ Returns the ordered collection of cells denoting a minimum-length non-unique path between cells. @@ -710,11 +643,11 @@ class _API_FUNCTIONS(object): ordered collection of H3Cell Starting with ``start``, and ending with ``end``. """ - mv = _cy.line(self._in_scalar(start), self._in_scalar(end)) + mv = _cy.grid_path_cells(self._in_scalar(start), self._in_scalar(end)) return self._out_ordered(mv) - def h3_is_res_class_III(self, h): + def is_res_class_III(self, h): """ Determine if cell has orientation "Class II" or "Class III". @@ -743,27 +676,24 @@ class _API_FUNCTIONS(object): """ return _cy.is_res_class_iii(self._in_scalar(h)) - def h3_is_res_class_iii(self, h): - """Alias for `h3_is_res_class_III`.""" - return self.h3_is_res_class_III(h) - - def get_pentagon_indexes(self, resolution): + def get_pentagons(self, res): """ Return all pentagons at a given resolution. Parameters ---------- - resolution : int + res : int + Resolution of the pentagons Returns ------- unordered collection of H3Cell """ - mv = _cy.get_pentagon_indexes(resolution) + mv = _cy.get_pentagons(res) return self._out_unordered(mv) - def get_res0_indexes(self): + def get_res0_cells(self): """ Return all cells at resolution 0. @@ -775,11 +705,11 @@ class _API_FUNCTIONS(object): ------- unordered collection of H3Cell """ - mv = _cy.get_res0_indexes() + mv = _cy.get_res0_cells() return self._out_unordered(mv) - def h3_to_center_child(self, h, res=None): + def cell_to_center_child(self, h, res=None): """ Get the center child of a cell at some finer resolution. @@ -795,12 +725,12 @@ class _API_FUNCTIONS(object): H3Cell """ h = self._in_scalar(h) - p = _cy.center_child(h, res) + p = _cy.cell_to_center_child(h, res) p = self._out_scalar(p) return p - def h3_get_faces(self, h): + def get_icosahedron_faces(self, h): """ Return icosahedron faces intersecting a given H3 cell. @@ -817,11 +747,11 @@ class _API_FUNCTIONS(object): Python ``set`` of ``int`` """ h = self._in_scalar(h) - faces = _cy.get_faces(h) + faces = _cy.get_icosahedron_faces(h) return faces - def experimental_h3_to_local_ij(self, origin, h): + def cell_to_local_ij(self, origin, h): """ Return local (i,j) coordinates of cell ``h`` in relation to ``origin`` cell @@ -855,11 +785,11 @@ class _API_FUNCTIONS(object): origin = self._in_scalar(origin) h = self._in_scalar(h) - i, j = _cy.experimental_h3_to_local_ij(origin, h) + i, j = _cy.cell_to_local_ij(origin, h) return i, j - def experimental_local_ij_to_h3(self, origin, i, j): + def local_ij_to_cell(self, origin, i, j): """ Return cell at local (i,j) position relative to the ``origin`` cell. @@ -890,7 +820,7 @@ class _API_FUNCTIONS(object): """ origin = self._in_scalar(origin) - h = _cy.experimental_local_ij_to_h3(origin, i, j) + h = _cy.local_ij_to_cell(origin, i, j) h = self._out_scalar(h) return h @@ -916,13 +846,13 @@ class _API_FUNCTIONS(object): This function breaks the cell into spherical triangles, and computes their spherical area. The function uses the spherical distance calculation given by - `point_dist`. + `great_circle_distance`. """ h = self._in_scalar(h) return _cy.cell_area(h, unit=unit) - def exact_edge_length(self, e, unit='km'): + def edge_length(self, e, unit='km'): """ Compute the spherical length of a specific H3 edge. @@ -941,26 +871,25 @@ class _API_FUNCTIONS(object): Notes ----- This function uses the spherical distance calculation given by - `point_dist`. + `great_circle_distance`. """ e = self._in_scalar(e) return _cy.edge_length(e, unit=unit) @staticmethod - def point_dist(point1, point2, unit='km'): + def great_circle_distance(latlng1, latlng2, unit='km'): """ Compute the spherical distance between two (lat, lng) points. + AKA: great circle distance or "haversine" distance. - todo: do we handle lat/lng points consistently in the api? what - about (lat1, lng1, lat2, lng2) as the input? How will this work - for vectorized versions? + todo: overload to allow two cell inputs? Parameters ---------- - point1 : tuple + latlng1 : tuple (lat, lng) tuple in degrees - point2 : tuple + latlng2 : tuple (lat, lng) tuple in degrees unit: str Unit for distance result ('km', 'm', or 'rads') @@ -968,13 +897,12 @@ class _API_FUNCTIONS(object): Returns ------- - Spherical (or "haversine") distance between the points + The spherical distance between the points in the given units """ - lat1, lng1 = point1 - lat2, lng2 = point2 - - return _cy.point_dist( + lat1, lng1 = latlng1 + lat2, lng2 = latlng2 + return _cy.great_circle_distance( lat1, lng1, lat2, lng2, - unit=unit + unit = unit ) diff --git a/src/h3/api/basic_int/_binding.py b/src/h3/api/basic_int/_binding.py index a232287..28002dd 100644 --- a/src/h3/api/basic_int/_binding.py +++ b/src/h3/api/basic_int/_binding.py @@ -21,10 +21,10 @@ def _id(x): return x -def _in_collection(hexes): - it = list(hexes) +def _in_collection(cells): + it = list(cells) - return _cy.from_iter(it) + return _cy.iter_to_mv(it) _binding = _API_FUNCTIONS( diff --git a/src/h3/api/basic_int/_public_api.py b/src/h3/api/basic_int/_public_api.py index 50b51fc..6f1b552 100644 --- a/src/h3/api/basic_int/_public_api.py +++ b/src/h3/api/basic_int/_public_api.py @@ -6,61 +6,56 @@ being able to understand the H3 API. This file exists to avoid dynamically modifying `globals` and support static tooling. """ -from ._binding import _binding +from ._binding import _binding as _b -cell_area = _binding.cell_area -compact = _binding.compact -edge_length = _binding.edge_length -exact_edge_length = _binding.exact_edge_length -experimental_h3_to_local_ij = _binding.experimental_h3_to_local_ij -experimental_local_ij_to_h3 = _binding.experimental_local_ij_to_h3 -geo_to_h3 = _binding.geo_to_h3 -get_destination_h3_index_from_unidirectional_edge = ( - _binding.get_destination_h3_index_from_unidirectional_edge -) -get_h3_indexes_from_unidirectional_edge = ( - _binding.get_h3_indexes_from_unidirectional_edge -) -get_h3_unidirectional_edge = _binding.get_h3_unidirectional_edge -get_h3_unidirectional_edge_boundary = _binding.get_h3_unidirectional_edge_boundary -get_h3_unidirectional_edges_from_hexagon = ( - _binding.get_h3_unidirectional_edges_from_hexagon -) -get_origin_h3_index_from_unidirectional_edge = ( - _binding.get_origin_h3_index_from_unidirectional_edge -) -get_pentagon_indexes = _binding.get_pentagon_indexes -get_res0_indexes = _binding.get_res0_indexes -h3_distance = _binding.h3_distance -h3_get_base_cell = _binding.h3_get_base_cell -h3_get_faces = _binding.h3_get_faces -h3_get_resolution = _binding.h3_get_resolution -h3_indexes_are_neighbors = _binding.h3_indexes_are_neighbors -h3_is_pentagon = _binding.h3_is_pentagon -h3_is_res_class_III = _binding.h3_is_res_class_III -h3_is_res_class_iii = _binding.h3_is_res_class_iii -h3_is_valid = _binding.h3_is_valid -h3_line = _binding.h3_line -h3_set_to_multi_polygon = _binding.h3_set_to_multi_polygon -h3_to_center_child = _binding.h3_to_center_child -h3_to_children = _binding.h3_to_children -h3_to_geo = _binding.h3_to_geo -h3_to_geo_boundary = _binding.h3_to_geo_boundary -h3_to_parent = _binding.h3_to_parent -h3_to_string = _binding.h3_to_string -h3_unidirectional_edge_is_valid = _binding.h3_unidirectional_edge_is_valid -hex_area = _binding.hex_area -hex_range = _binding.hex_range -hex_range_distances = _binding.hex_range_distances -hex_ranges = _binding.hex_ranges -hex_ring = _binding.hex_ring -k_ring = _binding.k_ring -k_ring_distances = _binding.k_ring_distances -num_hexagons = _binding.num_hexagons -point_dist = _binding.point_dist -polyfill = _binding.polyfill -polyfill_geojson = _binding.polyfill_geojson -polyfill_polygon = _binding.polyfill_polygon -string_to_h3 = _binding.string_to_h3 -uncompact = _binding.uncompact -versions = _binding.versions + +is_valid_cell = _b.is_valid_cell +is_pentagon = _b.is_pentagon +is_valid_directed_edge = _b.is_valid_directed_edge +is_res_class_III = _b.is_res_class_III + +int_to_str = _b.int_to_str +str_to_int = _b.str_to_int + +cell_area = _b.cell_area +edge_length = _b.edge_length +great_circle_distance = _b.great_circle_distance +average_hexagon_area = _b.average_hexagon_area +average_hexagon_edge_length = _b.average_hexagon_edge_length + +latlng_to_cell = _b.latlng_to_cell +cell_to_latlng = _b.cell_to_latlng +cell_to_boundary = _b.cell_to_boundary +cell_to_local_ij = _b.cell_to_local_ij +local_ij_to_cell = _b.local_ij_to_cell + +grid_ring = _b.grid_ring +grid_disk = _b.grid_disk +grid_distance = _b.grid_distance +grid_path_cells = _b.grid_path_cells + +get_num_cells = _b.get_num_cells +get_pentagons = _b.get_pentagons +get_res0_cells = _b.get_res0_cells +get_resolution = _b.get_resolution +get_base_cell_number = _b.get_base_cell_number +get_icosahedron_faces = _b.get_icosahedron_faces + +cell_to_parent = _b.cell_to_parent +cell_to_children = _b.cell_to_children +cell_to_center_child = _b.cell_to_center_child +compact_cells = _b.compact_cells +uncompact_cells = _b.uncompact_cells + +polygon_to_cells = _b.polygon_to_cells +cells_to_polygons = _b.cells_to_polygons + +are_neighbor_cells = _b.are_neighbor_cells +cells_to_directed_edge = _b.cells_to_directed_edge +directed_edge_to_cells = _b.directed_edge_to_cells +origin_to_directed_edges = _b.origin_to_directed_edges +get_directed_edge_origin = _b.get_directed_edge_origin +get_directed_edge_destination = _b.get_directed_edge_destination +directed_edge_to_boundary = _b.directed_edge_to_boundary + +versions = _b.versions diff --git a/src/h3/api/basic_str/_binding.py b/src/h3/api/basic_str/_binding.py index 765fdbb..4ebd5fb 100644 --- a/src/h3/api/basic_str/_binding.py +++ b/src/h3/api/basic_str/_binding.py @@ -18,25 +18,25 @@ from ... import _cy from .._api_template import _API_FUNCTIONS -def _in_collection(hexes): - it = [_cy.hex2int(h) for h in hexes] +def _in_collection(cells): + it = [_cy.str_to_int(h) for h in cells] - return _cy.from_iter(it) + return _cy.iter_to_mv(it) def _out_unordered(mv): # todo: should this be an (immutable) frozenset? - return set(_cy.int2hex(h) for h in mv) + return set(_cy.int_to_str(h) for h in mv) def _out_ordered(mv): # todo: should this be an (immutable) tuple? - return list(_cy.int2hex(h) for h in mv) + return list(_cy.int_to_str(h) for h in mv) _binding = _API_FUNCTIONS( - _in_scalar = _cy.hex2int, - _out_scalar = _cy.int2hex, + _in_scalar = _cy.str_to_int, + _out_scalar = _cy.int_to_str, _in_collection = _in_collection, _out_unordered = _out_unordered, _out_ordered = _out_ordered, diff --git a/src/h3/unstable/__init__.py b/src/h3/unstable/__init__.py deleted file mode 100644 index 5c1839c..0000000 --- a/src/h3/unstable/__init__.py +++ /dev/null @@ -1,9 +0,0 @@ -# flake8: noqa - -import warnings -warnings.warn( - 'Modules under `h3.unstable` are experimental, and may change at any time.' -) - -from . import v4 -from . import vect diff --git a/src/h3/unstable/v4.py b/src/h3/unstable/v4.py deleted file mode 100644 index 833cd6e..0000000 --- a/src/h3/unstable/v4.py +++ /dev/null @@ -1,125 +0,0 @@ -# flake8: noqa - -from ..api.basic_str import ( - # todo: implement is_valid_index - - compact as - compact_cells, - - edge_length as - get_hexagon_edge_length_avg, - - geo_to_h3 as - point_to_cell, - - get_destination_h3_index_from_unidirectional_edge as - get_directed_edge_destination, - - get_h3_indexes_from_unidirectional_edge as - directed_edge_to_cells, - - get_h3_unidirectional_edge as - cells_to_directed_edge, - - get_h3_unidirectional_edge_boundary as - directed_edge_to_boundary, - - get_h3_unidirectional_edges_from_hexagon as - origin_to_directed_edges, - - get_origin_h3_index_from_unidirectional_edge as - get_directed_edge_origin, - - get_pentagon_indexes as - get_pentagons, - - get_res0_indexes as - get_res0_cells, - - h3_distance as - grid_distance, - - h3_get_base_cell as - get_base_cell_number, - - h3_get_faces as - get_icosahedron_faces, - - h3_get_resolution as - get_resolution, - - h3_indexes_are_neighbors as - are_neighbor_cells, - - h3_is_pentagon as - is_pentagon, - - h3_is_res_class_III as - is_res_class_III, - - h3_is_valid as - is_valid_cell, - - h3_line as - grid_path_cells, - - h3_set_to_multi_polygon as - cells_to_multipolygon, - - h3_to_center_child as - cell_to_center_child, - - h3_to_children as - cell_to_children, - - h3_to_geo as - cell_to_point, - - h3_to_geo_boundary as - cell_to_boundary, - - h3_to_parent as - cell_to_parent, - - h3_to_string as - int_to_str, - - h3_unidirectional_edge_is_valid as - is_valid_directed_edge, - - hex_area as - get_hexagon_area_avg, - - # hex_range as _, - # hex_range_distances as _, # not sure we want this one; easy for user to implement - # hex_ranges as _, - - hex_ring as - grid_ring, - - k_ring as - grid_disk, - - k_ring_distances as - grid_disk_distances, - - num_hexagons as - get_num_cells, - - polyfill as - polygon_to_cells, - - polyfill_geojson as - geojson_to_cells, # still need to figure out the final polyfill interface - - #polyfill_polygon as _, - - string_to_h3 as - str_to_int, - - uncompact as - uncompact_cells, - - versions as - versions, -) diff --git a/src/h3/unstable/vect.py b/src/h3/unstable/vect.py deleted file mode 100644 index 122c07d..0000000 --- a/src/h3/unstable/vect.py +++ /dev/null @@ -1,105 +0,0 @@ -from .._cy import unstable_vect as _vect - -import numpy as np - - -def h3_to_parent(h, res=None): - """ - Get parent of arrays of cells. - - Parameters - ---------- - h : array of H3Cells - res: int or None, optional - The resolution for the parent - If `None`, then `res = resolution(h) - 1` - - Returns - ------- - array of H3Cells - """ - h = np.array(h, dtype=np.uint64) - out = np.zeros(len(h), dtype=np.uint64) - - if res is None: - res = h3_get_resolution(h) - 1 - else: - res = np.full(h.shape, res, dtype=np.intc) - - _vect.h3_to_parent_vect(h, res, out) - - return out - - -def h3_get_resolution(h): - """ - Return the resolution of an array of H3 cells. - - Parameters - ---------- - h : H3Cell - - Returns - ------- - array of int - """ - h = np.array(h, dtype=np.uint64) - out = np.zeros(len(h), dtype=np.intc) - - _vect.h3_get_resolution_vect(h, out) - - return out - - -def geo_to_h3(lats, lngs, res): - """ - Convert arrays describing lat/lng pairs to cells. - - Parameters - ---------- - lats, lngs : arrays of floats - - res: int - Resolution for output cells. - - Returns - ------- - array of H3Cells - """ - lats = np.array(lats, dtype=np.float64) - lngs = np.array(lngs, dtype=np.float64) - - assert len(lats) == len(lngs) - - out = np.zeros(len(lats), dtype='uint64') - - _vect.geo_to_h3_vect(lats, lngs, res, out) - - return out - - -def cell_haversine(a, b): - """ - Compute haversine distance between the centers of cells given in - arrays a and b. - - - Parameters - ---------- - a, b : arrays of H3Cell - - Returns - ------- - float - Haversine distance in kilometers - """ - a = np.array(a, dtype=np.uint64) - b = np.array(b, dtype=np.uint64) - - assert len(a) == len(b) - - out = np.zeros(len(a), dtype='double') - - _vect.haversine_vect(a, b, out) - - return out diff --git a/src/h3lib b/src/h3lib index ee292a9..46a581c 160000 --- a/src/h3lib +++ b/src/h3lib @@ -1 +1 @@ -Subproject commit ee292a96906767162f2f530b46fc2428b2555748 +Subproject commit 46a581c905b2747c861aa1683125276501f68a3b diff --git a/tests/cython_example.pyx b/tests/cython_example.pyx index e8d2859..a465bd6 100644 --- a/tests/cython_example.pyx +++ b/tests/cython_example.pyx @@ -1,11 +1,11 @@ from cython cimport boundscheck, wraparound from h3._cy.h3lib cimport H3int -from h3._cy.geo cimport geo_to_h3 +from h3._cy.geo cimport latlng_to_cell @boundscheck(False) @wraparound(False) -cpdef void geo_to_h3_vect( +cpdef void latlng_to_cell_vect( const double[:] lat, const double[:] lng, int res, @@ -15,4 +15,4 @@ cpdef void geo_to_h3_vect( cdef Py_ssize_t i for i in range(len(lat)): - out[i] = geo_to_h3(lat[i], lng[i], res) + out[i] = latlng_to_cell(lat[i], lng[i], res) diff --git a/tests/test_basic_int.py b/tests/test_basic_int.py index d5c47c0..99452fe 100644 --- a/tests/test_basic_int.py +++ b/tests/test_basic_int.py @@ -5,11 +5,11 @@ def test_int_output(): lat = 37.7752702151959 lng = -122.418307270836 - assert h3.geo_to_h3(lat, lng, 9) == 617700169958293503 - assert h3.geo_to_h3(lat, lng, 9) == 0x8928308280fffff + assert h3.latlng_to_cell(lat, lng, 9) == 617700169958293503 + assert h3.latlng_to_cell(lat, lng, 9) == 0x8928308280fffff -def test_k_ring(): +def test_grid_disk(): expected = { 617700169957507071, 617700169957769215, @@ -20,29 +20,29 @@ def test_k_ring(): 617700169965109247, } - out = h3.k_ring(617700169958293503, 1) + out = h3.grid_disk(617700169958293503, 1) assert out == expected -def test_compact(): +def test_compact_cells(): h = 617700169958293503 - hexes = h3.h3_to_children(h) + cells = h3.cell_to_children(h) - assert h3.compact(hexes) == {h} + assert h3.compact_cells(cells) == {h} -def test_get_faces(): +def test_get_icosahedron_faces(): h = 577832942814887935 expected = {2, 3, 7, 8, 12} - out = h3.h3_get_faces(h) + out = h3.get_icosahedron_faces(h) assert out == expected h = 579873636396040191 expected = {13} - out = h3.h3_get_faces(h) + out = h3.get_icosahedron_faces(h) assert out == expected h = 579768083279773695 expected = {16, 15} - out = h3.h3_get_faces(h) + out = h3.get_icosahedron_faces(h) assert out == expected diff --git a/tests/test_basic_str.py b/tests/test_basic_str.py index f765678..eaae35b 100644 --- a/tests/test_basic_str.py +++ b/tests/test_basic_str.py @@ -2,7 +2,8 @@ import h3.api.basic_str as h3 def test1(): - assert h3.geo_to_h3(37.7752702151959, -122.418307270836, 9) == '8928308280fffff' + lat, lng = 37.7752702151959, -122.418307270836 + assert h3.latlng_to_cell(lat, lng, 9) == '8928308280fffff' def test5(): @@ -16,5 +17,5 @@ def test5(): '89283082803ffff' } - out = h3.k_ring('8928308280fffff', 1) + out = h3.grid_disk('8928308280fffff', 1) assert out == expected diff --git a/tests/test_cells_and_edges.py b/tests/test_cells_and_edges.py index 173033a..4746569 100644 --- a/tests/test_cells_and_edges.py +++ b/tests/test_cells_and_edges.py @@ -2,11 +2,12 @@ import h3 import pytest from h3 import ( - H3ValueError, - H3CellError, - H3ResolutionError, - H3EdgeError, - H3DistanceError, + H3FailedError, + H3ResDomainError, + H3DomainError, + H3ResMismatchError, + H3CellInvalidError, + H3NotNeighborsError, ) @@ -21,14 +22,15 @@ def approx2(a, b): def test1(): - assert h3.geo_to_h3(37.7752702151959, -122.418307270836, 9) == '8928308280fffff' + lat, lng = 37.7752702151959, -122.418307270836 + assert h3.latlng_to_cell(lat, lng, 9) == '8928308280fffff' def test2(): h = '8928308280fffff' expected = (37.77670234943567, -122.41845932318311) - assert h3.h3_to_geo(h) == pytest.approx(expected) + assert h3.cell_to_latlng(h) == pytest.approx(expected) def test3(): @@ -41,7 +43,7 @@ def test3(): (37.775019673792606, -122.4195306280734), ) - out = h3.h3_to_geo_boundary('8928308280fffff') + out = h3.cell_to_boundary('8928308280fffff') assert approx2(out, expected) @@ -56,18 +58,18 @@ def test4(): (-122.41719971841658, 37.775197782893386) ) - out = h3.h3_to_geo_boundary('8928308280fffff', geo_json=True) + out = h3.cell_to_boundary('8928308280fffff', geo_json=True) assert approx2(out, expected) -def test_k_ring_distance(): - with pytest.raises(H3DistanceError): - h3.k_ring('8928308280fffff', -10) +def test_grid_disk_distance(): + with pytest.raises(H3DomainError): + h3.grid_disk('8928308280fffff', -10) -def test_hex_ring_distance(): - with pytest.raises(H3DistanceError): - h3.hex_ring('8928308280fffff', -10) +def test_grid_ring_distance(): + with pytest.raises(H3DomainError): + h3.grid_ring('8928308280fffff', -10) def test5(): @@ -81,13 +83,13 @@ def test5(): '89283082803ffff' } - out = h3.k_ring('8928308280fffff', 1) + out = h3.grid_disk('8928308280fffff', 1) assert out == expected def test6(): expected = {'8928308280fffff'} - out = h3.hex_ring('8928308280fffff', 0) + out = h3.grid_ring('8928308280fffff', 0) assert out == expected @@ -101,48 +103,67 @@ def test7(): '89283082877ffff' } - out = h3.hex_ring('8928308280fffff', 1) + out = h3.grid_ring('8928308280fffff', 1) assert out == expected def test8(): - assert h3.h3_is_valid('89283082803ffff') - assert not h3.h3_is_valid('abc') + assert h3.is_valid_cell('89283082803ffff') + assert not h3.is_valid_cell('abc') # looks like it might be valid, but it isn't! h_bad = '8a28308280fffff' - assert not h3.h3_is_valid(h_bad) + assert not h3.is_valid_cell(h_bad) # other methods should validate and raise exception if bad input - with pytest.raises(H3CellError): - h3.h3_get_resolution(h_bad) + with pytest.raises(H3CellInvalidError): + h3.get_resolution(h_bad) def test9(): - assert h3.h3_get_resolution('8928308280fffff') == 9 - assert h3.h3_get_resolution('8a28308280f7fff') == 10 + assert h3.get_resolution('8928308280fffff') == 9 + assert h3.get_resolution('8a28308280f7fff') == 10 def test_parent(): h = '8928308280fffff' - assert h3.h3_to_parent(h, 7) == '872830828ffffff' - assert h3.h3_to_parent(h, 8) == '8828308281fffff' - assert h3.h3_to_parent(h, 9) == h + assert h3.cell_to_parent(h, 7) == '872830828ffffff' + assert h3.cell_to_parent(h, 8) == '8828308281fffff' + assert h3.cell_to_parent(h, 9) == h - with pytest.raises(H3ResolutionError): - h3.h3_to_parent(h, 10) + with pytest.raises(H3ResMismatchError): + h3.cell_to_parent(h, 10) + + +def test_parent_err(): + # Test 1 + h = '8075fffffffffff' # latlng_to_cell(0,0,0) + + with pytest.raises(H3ResDomainError): + h3.cell_to_parent(h) + + # Test 2 + try: + h3.cell_to_parent(h) + except Exception as e: + msg = str(e) + + # todo: revist this weird formatting stuff + expected = 'Invalid parent resolution -1 for cell {}.' + expected = expected.format(hex(h3.str_to_int(h))) + + assert msg == expected def test_children(): h = '8928308280fffff' - # one above should raise an exception - with pytest.raises(H3ResolutionError): - h3.h3_to_children(h, 8) + with pytest.raises(H3ResDomainError): + h3.cell_to_children(h, 8) # same resolution is set of just cell itself - out = h3.h3_to_children(h, 9) + out = h3.cell_to_children(h, 9) assert out == {h} # one below should give children @@ -155,58 +176,62 @@ def test_children(): '8a28308280effff', '8a28308280f7fff' } - out = h3.h3_to_children(h, 10) + out = h3.cell_to_children(h, 10) assert out == expected # finest resolution cell should return error for children h = '8f04ccb2c45e225' - with pytest.raises(H3ResolutionError): - h3.h3_to_children(h) + with pytest.raises(H3ResDomainError): + h3.cell_to_children(h) def test_center_child(): h = '8928308280fffff' # one above should raise an exception - with pytest.raises(H3ResolutionError): - h3.h3_to_center_child(h, 8) + with pytest.raises(H3ResDomainError): + h3.cell_to_center_child(h, 8) # same resolution should be same cell - assert h3.h3_to_center_child(h, 9) == h + assert h3.cell_to_center_child(h, 9) == h # one below should give direct child expected = '8a28308280c7fff' - assert h3.h3_to_center_child(h, 10) == expected + assert h3.cell_to_center_child(h, 10) == expected # finest resolution hex should return error for child h = '8f04ccb2c45e225' - with pytest.raises(H3ResolutionError): - h3.h3_to_center_child(h) + with pytest.raises(H3ResDomainError): + h3.cell_to_center_child(h) def test_distance(): h = '8a28308280c7fff' - assert h3.h3_distance(h, h) == 0 + assert h3.grid_distance(h, h) == 0 - n = h3.hex_ring(h, 1).pop() - assert h3.h3_distance(h, n) == 1 + n = h3.grid_ring(h, 1).pop() + assert h3.grid_distance(h, n) == 1 - n = h3.hex_ring(h, 2).pop() - assert h3.h3_distance(h, n) == 2 + n = h3.grid_ring(h, 2).pop() + assert h3.grid_distance(h, n) == 2 def test_distance_error(): + """ Two valid cells, but they are too far apart compute the distance + + todo: make sure this raises a E_TOO_FAR error (when we add it in the future) + """ h1 = '8353b0fffffffff' h2 = '835804fffffffff' - with pytest.raises(H3ValueError): - h3.h3_distance(h1, h2) + with pytest.raises(H3FailedError): + h3.grid_distance(h1, h2) -def test_compact(): +def test_compact_cells(): # lat/lngs for State of Maine - maine = [ + maine = h3.Polygon([ (45.137451890638886, -67.13734351262877), (44.8097, -66.96466), (44.3252, -68.03252), @@ -227,12 +252,11 @@ def test_compact(): (47.066248887716995, -67.79035274928509), (45.702585354182816, -67.79141211614706), (45.137451890638886, -67.13734351262877) - ] + ]) res = 5 - - h_uncomp = h3.polyfill_polygon(maine, res) - h_comp = h3.compact(h_uncomp) + h_uncomp = h3.polygon_to_cells(maine, res=res) + h_comp = h3.compact_cells(h_uncomp) expected = {'852b114ffffffff', '852b189bfffffff', '852b1163fffffff', '842ba9bffffffff', '842bad3ffffffff', '852ba9cffffffff', '842badbffffffff', '852b1e8bfffffff', '852a346ffffffff', '842b1e3ffffffff', '852b116ffffffff', '842b185ffffffff', '852b1bdbfffffff', '852bad47fffffff', '852ba9c3fffffff', '852b106bfffffff', '852a30d3fffffff', '842b1edffffffff', '852b12a7fffffff', '852b1027fffffff', '842baddffffffff', '852a349bfffffff', '852b1227fffffff', '852a3473fffffff', '852b117bfffffff', '842ba99ffffffff', '852a341bfffffff', '852ba9d3fffffff', '852b1067fffffff', '852a3463fffffff', '852baca7fffffff', '852b116bfffffff', '852b1c6bfffffff', '852a3493fffffff', '852ba9dbfffffff', '852b180bfffffff', '842bad7ffffffff', '852b1063fffffff', '842ba93ffffffff', '852a3693fffffff', '852ba977fffffff', '852b1e9bfffffff', '852bad53fffffff', '852b100ffffffff', '852b102bfffffff', '852a3413fffffff', '852ba8b7fffffff', '852bad43fffffff', '852b1c6ffffffff', '852a340bfffffff', '852b103bfffffff', '852b1813fffffff', '852b12affffffff', '842a34dffffffff', '852b1873fffffff', '852b106ffffffff', '852b115bfffffff', '852baca3fffffff', '852b114bfffffff', '852b1143fffffff', '852a348bfffffff', '852a30d7fffffff', '852b181bfffffff', '842a345ffffffff', '852b1e8ffffffff', '852b1883fffffff', '852b1147fffffff', '852a3483fffffff', '852b12a3fffffff', '852a346bfffffff', '852ba9d7fffffff', '842b18dffffffff', '852b188bfffffff', '852a36a7fffffff', '852bacb3fffffff', '852b187bfffffff', '852bacb7fffffff', '842b1ebffffffff', '842b1e5ffffffff', '852ba8a7fffffff', '842bad9ffffffff', '852a36b7fffffff', '852a347bfffffff', '832b13fffffffff', '852ba9c7fffffff', '832b1afffffffff', '842ba91ffffffff', '852bad57fffffff', '852ba8affffffff', '852b1803fffffff', '842b1e7ffffffff', '852bad4ffffffff', '852b102ffffffff', '852b1077fffffff', '852b1237fffffff', '852b1153fffffff', '852a3697fffffff', '852a36b3fffffff', '842bad1ffffffff', '842b1e1ffffffff', '852b186bfffffff', '852b1023fffffff'} # noqa @@ -241,16 +265,16 @@ def test_compact(): return h_uncomp, h_comp, res -def test_uncompact(): +def test_uncompact_cells(): - h_uncomp, h_comp, res = test_compact() + h_uncomp, h_comp, res = test_compact_cells() - out = h3.uncompact(h_comp, res) + out = h3.uncompact_cells(h_comp, res) assert out == h_uncomp -def test_num_hexagons(): +def test_get_num_cells(): expected = { 0: 122, 1: 842, @@ -260,31 +284,31 @@ def test_num_hexagons(): } out = { - k: h3.num_hexagons(k) + k: h3.get_num_cells(k) for k in expected } assert expected == out -def test_hex_area(): +def test_average_hexagon_area(): expected_in_km2 = { - 0: 4250546.848, - 1: 607220.9782, - 2: 86745.85403, - 9: 0.1053325, - 15: 9e-07, + 0: 4357449.416078381, + 1: 609788.441794133, + 2: 86801.780398997, + 9: 0.105332513, + 15: 8.95311e-07, } out = { - k: h3.hex_area(k, unit='km^2') + k: h3.average_hexagon_area(k, unit='km^2') for k in expected_in_km2 } assert out == pytest.approx(expected_in_km2) -def test_hex_edge_length(): +def test_average_hexagon_edge_length(): expected_in_km = { 0: 1107.712591000, 1: 418.676005500, @@ -294,7 +318,7 @@ def test_hex_edge_length(): } out = { - res: h3.edge_length(res, unit='km') + res: h3.average_hexagon_edge_length(res, unit='km') for res in expected_in_km } @@ -305,29 +329,29 @@ def test_edge(): h1 = '8928308280fffff' h2 = '89283082873ffff' - assert not h3.h3_indexes_are_neighbors(h1, h1) - assert h3.h3_indexes_are_neighbors(h1, h2) + assert not h3.are_neighbor_cells(h1, h1) + assert h3.are_neighbor_cells(h1, h2) - e = h3.get_h3_unidirectional_edge(h1, h2) + e = h3.cells_to_directed_edge(h1, h2) assert e == '12928308280fffff' - assert h3.h3_unidirectional_edge_is_valid(e) - assert not h3.h3_is_valid(e) + assert h3.is_valid_directed_edge(e) + assert not h3.is_valid_cell(e) - assert h3.get_origin_h3_index_from_unidirectional_edge(e) == h1 - assert h3.get_destination_h3_index_from_unidirectional_edge(e) == h2 + assert h3.get_directed_edge_origin(e) == h1 + assert h3.get_directed_edge_destination(e) == h2 - assert h3.get_h3_indexes_from_unidirectional_edge(e) == (h1, h2) + assert h3.directed_edge_to_cells(e) == (h1, h2) -def test_edges_from_cell(): +def test_origin_to_directed_edges(): h = '8928308280fffff' - edges = h3.get_h3_unidirectional_edges_from_hexagon(h) + edges = h3.origin_to_directed_edges(h) destinations = { - h3.get_destination_h3_index_from_unidirectional_edge(e) + h3.get_directed_edge_destination(e) for e in edges } - neighbors = h3.hex_ring(h, 1) + neighbors = h3.grid_ring(h, 1) assert neighbors == destinations @@ -335,14 +359,14 @@ def test_edges_from_cell(): def test_edge_boundary(): h1 = '8928308280fffff' h2 = '89283082873ffff' - e = h3.get_h3_unidirectional_edge(h1, h2) + e = h3.cells_to_directed_edge(h1, h2) expected = ( (37.77688044840226, -122.41612835779266), (37.778385004930925, -122.41738797617619) ) - out = h3.get_h3_unidirectional_edge_boundary(e) + out = h3.directed_edge_to_boundary(e) assert out[0] == pytest.approx(expected[0]) assert out[1] == pytest.approx(expected[1]) @@ -351,87 +375,84 @@ def test_edge_boundary(): def test_validation(): h = '8a28308280fffff' # invalid cell - with pytest.raises(H3CellError): - h3.h3_get_base_cell(h) + with pytest.raises(H3CellInvalidError): + h3.get_base_cell_number(h) - with pytest.raises(H3CellError): - h3.h3_get_resolution(h) + with pytest.raises(H3CellInvalidError): + h3.get_resolution(h) - with pytest.raises(H3CellError): - h3.h3_to_parent(h, 9) + with pytest.raises(H3CellInvalidError): + h3.cell_to_parent(h, 9) - with pytest.raises(H3CellError): - h3.h3_distance(h, h) + with pytest.raises(H3CellInvalidError): + h3.grid_distance(h, h) - with pytest.raises(H3CellError): - h3.k_ring(h, 1) + with pytest.raises(H3CellInvalidError): + h3.grid_disk(h, 1) - with pytest.raises(H3CellError): - h3.hex_ring(h, 1) + with pytest.raises(H3CellInvalidError): + h3.grid_ring(h, 1) - with pytest.raises(H3CellError): - h3.h3_to_children(h, 11) + with pytest.raises(H3CellInvalidError): + h3.cell_to_children(h, 11) - with pytest.raises(H3CellError): - h3.compact({h}) + with pytest.raises(H3CellInvalidError): + h3.compact_cells({h}) - with pytest.raises(H3CellError): - h3.uncompact({h}, 10) + with pytest.raises(H3CellInvalidError): + h3.uncompact_cells({h}, 10) def test_validation2(): h = '8928308280fffff' - with pytest.raises(H3ResolutionError): - h3.h3_to_children(h, 17) + with pytest.raises(H3ResDomainError): + h3.cell_to_children(h, 17) - assert not h3.h3_indexes_are_neighbors(h, h) + assert not h3.are_neighbor_cells(h, h) def test_validation_geo(): h = '8a28308280fffff' # invalid cell - with pytest.raises(H3CellError): - h3.h3_to_geo(h) + with pytest.raises(H3CellInvalidError): + h3.cell_to_latlng(h) - with pytest.raises(H3ResolutionError): - h3.geo_to_h3(0, 0, 17) + with pytest.raises(H3ResDomainError): + h3.latlng_to_cell(0, 0, 17) - with pytest.raises(H3CellError): - h3.h3_to_geo_boundary(h) + with pytest.raises(H3CellInvalidError): + h3.cell_to_boundary(h) - with pytest.raises(H3CellError): - h3.h3_indexes_are_neighbors(h, h) + # note: this won't raise an exception on bad input, but it does + # *correctly* say that two invalid indexes are not neighbors + assert not h3.are_neighbor_cells(h, h) def test_edges(): h = '8928308280fffff' - with pytest.raises(H3ValueError): - h3.get_h3_unidirectional_edge(h, h) + with pytest.raises(H3NotNeighborsError): + h3.cells_to_directed_edge(h, h) - h2 = h3.hex_ring(h, 2).pop() - with pytest.raises(H3ValueError): - h3.get_h3_unidirectional_edge(h, h2) + h2 = h3.grid_ring(h, 2).pop() + with pytest.raises(H3NotNeighborsError): + h3.cells_to_directed_edge(h, h2) e_bad = '14928308280ffff1' - assert not h3.h3_unidirectional_edge_is_valid(e_bad) + assert not h3.is_valid_directed_edge(e_bad) - with pytest.raises(H3EdgeError): - h3.get_origin_h3_index_from_unidirectional_edge(e_bad) - - with pytest.raises(H3EdgeError): - h3.get_destination_h3_index_from_unidirectional_edge(e_bad) - - with pytest.raises(H3EdgeError): - h3.get_h3_indexes_from_unidirectional_edge(e_bad) + # note: won't raise an error on bad input + h3.get_directed_edge_origin(e_bad) + h3.get_directed_edge_destination(e_bad) + h3.directed_edge_to_cells(e_bad) def test_line(): h1 = '8928308280fffff' h2 = '8928308287bffff' - out = h3.h3_line(h1, h2) + out = h3.grid_path_cells(h1, h2) expected = [ '8928308280fffff', @@ -458,24 +479,24 @@ def test_versions(): def test_str_int_convert(): s = '8928308280fffff' - i = h3.string_to_h3(s) + i = h3.str_to_int(s) - assert h3.h3_to_string(i) == s + assert h3.int_to_str(i) == s -def test_hex2int_fail(): +def test_str_to_int_fail(): h_invalid = {} - assert not h3.h3_is_valid(h_invalid) + assert not h3.is_valid_cell(h_invalid) def test_edge_is_valid_fail(): e_invalid = {} - assert not h3.h3_unidirectional_edge_is_valid(e_invalid) + assert not h3.is_valid_directed_edge(e_invalid) def test_get_pentagons(): - out = h3.get_pentagon_indexes(0) + out = h3.get_pentagons(0) expected = { '8009fffffffffff', @@ -494,7 +515,7 @@ def test_get_pentagons(): assert out == expected - out = h3.get_pentagon_indexes(5) + out = h3.get_pentagons(5) expected = { '85080003fffffff', @@ -514,34 +535,34 @@ def test_get_pentagons(): assert out == expected for i in range(16): - assert len(h3.get_pentagon_indexes(i)) == 12 + assert len(h3.get_pentagons(i)) == 12 def test_uncompact_cell_input(): - # `uncompact` takes in a collection of cells, not a single cell. + # `uncompact_cells` takes in a collection of cells, not a single cell. # Since a python string is seen as a Iterable collection, # inputting a single cell string can raise weird errors. # Ensure we get a reasonably helpful answer - with pytest.raises(H3CellError): - h3.uncompact('8001fffffffffff', 1) + with pytest.raises(H3CellInvalidError): + h3.uncompact_cells('8001fffffffffff', 1) -def test_get_res0_indexes(): - out = h3.get_res0_indexes() +def test_get_res0_cells(): + out = h3.get_res0_cells() assert len(out) == 122 # subset - pentagons = h3.get_pentagon_indexes(0) + pentagons = h3.get_pentagons(0) assert pentagons < out # all valid - assert all(map(h3.h3_is_valid, out)) + assert all(map(h3.is_valid_cell, out)) # resolution assert all(map( - lambda h: h3.h3_get_resolution(h) == 0, + lambda h: h3.get_resolution(h) == 0, out )) @@ -554,60 +575,55 @@ def test_get_res0_indexes(): assert sub < out -def test_get_faces_invalid(): - h = '8a28308280fffff' # invalid cell - - with pytest.raises(H3CellError): - h3.h3_get_faces(h) - - -def test_get_faces(): +def test_get_icosahedron_faces(): h = '804dfffffffffff' expected = {2, 3, 7, 8, 12} - out = h3.h3_get_faces(h) + out = h3.get_icosahedron_faces(h) assert out == expected h = '80c1fffffffffff' expected = {13} - out = h3.h3_get_faces(h) + out = h3.get_icosahedron_faces(h) assert out == expected h = '80bbfffffffffff' expected = {16, 15} - out = h3.h3_get_faces(h) + out = h3.get_icosahedron_faces(h) assert out == expected def test_to_local_ij_error(): - h = h3.geo_to_h3(0, 0, 0) + h = h3.latlng_to_cell(0, 0, 0) # error if we cross a face - nb = h3.hex_ring(h, k=2) - with pytest.raises(H3ValueError): - [h3.experimental_h3_to_local_ij(h, p) for p in nb] + nb = h3.grid_ring(h, k=2) + + # todo: should this be the E_TOO_FAR guy? + with pytest.raises(H3FailedError): + [h3.cell_to_local_ij(h, p) for p in nb] # should be fine if we do not cross a face - nb = h3.hex_ring(h, k=1) - out = {h3.experimental_h3_to_local_ij(h, p) for p in nb} + nb = h3.grid_ring(h, k=1) + out = {h3.cell_to_local_ij(h, p) for p in nb} expected = {(-1, 0), (0, -1), (0, 1), (1, 0), (1, 1)} assert out == expected def test_from_local_ij_error(): - h = h3.geo_to_h3(0, 0, 0) + h = h3.latlng_to_cell(0, 0, 0) baddies = [(1, -1), (-1, 1), (-1, -1)] for i, j in baddies: - with pytest.raises(H3ValueError): - h3.experimental_local_ij_to_h3(h, i, j) + with pytest.raises(H3FailedError): + h3.local_ij_to_cell(h, i, j) # inverting output should give good data - nb = h3.hex_ring(h, k=1) - goodies = {h3.experimental_h3_to_local_ij(h, p) for p in nb} + nb = h3.grid_ring(h, k=1) + goodies = {h3.cell_to_local_ij(h, p) for p in nb} out = { - h3.experimental_local_ij_to_h3(h, i, j) + h3.local_ij_to_cell(h, i, j) for i, j in goodies } @@ -615,7 +631,7 @@ def test_from_local_ij_error(): def test_to_local_ij_self(): - h = h3.geo_to_h3(0, 0, 9) - out = h3.experimental_h3_to_local_ij(h, h) + h = h3.latlng_to_cell(0, 0, 9) + out = h3.cell_to_local_ij(h, h) assert out == (-858, -2766) diff --git a/tests/test_collection_inputs.py b/tests/test_collection_inputs.py index aa09c4f..92a8ba5 100644 --- a/tests/test_collection_inputs.py +++ b/tests/test_collection_inputs.py @@ -22,15 +22,15 @@ def test_set(): h = 614553222213795839 - assert basic_int.compact(ints) == {h} + assert basic_int.compact_cells(ints) == {h} with pytest.raises(TypeError): # numpy can't convert from a set - numpy_int.compact(ints) + numpy_int.compact_cells(ints) with pytest.raises(TypeError): # set isn't a memoryview - memview_int.compact(ints) + memview_int.compact_cells(ints) def test_list(): @@ -46,19 +46,19 @@ def test_list(): h = 614553222213795839 - assert basic_int.compact(ints) == {h} + assert basic_int.compact_cells(ints) == {h} # numpy can convert from a list OK # (numpy knows to convert it to uint64) - assert numpy_int.compact(ints) == np.array([h], dtype='uint64') + assert numpy_int.compact_cells(ints) == np.array([h], dtype='uint64') # little weird that numpy comparisons don't consider dtype - assert numpy_int.compact(ints) == np.array([h]) - assert not numpy_int.compact(ints).dtype == np.array([h]).dtype + assert numpy_int.compact_cells(ints) == np.array([h]) + assert not numpy_int.compact_cells(ints).dtype == np.array([h]).dtype with pytest.raises(TypeError): # list isn't a memoryview - memview_int.compact(ints) + memview_int.compact_cells(ints) def test_np_array(): @@ -74,12 +74,12 @@ def test_np_array(): h = 614553222213795839 - assert basic_int.compact(ints) == {h} + assert basic_int.compact_cells(ints) == {h} - assert numpy_int.compact(ints) == np.array([h], dtype='uint64') - assert numpy_int.compact(ints).dtype == np.dtype('uint64') + assert numpy_int.compact_cells(ints) == np.array([h], dtype='uint64') + assert numpy_int.compact_cells(ints).dtype == np.dtype('uint64') - out = memview_int.compact(ints) + out = memview_int.compact_cells(ints) assert len(out) == 1 assert out[0] == h @@ -99,15 +99,15 @@ def test_list_to_array(): h = 614553222213795839 - assert basic_int.compact(ints) == {h} - assert numpy_int.compact(ints) == np.array([h], dtype='uint64') + assert basic_int.compact_cells(ints) == {h} + assert numpy_int.compact_cells(ints) == np.array([h], dtype='uint64') with pytest.raises(ValueError): # Without the explicit dtype given above, the array # assumes it has *signed* integers # The `memview_int` interface requires a dtype match # with uint64. - memview_int.compact(ints) + memview_int.compact_cells(ints) def test_iterator(): @@ -128,14 +128,14 @@ def test_iterator(): h = 614553222213795839 ints = foo() - assert basic_int.compact(ints) == {h} + assert basic_int.compact_cells(ints) == {h} ints = foo() with pytest.raises(TypeError): # numpy can't create an array from an iterator - numpy_int.compact(ints) + numpy_int.compact_cells(ints) ints = foo() with pytest.raises(TypeError): # requires a bytes-like input - memview_int.compact(ints) + memview_int.compact_cells(ints) diff --git a/tests/test_cython.py b/tests/test_cython.py index 30566b1..89aa064 100644 --- a/tests/test_cython.py +++ b/tests/test_cython.py @@ -3,15 +3,15 @@ import numpy as np # Avoid checking for import-error here because cython_example may not have # been compiled yet. try: - from .cython_example import geo_to_h3_vect # pylint: disable=import-error + from .cython_example import latlng_to_cell_vect # pylint: disable=import-error except ImportError: - geo_to_h3_vect = None + latlng_to_cell_vect = None np.random.seed(0) def test_cython_api(): - if geo_to_h3_vect is None: + if latlng_to_cell_vect is None: print("Not running Cython test because cython example was not compiled") return @@ -23,6 +23,6 @@ def test_cython_api(): lats = np.array(lats, dtype=np.float64) lngs = np.array(lngs, dtype=np.float64) out = np.zeros(len(lats), dtype="uint64") - geo_to_h3_vect(lats, lngs, res, out) + latlng_to_cell_vect(lats, lngs, res, out) assert out[0] == 617284541015654399 diff --git a/tests/test_error_codes.py b/tests/test_error_codes.py new file mode 100644 index 0000000..d8229b3 --- /dev/null +++ b/tests/test_error_codes.py @@ -0,0 +1,67 @@ +import pytest + +import h3 + +# todo: maybe check the `check_for_error` function behavior directly? + + +h3_exceptions = { + # h3.UnknownH3ErrorCode + h3.H3BaseException: None, + + h3.H3GridNavigationError: None, + h3.H3MemoryError: None, + h3.H3ValueError: None, + + h3.H3FailedError: 1, + h3.H3DomainError: 2, + h3.H3LatLngDomainError: 3, + h3.H3ResDomainError: 4, + h3.H3CellInvalidError: 5, + h3.H3DirEdgeInvalidError: 6, + h3.H3UndirEdgeInvalidError: 7, + h3.H3VertexInvalidError: 8, + h3.H3PentagonError: 9, + h3.H3DuplicateInputError: 10, + h3.H3NotNeighborsError: 11, + h3.H3ResMismatchError: 12, + h3.H3MemoryAllocError: 13, + h3.H3MemoryBoundsError: 14, + h3.H3OptionInvalidError: 15, +} + + +def test_error_codes_match(): + """ + Should match the error codes given in `h3api.h.in` in the core C lib. + """ + + for err, code in h3_exceptions.items(): + assert err.h3_error_code == code + + +def test_unknown(): + weird_code = 1234 + + with pytest.raises(h3.UnknownH3ErrorCode) as excinfo: + raise h3.UnknownH3ErrorCode(weird_code) + err = excinfo.value + + assert isinstance(err, h3.UnknownH3ErrorCode) + assert err.args == (weird_code,) + + +def test_atributes(): + # errors always have an `h3_error_code` attribute + for err in h3_exceptions: + x = err.h3_error_code + assert (x is None) or (x > 0) + + # UnknownH3ErrorCode is a bit of a special case + weird_code = 1234 + with pytest.raises(h3.UnknownH3ErrorCode) as excinfo: + raise h3.UnknownH3ErrorCode(weird_code) + err = excinfo.value + + assert err.h3_error_code is None + assert err.args == (weird_code,) diff --git a/tests/test_h3.py b/tests/test_h3.py index 09a1e7d..5900db9 100644 --- a/tests/test_h3.py +++ b/tests/test_h3.py @@ -4,61 +4,47 @@ from pytest import approx import h3 -def test_nested_import(): - """ Test that we can import `h3.h3` - For backwards-compatibility - """ - from h3 import h3 - assert h3.geo_to_h3(37.3615593, -122.0553238, 5) == '85283473fffffff' - - -def shift_circular_list(start_element, elements_list): - # We shift the circular list so that it starts from start_element, - start_index = elements_list.index(start_element) - return elements_list[start_index:] + elements_list[:start_index] - - -def test_h3_is_valid(): - assert h3.h3_is_valid('85283473fffffff') - assert h3.h3_is_valid('850dab63fffffff') - assert not h3.h3_is_valid('lolwut') +def test_is_valid_cell(): + assert h3.is_valid_cell('85283473fffffff') + assert h3.is_valid_cell('850dab63fffffff') + assert not h3.is_valid_cell('lolwut') # H3 0.x Addresses are not considered valid - assert not h3.h3_is_valid('5004295803a88') + assert not h3.is_valid_cell('5004295803a88') for res in range(16): - assert h3.h3_is_valid(h3.geo_to_h3(37, -122, res)) + assert h3.is_valid_cell(h3.latlng_to_cell(37, -122, res)) -def test_geo_to_h3(): - assert h3.geo_to_h3(37.3615593, -122.0553238, 5) == '85283473fffffff' +def test_latlng_to_cell(): + assert h3.latlng_to_cell(37.3615593, -122.0553238, 5) == '85283473fffffff' -def test_h3_get_resolution(): +def test_get_resolution(): for res in range(16): - h = h3.geo_to_h3(37.3615593, -122.0553238, res) - assert h3.h3_get_resolution(h) == res + h = h3.latlng_to_cell(37.3615593, -122.0553238, res) + assert h3.get_resolution(h) == res -def test_silly_geo_to_h3(): +def test_silly_latlng_to_cell(): lat, lng = 37.3615593, -122.0553238 expected0 = '85283473fffffff' - out0 = h3.geo_to_h3(lat, lng, 5) + out0 = h3.latlng_to_cell(lat, lng, 5) assert out0 == expected0 - out1 = h3.geo_to_h3(lat + 180.0, lng + 360.0, 5) + out1 = h3.latlng_to_cell(lat + 180.0, lng + 360.0, 5) expected1 = '85ca2d53fffffff' assert out1 == expected1 -def test_h3_to_geo(): - latlng = h3.h3_to_geo('85283473fffffff') +def test_cell_to_latlng(): + latlng = h3.cell_to_latlng('85283473fffffff') assert latlng == approx((37.34579337536848, -121.97637597255124)) -def test_h3_to_geo_boundary(): - out = h3.h3_to_geo_boundary('85283473fffffff') +def test_cell_to_boundary(): + out = h3.cell_to_boundary('85283473fffffff') expected = [ [37.271355866731895, -121.91508032705622], @@ -75,8 +61,8 @@ def test_h3_to_geo_boundary(): assert o == approx(e) -def test_h3_to_geo_boundary_geo_json(): - out = h3.h3_to_geo_boundary('85283473fffffff', True) +def test_cell_to_boundary_geo_json(): + out = h3.cell_to_boundary('85283473fffffff', True) expected = [ [-121.91508032705622, 37.271355866731895], @@ -94,9 +80,9 @@ def test_h3_to_geo_boundary_geo_json(): assert o == approx(e) -def test_k_ring(): +def test_grid_disk(): h = '8928308280fffff' - out = h3.k_ring(h, 1) + out = h3.grid_disk(h, 1) assert len(out) == 1 + 6 @@ -113,9 +99,9 @@ def test_k_ring(): assert out == expected -def test_k_ring2(): +def test_grid_disk2(): h = '8928308280fffff' - out = h3.k_ring(h, 2) + out = h3.grid_disk(h, 2) assert len(out) == 1 + 6 + 12 @@ -144,9 +130,9 @@ def test_k_ring2(): assert out == expected -def test_k_ring_pentagon(): +def test_grid_disk_pentagon(): h = '821c07fffffffff' # a pentagon cell - out = h3.k_ring(h, 1) + out = h3.grid_disk(h, 1) assert len(out) == 1 + 5 @@ -162,402 +148,258 @@ def test_k_ring_pentagon(): assert out == expected -def test_k_ring_distances(): - h = '8928308280fffff' - out = h3.k_ring_distances(h, 1) +sf_7x7 = [ + (37.813318999983238, -122.4089866999972145), + (37.7866302000007224, -122.3805436999997056), + (37.7198061999978478, -122.3544736999993603), + (37.7076131999975672, -122.5123436999983966), + (37.7835871999971715, -122.5247187000021967), + (37.8151571999998453, -122.4798767000009008), +] - assert [len(x) for x in out] == [1, 6] +sf_hole1 = [ + (37.7869802, -122.4471197), + (37.7664102, -122.4590777), + (37.7710682, -122.4137097), +] - expected = [ - {h}, - { - '8928308280bffff', - '89283082807ffff', - '89283082877ffff', - '89283082803ffff', - '89283082873ffff', - '8928308283bffff', - } - ] - - assert out == expected - - out = h3.k_ring_distances('870800003ffffff', 2) - - assert [len(x) for x in out] == [1, 6, 11] +sf_hole2 = [ + (37.747976, -122.490025), + (37.731550, -122.503758), + (37.725440, -122.452603), +] def test_polyfill(): - geo = { - 'type': 'Polygon', - 'coordinates': [ - [ - [37.813318999983238, -122.4089866999972145], - [37.7866302000007224, -122.3805436999997056], - [37.7198061999978478, -122.3544736999993603], - [37.7076131999975672, -122.5123436999983966], - [37.7835871999971715, -122.5247187000021967], - [37.8151571999998453, -122.4798767000009008] - ] - ] - } + poly = h3.Polygon(sf_7x7) + out = h3.polygon_to_cells(poly, res=9) - out = h3.polyfill(geo, 9) - assert len(out) > 1000 + assert len(out) == 1253 + assert '89283080527ffff' in out + assert '89283095edbffff' in out -def test_polyfill_bogus_geo_json(): - with pytest.raises(ValueError): - bad_geo = {'type': 'whatwhat'} - h3.polyfill(bad_geo, 9) +# def test_polyfill_bogus_geo_json(): +# with pytest.raises(ValueError): +# bad_geo = {'type': 'whatwhat'} +# h3.polyfill(bad_geo, 9) def test_polyfill_with_hole(): - geo = { - 'type': 'Polygon', - 'coordinates': [ - [ - [37.813318999983238, -122.4089866999972145], - [37.7866302000007224, -122.3805436999997056], - [37.7198061999978478, -122.3544736999993603], - [37.7076131999975672, -122.5123436999983966], - [37.7835871999971715, -122.5247187000021967], - [37.8151571999998453, -122.4798767000009008], - ], - [ - [37.7869802, -122.4471197], - [37.7664102, -122.4590777], - [37.7710682, -122.4137097], - ] - ] - } + poly = h3.Polygon(sf_7x7, sf_hole1) - out = h3.polyfill(geo, 9) - assert len(out) > 1000 + out = h3.polygon_to_cells(poly, res=9) + assert len(out) == 1214 + + foo = lambda x: h3.polygon_to_cells(h3.Polygon(x), 9) + # todo: foo = lambda x: h3.Polygon(x).to_cells(9) + assert out == foo(sf_7x7) - foo(sf_hole1) def test_polyfill_with_two_holes(): - geo = { - 'type': 'Polygon', - 'coordinates': [ - [ - [37.813318999983238, -122.4089866999972145], - [37.7866302000007224, -122.3805436999997056], - [37.7198061999978478, -122.3544736999993603], - [37.7076131999975672, -122.5123436999983966], - [37.7835871999971715, -122.5247187000021967], - [37.8151571999998453, -122.4798767000009008], - ], - [ - [37.7869802, -122.4471197], - [37.7664102, -122.4590777], - [37.7710682, -122.4137097], - ], - [ - [37.747976, -122.490025], - [37.731550, -122.503758], - [37.725440, -122.452603], - ] - ] - } - out = h3.polyfill(geo, 9) - assert len(out) > 1000 + poly = h3.Polygon(sf_7x7, sf_hole1, sf_hole2) + out = h3.polygon_to_cells(poly, 9) + assert len(out) == 1172 + foo = lambda x: h3.polygon_to_cells(h3.Polygon(x), 9) + assert out == foo(sf_7x7) - (foo(sf_hole1) | foo(sf_hole2)) -def test_polyfill_geo_json_compliant(): - geo = { - 'type': 'Polygon', - 'coordinates': [ - [ - [-122.4089866999972145, 37.813318999983238], - [-122.3805436999997056, 37.7866302000007224], - [-122.3544736999993603, 37.7198061999978478], - [-122.5123436999983966, 37.7076131999975672], - [-122.5247187000021967, 37.7835871999971715], - [-122.4798767000009008, 37.8151571999998453], - ] - ] - } +# def test_polyfill_geo_json_compliant(): +# geo = { +# 'type': 'Polygon', +# 'coordinates': [ +# [ +# [-122.4089866999972145, 37.813318999983238], +# [-122.3805436999997056, 37.7866302000007224], +# [-122.3544736999993603, 37.7198061999978478], +# [-122.5123436999983966, 37.7076131999975672], +# [-122.5247187000021967, 37.7835871999971715], +# [-122.4798767000009008, 37.8151571999998453], +# ] +# ] +# } - out = h3.polyfill(geo, 9, True) - assert len(out) > 1000 +# out = h3.polyfill(geo, 9, True) +# assert len(out) > 1000 def test_polyfill_down_under(): - geo = { - 'type': 'Polygon', - 'coordinates': [ - [ - [151.1979259, -33.8555555], - [151.2074556, -33.8519779], - [151.224743, -33.8579597], - [151.2254986, -33.8582212], - [151.235313348, -33.8564183032], - [151.234799568, -33.8594049408], - [151.233485084, -33.8641069037], - [151.233181742, -33.8715791334], - [151.223980353, -33.8876967719], - [151.219388501, -33.8873877027], - [151.2189209, -33.8869995], - [151.2181177, -33.886283399999996], - [151.2157995, -33.8851287], - [151.2156925, -33.8852471], - [151.2141233, -33.8851287], - [151.2116267, -33.8847438], - [151.2083456, -33.8834707], - [151.2080246, -33.8827601], - [151.2059204, -33.8816053], - [151.2043868, -33.8827601], - [151.2028176, -33.8838556], - [151.2022826, -33.8839148], - [151.2011057, -33.8842405], - [151.1986114, -33.8842819], - [151.1986091, -33.8842405], - [151.1948287, -33.8773416], - [151.1923322, -33.8740845], - [151.1850566, -33.8697019], - [151.1902636, -33.8625354], - [151.1986805, -33.8612915], - [151.1979259, -33.8555555], - ] - ] - } + sydney = [ + (-33.8555555, 151.1979259), + (-33.8519779, 151.2074556), + (-33.8579597, 151.224743), + (-33.8582212, 151.2254986), + (-33.8564183032, 151.235313348), + (-33.8594049408, 151.234799568), + (-33.8641069037, 151.233485084), + (-33.8715791334, 151.233181742), + (-33.8876967719, 151.223980353), + (-33.8873877027, 151.219388501), + (-33.8869995, 151.2189209), + (-33.886283399999996, 151.2181177), + (-33.8851287, 151.2157995), + (-33.8852471, 151.2156925), + (-33.8851287, 151.2141233), + (-33.8847438, 151.2116267), + (-33.8834707, 151.2083456), + (-33.8827601, 151.2080246), + (-33.8816053, 151.2059204), + (-33.8827601, 151.2043868), + (-33.8838556, 151.2028176), + (-33.8839148, 151.2022826), + (-33.8842405, 151.2011057), + (-33.8842819, 151.1986114), + (-33.8842405, 151.1986091), + (-33.8773416, 151.1948287), + (-33.8740845, 151.1923322), + (-33.8697019, 151.1850566), + (-33.8625354, 151.1902636), + (-33.8612915, 151.1986805), + (-33.8555555, 151.1979259), + ] - out = h3.polyfill(geo, 9, True) - assert len(out) > 10 + poly = h3.Polygon(sydney) + out = h3.polygon_to_cells(poly, 9) + assert len(out) == 92 + assert '89be0e34207ffff' in out + assert '89be0e35ddbffff' in out def test_polyfill_far_east(): - geo = { - 'type': 'Polygon', - 'coordinates': [ - [ - [142.86483764648438, 41.92578147109541], - [142.86483764648438, 42.29965889253408], - [143.41552734375, 42.29965889253408], - [143.41552734375, 41.92578147109541], - [142.86483764648438, 41.92578147109541], - ] - ] - } + geo = [ + (41.92578147109541, 142.86483764648438), + (42.29965889253408, 142.86483764648438), + (42.29965889253408, 143.41552734375), + (41.92578147109541, 143.41552734375), + (41.92578147109541, 142.86483764648438), + ] - out = h3.polyfill(geo, 9, True) - assert len(out) > 10 + poly = h3.Polygon(geo) + out = h3.polygon_to_cells(poly, 9) + assert len(out) == 18507 + assert '892e18d16c3ffff' in out + assert '892e1ebb5a7ffff' in out def test_polyfill_southern_tip(): - geo = { - 'type': 'Polygon', - 'coordinates': [ - [ - [-67.642822265625, -55.41654360858007], - [-67.642822265625, -54.354955689554096], - [-64.742431640625, -54.354955689554096], - [-64.742431640625, -55.41654360858007], - [-67.642822265625, -55.41654360858007], - ] - ] - } + geo = [ + (-55.41654360858007, -67.642822265625), + (-54.354955689554096, -67.642822265625), + (-54.354955689554096, -64.742431640625), + (-55.41654360858007, -64.742431640625), + (-55.41654360858007, -67.642822265625), + ] - out = h3.polyfill(geo, 9, True) - assert len(out) > 10 + poly = h3.Polygon(geo) + out = h3.polygon_to_cells(poly, 9) + assert len(out) == 223247 + assert '89df4000003ffff' in out + assert '89df4636b27ffff' in out def test_polyfill_null_island(): - geo = { - "type": "Polygon", - "coordinates": [ - [ - [-3.218994140625, -3.0856655287215378], - [-3.218994140625, 3.6888551431470478], - [3.5815429687499996, 3.6888551431470478], - [3.5815429687499996, -3.0856655287215378], - [-3.218994140625, -3.0856655287215378], - ] - ] - } + geo = [ + (-3, -3), + (+3, -3), + (+3, +3), + (-3, +3), + (-3, -3), + ] - out = h3.polyfill(geo, 4, True) - assert len(out) > 10 + poly = h3.Polygon(geo) + out = h3.polygon_to_cells(poly, 4) + assert len(out) == 345 + assert '847421bffffffff' in out + assert '84825ddffffffff' in out -def test_h3_set_to_multi_polygon_empty(): - out = h3.h3_set_to_multi_polygon([]) - assert out == [] +def test_cells_to_polygons_empty(): + polys = h3.cells_to_polygons([]) + assert polys == [] -def test_h3_set_to_multi_polygon_single(): +def test_cells_to_polygons_single(): h = '89283082837ffff' - hexes = {h} + cells = {h} - # multi_polygon - mp = h3.h3_set_to_multi_polygon(hexes) - vertices = h3.h3_to_geo_boundary(h) + polys = h3.cells_to_polygons(cells) + assert len(polys) == 1 + poly = polys[0] - # We shift the expected circular list so that it starts from - # multi_polygon[0][0][0], since output starting from any vertex - # would be correct as long as it's in order. - expected_coords = shift_circular_list( - mp[0][0][0], - [ - vertices[2], - vertices[3], - vertices[4], - vertices[5], - vertices[0], - vertices[1], - ] - ) + vertices = h3.cell_to_boundary(h) + expected_poly = h3.Polygon(vertices) - expected = [[expected_coords]] - - assert mp == expected + assert set(poly.outer) == set(expected_poly.outer) + assert poly.holes == expected_poly.holes == () -def test_h3_set_to_multi_polygon_single_geo_json(): - hexes = ['89283082837ffff'] - mp = h3.h3_set_to_multi_polygon(hexes, True) - vertices = h3.h3_to_geo_boundary(hexes[0], True) +def test_cells_to_polygons_contiguous(): + a = '89283082837ffff' + b = '89283082833ffff' + assert h3.are_neighbor_cells(a, b) - # We shift the expected circular list so that it starts from - # multi_polygon[0][0][0], since output starting from any vertex - # would be correct as long as it's in order. - expected_coords = shift_circular_list( - mp[0][0][0], - [ - vertices[2], - vertices[3], - vertices[4], - vertices[5], - vertices[0], - vertices[1] - ] - ) + polys = h3.cells_to_polygons([a, b]) + assert len(polys) == 1 + poly = polys[0] - expected = [[expected_coords]] + assert len(poly.outer) == 10 + assert poly.holes == () - # polygon count matches expected - assert len(mp) == 1 - - # loop count matches expected - assert len(mp[0]) == 1 - - # coord count 7 matches expected according to geojson format - assert len(mp[0][0]) == 7 - - # first coord should be the same as last coord according to geojson format - assert mp[0] == mp[-1] - - # the coord should be (lng, lat) according to geojson format - assert mp[0][0][0][0] == approx(-122.42778275313199) - assert mp[0][0][0][1] == approx(37.77598951883773) - - # Discard last coord for testing below, since last coord is - # the same as the first one - mp[0][0].pop() - assert mp == expected + verts_a = h3.cell_to_boundary(a) + verts_b = h3.cell_to_boundary(b) + assert set(poly.outer) == set(verts_a) | set(verts_b) -def test_h3_set_to_multi_polygon_contiguous(): - # the second hexagon shares v0 and v1 with the first - hexes = ['89283082837ffff', '89283082833ffff'] +def test_cells_to_polygons_non_contiguous(): + a = '89283082837ffff' + b = '8928308280fffff' + assert not h3.are_neighbor_cells(a, b) - # multi_polygon - mp = h3.h3_set_to_multi_polygon(hexes) - vertices0 = h3.h3_to_geo_boundary(hexes[0]) - vertices1 = h3.h3_to_geo_boundary(hexes[1]) + polys = h3.cells_to_polygons([a, b]) + assert len(polys) == 2 - # We shift the expected circular list so that it starts from - # multi_polygon[0][0][0], since output starting from any vertex - # would be correct as long as it's in order. - expected_coords = shift_circular_list( - mp[0][0][0], - [ - vertices1[0], - vertices1[1], - vertices1[2], - vertices0[1], - vertices0[2], - vertices0[3], - vertices0[4], - vertices0[5], - vertices1[4], - vertices1[5], - ] - ) + assert all(poly.holes == () for poly in polys) + assert all(len(poly.outer) == 6 for poly in polys) - expected = [[expected_coords]] + verts_a = h3.cell_to_boundary(a) + verts_b = h3.cell_to_boundary(b) - assert len(mp) == 1 # polygon count matches expected - assert len(mp[0]) == 1 # loop count matches expected - assert len(mp[0][0]) == 10 # coord count matches expected - - assert mp == expected + verts_both = set.union(*[set(poly.outer) for poly in polys]) + assert verts_both == set(verts_a) | set(verts_b) -def test_h3_set_to_multi_polygon_non_contiguous(): - # the second hexagon does not touch the first - hexes = {'89283082837ffff', '8928308280fffff'} - # multi_polygon - mp = h3.h3_set_to_multi_polygon(hexes) - - assert len(mp) == 2 # polygon count matches expected - assert len(mp[0]) == 1 # loop count matches expected - assert len(mp[0][0]) == 6 # coord count 1 matches expected - assert len(mp[1][0]) == 6 # coord count 2 matches expected - - -def test_h3_set_to_multi_polygon_hole(): +def test_cells_to_polygons_hole(): # Six hexagons in a ring around a hole - hexes = [ + cells = [ '892830828c7ffff', '892830828d7ffff', '8928308289bffff', '89283082813ffff', '8928308288fffff', '89283082883ffff', ] - mp = h3.h3_set_to_multi_polygon(hexes) + polys = h3.cells_to_polygons(cells) - assert len(mp) == 1 # polygon count matches expected - assert len(mp[0]) == 2 # loop count matches expected - assert len(mp[0][0]) == 6 * 3 # outer coord count matches expected - assert len(mp[0][1]) == 6 # inner coord count matches expected + assert len(polys) == 1 + poly = polys[0] + + assert len(poly.holes) == 1 + assert len(poly.holes[0]) == 6 + assert len(poly.outer) == 6 * 3 -def test_h3_set_to_multi_polygon_2k_ring(): +def test_cells_to_polygons_2grid_disk(): h = '8930062838bffff' - hexes = h3.k_ring(h, 2) - # multi_polygon - mp = h3.h3_set_to_multi_polygon(hexes) + cells = h3.grid_disk(h, 2) + polys = h3.cells_to_polygons(cells) - assert len(mp) == 1 # polygon count matches expected - assert len(mp[0]) == 1 # loop count matches expected - assert len(mp[0][0]) == 6 * (2 * 2 + 1) # coord count matches expected + assert len(polys) == 1 + poly = polys[0] - hexes2 = { - '89300628393ffff', '89300628383ffff', '89300628397ffff', - '89300628067ffff', '89300628387ffff', '893006283bbffff', - '89300628313ffff', '893006283cfffff', '89300628303ffff', - '89300628317ffff', '8930062839bffff', h, - '8930062806fffff', '8930062838fffff', '893006283d3ffff', - '893006283c3ffff', '8930062831bffff', '893006283d7ffff', - '893006283c7ffff' - } - - mp2 = h3.h3_set_to_multi_polygon(hexes2) - - assert len(mp2) == 1 # polygon count matches expected - assert len(mp2[0]) == 1 # loop count matches expected - assert len(mp2[0][0]) == 6 * (2 * 2 + 1) # coord count matches expected - - hexes3 = list(h3.k_ring(h, 6)) - hexes3.sort() - mp3 = h3.h3_set_to_multi_polygon(hexes3) - - assert len(mp3[0]) == 1 # loop count matches expected + assert len(poly.holes) == 0 + assert len(poly.outer) == 6 * (2 * 2 + 1) -def test_hex_ring(): +def test_grid_ring(): h = '8928308280fffff' - out = h3.hex_ring(h, 1) + out = h3.grid_ring(h, 1) expected = { '8928308280bffff', '89283082807ffff', @@ -568,12 +410,12 @@ def test_hex_ring(): } assert out == expected - assert out == h3.k_ring(h, 1) - h3.k_ring(h, 0) + assert out == h3.grid_disk(h, 1) - h3.grid_disk(h, 0) -def test_hex_ring2(): +def test_grid_ring2(): h = '8928308280fffff' - out = h3.hex_ring(h, 2) + out = h3.grid_ring(h, 2) expected = { '89283082813ffff', @@ -591,12 +433,12 @@ def test_hex_ring2(): } assert out == expected - assert out == h3.k_ring(h, 2) - h3.k_ring(h, 1) + assert out == h3.grid_disk(h, 2) - h3.grid_disk(h, 1) -def test_hex_ring_pentagon(): +def test_grid_ring_pentagon(): h = '821c07fffffffff' - out = h3.hex_ring(h, 1) + out = h3.grid_ring(h, 1) expected = { '821c17fffffffff', @@ -609,342 +451,163 @@ def test_hex_ring_pentagon(): assert out == expected -def test_compact_and_uncompact(): - geo = { - 'type': 'Polygon', - 'coordinates': [ - [ - [37.813318999983238, -122.4089866999972145], - [37.7866302000007224, -122.3805436999997056], - [37.7198061999978478, -122.3544736999993603], - [37.7076131999975672, -122.5123436999983966], - [37.7835871999971715, -122.5247187000021967], - [37.8151571999998453, -122.4798767000009008], - ] - ] - } +def test_compact_and_uncompact_cells(): + poly = h3.Polygon(sf_7x7) + cells = h3.polygon_to_cells(poly, 9) - hexes = h3.polyfill(geo, 9) + compact_cells = h3.compact_cells(cells) + assert len(compact_cells) == 209 - compact_hexes = h3.compact(hexes) - assert len(compact_hexes) == 209 + uncompact_cells = h3.uncompact_cells(compact_cells, 9) + assert len(uncompact_cells) == 1253 - uncompact_hexes = h3.uncompact(compact_hexes, 9) - assert len(uncompact_hexes) == 1253 + assert uncompact_cells == cells -def test_compact_and_uncompact_nothing(): - assert h3.compact([]) == set() - assert h3.uncompact([], 9) == set() +def test_compact_cells_and_uncompact_cells_nothing(): + assert h3.compact_cells([]) == set() + assert h3.uncompact_cells([], 9) == set() -def test_uncompact_error(): - hexagons = [h3.geo_to_h3(37, -122, 10)] +def test_uncompact_cells_error(): + hexagons = [h3.latlng_to_cell(37, -122, 10)] with pytest.raises(Exception): - h3.uncompact(hexagons, 5) + h3.uncompact_cells(hexagons, 5) -def test_compact_malformed_input(): - hexes = ['89283082813ffff'] * 13 +def test_compact_cells_malformed_input(): + cells = ['89283082813ffff'] * 13 with pytest.raises(Exception): - h3.compact(hexes) + h3.compact_cells(cells) -def test_h3_to_parent(): +def test_cell_to_parent(): h = '89283082813ffff' - assert h3.h3_to_parent(h, 8) == '8828308281fffff' + assert h3.cell_to_parent(h, 8) == '8828308281fffff' -def test_h3_to_children(): +def test_cell_to_children(): h = '8828308281fffff' - children = h3.h3_to_children(h, 9) + children = h3.cell_to_children(h, 9) assert len(children) == 7 -def test_hex_range(): - h = '8928308280fffff' - out = h3.hex_range(h, 1) - assert len(out) == 1 + 6 - - expected = { - '8928308280bffff', - '89283082807ffff', - h, - '89283082877ffff', - '89283082803ffff', - '89283082873ffff', - '8928308283bffff', - } - - assert out == expected - - -def test_hex_range2(): - h = '8928308280fffff' - out = h3.hex_range(h, 2) - - assert len(out) == 1 + 6 + 12 - - expected = { - '89283082813ffff', - '89283082817ffff', - '8928308281bffff', - '89283082863ffff', - '89283082823ffff', - '89283082873ffff', - '89283082877ffff', - '8928308287bffff', - '89283082833ffff', - '8928308282bffff', - '8928308283bffff', - '89283082857ffff', - '892830828abffff', - '89283082847ffff', - '89283082867ffff', - '89283082803ffff', - h, - '89283082807ffff', - '8928308280bffff', - } - - assert out == expected - - -def test_hex_range_pentagon(): - h = '821c07fffffffff' # a pentagon - - # should consist of `h` and it's 5 neighbors - out = h3.hex_range(h, 1) - - expected = { - h, - '821c17fffffffff', - '821c1ffffffffff', - '821c27fffffffff', - '821c2ffffffffff', - '821c37fffffffff', - } - - assert out == expected - - -def test_hex_range_distances(): - h = '8928308280fffff' - - # should consist of `h` and it's 5 neighbors - out = h3.hex_range_distances(h, 1) - - expected = [ - {h}, - { - '8928308280bffff', - '89283082807ffff', - '89283082877ffff', - '89283082803ffff', - '89283082873ffff', - '8928308283bffff', - } - ] - - assert out == expected - - -def test_hex_range_distances_pentagon(): - - h = '821c07fffffffff' - out = h3.hex_range_distances(h, 1) - - expected = [ - {h}, - { - '821c17fffffffff', - '821c1ffffffffff', - '821c27fffffffff', - '821c2ffffffffff', - '821c37fffffffff', - } - ] - - assert out == expected - - -def test_hex_ranges(): - h = '8928308280fffff' - out = h3.hex_ranges([h], 1) - - assert set(out.keys()) == {h} - - expected = [ - {h}, - { - '8928308280bffff', - '89283082807ffff', - '89283082877ffff', - '89283082803ffff', - '89283082873ffff', - '8928308283bffff', - } - ] - - assert out[h] == expected - - -def test_hex_ranges_pentagon(): - h = '821c07fffffffff' - out = h3.hex_ranges([h], 1) - - expected = { - h: [ - {h}, - { - '821c17fffffffff', - '821c1ffffffffff', - '821c27fffffffff', - '821c2ffffffffff', - '821c37fffffffff' - } - ] - } - - assert out == expected - - -def test_many_hex_ranges(): - hexes = h3.k_ring('8928308280fffff', 2) - out = h3.hex_ranges(hexes, 2) - - assert len(out) == 19 - - hexes = out['8928308280fffff'] - assert [len(x) for x in hexes] == [1, 6, 12] - - -def test_many_hex_ranges2(): - hexes = h3.k_ring('8928308280fffff', 5) - out = h3.hex_ranges(hexes, 5) - assert len(out) == 91 - - hexes = out['8928308280fffff'] - - assert [len(x) for x in hexes] == [1, 6, 12, 18, 24, 30] - - -def test_hex_area(): +def test_average_hexagon_area(): for i in range(0, 15): - assert isinstance(h3.hex_area(i), float) - assert isinstance(h3.hex_area(i, 'm^2'), float) + assert isinstance(h3.average_hexagon_area(i), float) + assert isinstance(h3.average_hexagon_area(i, 'm^2'), float) with pytest.raises(ValueError): - h3.hex_area(5, 'ft^2') + h3.average_hexagon_area(5, 'ft^2') -def test_edge_length(): +def test_average_hexagon_edge_length(): for i in range(0, 15): - assert isinstance(h3.edge_length(i), float) - assert isinstance(h3.edge_length(i, 'm'), float) + assert isinstance(h3.average_hexagon_edge_length(i), float) + assert isinstance(h3.average_hexagon_edge_length(i, 'm'), float) with pytest.raises(ValueError): - h3.edge_length(5, 'ft') + h3.average_hexagon_edge_length(5, 'ft') -def test_num_hexagons(): +def test_get_num_cells(): h0 = 122 - assert h3.num_hexagons(0) == h0 + assert h3.get_num_cells(0) == h0 for i in range(0, 15): - n = h3.num_hexagons(i) * 1.0 / h0 + n = h3.get_num_cells(i) * 1.0 / h0 assert 6**i <= n <= 7**i -def test_h3_get_base_cell(): - assert h3.h3_get_base_cell('8928308280fffff') == 20 +def test_get_base_cell_number(): + assert h3.get_base_cell_number('8928308280fffff') == 20 -def test_h3_is_res_class_iiiIII(): - assert h3.h3_is_res_class_iii('8928308280fffff') - assert not h3.h3_is_res_class_iii('8828308280fffff') - assert h3.h3_is_res_class_III('8928308280fffff') +def test_is_res_class_III(): + assert h3.is_res_class_III('8928308280fffff') + assert not h3.is_res_class_III('8828308280fffff') -def test_h3_is_pentagon(): - assert h3.h3_is_pentagon('821c07fffffffff') - assert not h3.h3_is_pentagon('8928308280fffff') +def test_is_pentagon(): + assert h3.is_pentagon('821c07fffffffff') + assert not h3.is_pentagon('8928308280fffff') -def test_h3_indexes_are_neighbors(): - assert h3.h3_indexes_are_neighbors('8928308280fffff', '8928308280bffff') - assert not h3.h3_indexes_are_neighbors('821c07fffffffff', '8928308280fffff') +def test_are_neighbor_cells(): + assert h3.are_neighbor_cells('8928308280fffff', '8928308280bffff') + + assert not h3.are_neighbor_cells('821c07fffffffff', '8928308280fffff') -def test_get_h3_unidirectional_edge(): - out = h3.get_h3_unidirectional_edge('8928308280fffff', '8928308280bffff') - assert h3.h3_unidirectional_edge_is_valid(out) +def test_cells_to_directed_edge(): + out = h3.cells_to_directed_edge('8928308280fffff', '8928308280bffff') + assert h3.is_valid_directed_edge(out) - with pytest.raises(ValueError): - h3.get_h3_unidirectional_edge('821c07fffffffff', '8928308280fffff') + with pytest.raises(h3.H3NotNeighborsError): + h3.cells_to_directed_edge('821c07fffffffff', '8928308280fffff') -def test_h3_unidirectional_edge_is_valid(): - assert not h3.h3_unidirectional_edge_is_valid('8928308280fffff') - assert h3.h3_unidirectional_edge_is_valid('11928308280fffff') +def test_is_valid_directed_edge(): + assert not h3.is_valid_directed_edge('8928308280fffff') + assert h3.is_valid_directed_edge('11928308280fffff') -def test_get_origin_h3_index_from_unidirectional_edge(): - out = h3.get_origin_h3_index_from_unidirectional_edge('11928308280fffff') +def test_get_directed_edge_origin(): + out = h3.get_directed_edge_origin('11928308280fffff') assert out == '8928308280fffff' -def test_get_destination_h3_index_from_unidirectional_edge(): +def test_get_directed_edge_destination(): h = '11928308280fffff' - out = h3.get_destination_h3_index_from_unidirectional_edge(h) + out = h3.get_directed_edge_destination(h) assert out == '8928308283bffff' -def test_get_h3_indexes_from_unidirectional_edge(): - e = h3.get_h3_indexes_from_unidirectional_edge('11928308280fffff') +def test_directed_edge_to_cells(): + e = h3.directed_edge_to_cells('11928308280fffff') assert e == ('8928308280fffff', '8928308283bffff') -def test_get_h3_unidirectional_edges_from_hexagon(): - h3_uni_edges = h3.get_h3_unidirectional_edges_from_hexagon( +def test_origin_to_directed_edges(): + h3_uni_edges = h3.origin_to_directed_edges( '8928308280fffff' ) assert len(h3_uni_edges) == 6 - h3_uni_edge_pentagon = h3.get_h3_unidirectional_edges_from_hexagon( + h3_uni_edge_pentagon = h3.origin_to_directed_edges( '821c07fffffffff' ) assert len(h3_uni_edge_pentagon) == 5 -def test_get_h3_unidirectional_edge_boundary(): +def test_directed_edge_to_boundary(): e = '11928308280fffff' - boundary = h3.get_h3_unidirectional_edge_boundary(e) + boundary = h3.directed_edge_to_boundary(e) assert len(boundary) == 2 - boundary_geo_json = h3.get_h3_unidirectional_edge_boundary(e, True) + boundary_geo_json = h3.directed_edge_to_boundary(e, True) assert len(boundary_geo_json) == 3 -def test_h3_distance(): +def test_grid_distance(): h = '89283082993ffff' - assert 0 == h3.h3_distance(h, h) - assert 1 == h3.h3_distance(h, '8928308299bffff') - assert 5 == h3.h3_distance(h, '89283082827ffff') + assert 0 == h3.grid_distance(h, h) + assert 1 == h3.grid_distance(h, '8928308299bffff') + assert 5 == h3.grid_distance(h, '89283082827ffff') -def test_h3_line(): +def test_grid_path_cells(): h1 = '8a2a84730587fff' h2 = '8a2a8471414ffff' - out = h3.h3_line(h1, h2) + out = h3.grid_path_cells(h1, h2) expected = [ h1, @@ -982,5 +645,5 @@ def test_h3_line(): assert out == expected - with pytest.raises(ValueError): - h3.h3_line(h1, '8001fffffffffff') + with pytest.raises(h3.H3ResMismatchError): + h3.grid_path_cells(h1, '8001fffffffffff') diff --git a/tests/test_length_area.py b/tests/test_length_area.py index 8236199..8851a4b 100644 --- a/tests/test_length_area.py +++ b/tests/test_length_area.py @@ -1,8 +1,6 @@ import h3 import pytest -from h3 import H3ValueError - def approx2(a, b): if len(a) != len(b): @@ -15,10 +13,10 @@ def approx2(a, b): def cell_perimiter1(h, unit='km'): - edges = h3.get_h3_unidirectional_edges_from_hexagon(h) + edges = h3.origin_to_directed_edges(h) dists = [ - h3.exact_edge_length(e, unit=unit) + h3.edge_length(e, unit=unit) for e in edges ] @@ -28,12 +26,12 @@ def cell_perimiter1(h, unit='km'): def cell_perimiter2(h, unit='km'): - verts = h3.h3_to_geo_boundary(h) + verts = h3.cell_to_boundary(h) N = len(verts) verts += (verts[0],) dists = [ - h3.point_dist(verts[i], verts[i + 1], unit=unit) + h3.great_circle_distance(verts[i], verts[i + 1], unit=unit) for i in range(N) ] @@ -63,7 +61,7 @@ def test_areas_at_00(): ] out = [ - h3.cell_area(h3.geo_to_h3(0, 0, r), unit='km^2') + h3.cell_area(h3.latlng_to_cell(0, 0, r), unit='km^2') for r in range(16) ] @@ -89,7 +87,7 @@ def test_areas_at_00(): ] out = [ - h3.cell_area(h3.geo_to_h3(0, 0, r), unit='rads^2') + h3.cell_area(h3.latlng_to_cell(0, 0, r), unit='rads^2') for r in range(16) ] @@ -100,41 +98,42 @@ def test_bad_units(): h = '89754e64993ffff' e = '139754e64993ffff' - assert h3.h3_is_valid(h) - assert h3.h3_unidirectional_edge_is_valid(e) + assert h3.is_valid_cell(h) + assert h3.is_valid_directed_edge(e) - with pytest.raises(H3ValueError): + with pytest.raises(ValueError): h3.cell_area(h, unit='foot-pounds') - with pytest.raises(H3ValueError): - h3.exact_edge_length(h, unit='foot-pounds') + with pytest.raises(ValueError): + h3.edge_length(e, unit='foot-pounds') - with pytest.raises(H3ValueError): - h3.point_dist((0, 0), (0, 0), unit='foot-pounds') + with pytest.raises(ValueError): + h3.great_circle_distance((0, 0), (0, 0), unit='foot-pounds') -def test_point_dist(): +def test_great_circle_distance(): lyon = (45.7597, 4.8422) # (lat, lon) paris = (48.8567, 2.3508) - d = h3.point_dist(lyon, paris, unit='rads') + d = h3.great_circle_distance(lyon, paris, unit='rads') assert d == pytest.approx(0.0615628186794217) - d = h3.point_dist(lyon, paris, unit='m') + d = h3.great_circle_distance(lyon, paris, unit='m') assert d == pytest.approx(392217.1598841777) - d = h3.point_dist(lyon, paris, unit='km') + d = h3.great_circle_distance(lyon, paris, unit='km') assert d == pytest.approx(392.21715988417765) # test that 'km' is the default unit - assert h3.point_dist(lyon, paris, unit='km') == h3.point_dist(lyon, paris) + dist = h3.great_circle_distance + assert dist(lyon, paris, unit='km') == dist(lyon, paris) def test_cell_perimiter_calculations(): resolutions = [0, 1] for r in resolutions: - cells = h3.uncompact(h3.get_res0_indexes(), r) + cells = h3.uncompact_cells(h3.get_res0_cells(), r) for h in cells: for unit in ['rads', 'm', 'km']: v1 = cell_perimiter1(h, unit) diff --git a/tests/test_memview_int.py b/tests/test_memview_int.py index 9923b75..0e7e56e 100644 --- a/tests/test_memview_int.py +++ b/tests/test_memview_int.py @@ -2,15 +2,16 @@ import h3.api.memview_int as h3 def test1(): - assert h3.geo_to_h3(37.7752702151959, -122.418307270836, 9) == 617700169958293503 + lat, lng = 37.7752702151959, -122.418307270836 + assert h3.latlng_to_cell(lat, lng, 9) == 617700169958293503 def test_line(): h1 = '8928308280fffff' h2 = '8928308287bffff' - h1, h2 = h3.string_to_h3(h1), h3.string_to_h3(h2) + h1, h2 = h3.str_to_int(h1), h3.str_to_int(h2) - out = h3.h3_line(h1, h2) + out = h3.grid_path_cells(h1, h2) # todo: are we outputting `memoryviewslice`? should we just output a memoryview? assert 'memoryview' in str(type(out)) @@ -24,18 +25,18 @@ def test_line(): assert list(out) == expected -def test_get_faces(): +def test_get_icosahedron_faces(): h = 577832942814887935 expected = {2, 3, 7, 8, 12} - out = h3.h3_get_faces(h) + out = h3.get_icosahedron_faces(h) assert out == expected h = 579873636396040191 expected = {13} - out = h3.h3_get_faces(h) + out = h3.get_icosahedron_faces(h) assert out == expected h = 579768083279773695 expected = {16, 15} - out = h3.h3_get_faces(h) + out = h3.get_icosahedron_faces(h) assert out == expected diff --git a/tests/test_numpy_int.py b/tests/test_numpy_int.py index 8169772..c565518 100644 --- a/tests/test_numpy_int.py +++ b/tests/test_numpy_int.py @@ -3,7 +3,8 @@ import numpy as np # only run this test suite if numpy is installed def test1(): - assert h3.geo_to_h3(37.7752702151959, -122.418307270836, 9) == 617700169958293503 + lat, lng = 37.7752702151959, -122.418307270836, + assert h3.latlng_to_cell(lat, lng, 9) == 617700169958293503 def test5(): @@ -17,31 +18,31 @@ def test5(): 617700169965109247, } - out = h3.k_ring(617700169958293503, 1) + out = h3.grid_disk(617700169958293503, 1) assert isinstance(out, np.ndarray) assert set(out) == expected -def test_compact(): +def test_compact_cells(): h = 617700169958293503 - hexes = h3.h3_to_children(h) - assert isinstance(hexes, np.ndarray) + cells = h3.cell_to_children(h) + assert isinstance(cells, np.ndarray) - assert set(h3.compact(hexes)) == {h} + assert set(h3.compact_cells(cells)) == {h} -def test_get_faces(): +def test_get_icosahedron_faces(): h = 577832942814887935 expected = {2, 3, 7, 8, 12} - out = h3.h3_get_faces(h) + out = h3.get_icosahedron_faces(h) assert out == expected h = 579873636396040191 expected = {13} - out = h3.h3_get_faces(h) + out = h3.get_icosahedron_faces(h) assert out == expected h = 579768083279773695 expected = {16, 15} - out = h3.h3_get_faces(h) + out = h3.get_icosahedron_faces(h) assert out == expected diff --git a/tests/test_polyfill.py b/tests/test_polyfill.py index 4739009..6e2c550 100644 --- a/tests/test_polyfill.py +++ b/tests/test_polyfill.py @@ -2,6 +2,8 @@ import h3 import itertools import pytest +from h3 import H3ResDomainError + def reverse(loop): return list(reversed(loop)) @@ -29,21 +31,22 @@ def chain_toggle_map(func, seq): return seq -def input_permutations(poly, res=5): - g = [poly] +def input_permutations(geo, res=5): + g = [geo] g = chain_toggle_map(drop_last, g) g = chain_toggle_map(reverse, g) for p in g: - hexes = h3.polyfill_polygon(p[0], res=res, holes=p[1:]) - yield hexes + poly = h3.Polygon(*p) + cells = h3.polygon_to_cells(poly, res=res) + yield cells def swap_element_order(seq): return [e[::-1] for e in seq] -def get_us_box_coords(order='latlng'): +def get_us_box_coords(): # big center chunk of the US in lat/lng order outer = [ @@ -69,13 +72,10 @@ def get_us_box_coords(order='latlng'): [41.37, -98.61] ] - if order == 'lnglat': - outer, hole1, hole2 = map(swap_element_order, [outer, hole1, hole2]) - return outer, hole1, hole2 -def test_polyfill_polygon(): +def test_polygon_to_cells(): # lat/lngs for State of Maine maine = [ @@ -111,72 +111,74 @@ def test_polyfill_polygon(): '832badfffffffff' } - out = h3.polyfill_polygon(maine, 3) + poly = h3.Polygon(maine) + out = h3.polygon_to_cells(poly, 3) assert out == expected -def test_polyfill_polygon_order(): - lnglat, _, _ = get_us_box_coords(order='lnglat') +def test_polygon_to_cells2(): + lnglat, _, _ = get_us_box_coords() - out = h3.polyfill_polygon(lnglat, 5, lnglat_order=True) + poly = h3.Polygon(lnglat) + out = h3.polygon_to_cells(poly, 5) assert len(out) == 7063 -# # todo: we can generate segfaults with malformed input data to polyfill -# # need to test for this and avoid segfault -# # def test_polyfill_segfault(): -# # pass +# todo: we can generate segfaults with malformed input data to polyfill +# need to test for this and avoid segfault +# def test_polyfill_segfault(): +# pass -def test_polyfill_polygon_holes(): +def test_polygon_to_cells_holes(): outer, hole1, hole2 = get_us_box_coords() assert 7063 == len( - h3.polyfill_polygon(outer, 5) + h3.polygon_to_cells(h3.Polygon(outer), 5) ) for res in 1, 2, 3, 4, 5: - hexes_all = h3.polyfill_polygon(outer, res) - hexes_holes = h3.polyfill_polygon(outer, res, [hole1, hole2]) + cells_all = h3.polygon_to_cells(h3.Polygon(outer), res) + cells_holes = h3.polygon_to_cells(h3.Polygon(outer, hole1, hole2), res=res) - hexes_1 = h3.polyfill_polygon(hole1, res) - hexes_2 = h3.polyfill_polygon(hole2, res) + cells_1 = h3.polygon_to_cells(h3.Polygon(hole1), res) + cells_2 = h3.polygon_to_cells(h3.Polygon(hole2), res) - assert len(hexes_all) == len(hexes_holes) + len(hexes_1) + len(hexes_2) - assert hexes_all == set.union(hexes_holes, hexes_1, hexes_2) + assert len(cells_all) == len(cells_holes) + len(cells_1) + len(cells_2) + assert cells_all == set.union(cells_holes, cells_1, cells_2) -def test_polyfill_geojson(): - outer, hole1, hole2 = get_us_box_coords(order='lnglat') +# def test_polyfill_geojson(): +# outer, hole1, hole2 = get_us_box_coords(order='lnglat') - d = { - 'type': 'Polygon', - 'coordinates': [outer], - } +# d = { +# 'type': 'Polygon', +# 'coordinates': [outer], +# } - out = h3.polyfill_geojson(d, 5) +# out = h3.polyfill_geojson(d, 5) - assert len(out) == 7063 +# assert len(out) == 7063 -def test_polyfill(): - outer, hole1, hole2 = get_us_box_coords(order='lnglat') +# def test_polyfill(): +# outer, hole1, hole2 = get_us_box_coords(order='lnglat') - d = { - 'type': 'Polygon', - 'coordinates': [outer], - } +# d = { +# 'type': 'Polygon', +# 'coordinates': [outer], +# } - out = h3.polyfill(d, 5, geo_json_conformant=True) +# out = h3.polyfill(d, 5, geo_json_conformant=True) - assert len(out) == 7063 +# assert len(out) == 7063 def test_input_format(): - """ Test that `polyfill_polygon` can take in polygon inputs + """ Test that `polygon_to_cells` can take in polygon inputs where the LinearRings may or may not follow the right hand rule, and they may or may not be closed loops (where the last element is equal to the first). @@ -186,34 +188,34 @@ def test_input_format(): may follow a different subset of rules. """ - poly = get_us_box_coords(order='latlng') + geo = get_us_box_coords() - assert len(poly) == 3 + assert len(geo) == 3 # two holes - for hexes in input_permutations(poly[:3]): - assert len(hexes) == 5437 + for cells in input_permutations(geo[:3]): + assert len(cells) == 5437 # one hole - for hexes in input_permutations(poly[:2]): - assert len(hexes) == 5726 + for cells in input_permutations(geo[:2]): + assert len(cells) == 5726 # zero holes - for hexes in input_permutations(poly[:1]): - assert len(hexes) == 7063 + for cells in input_permutations(geo[:1]): + assert len(cells) == 7063 def test_resolution(): - d = { - 'type': 'Polygon', - 'coordinates': [[]], - } + poly = h3.Polygon([]) - with pytest.raises(h3.H3ResolutionError): - h3.polyfill(d, -1) + assert h3.polygon_to_cells(poly, 0) == set() + assert h3.polygon_to_cells(poly, 15) == set() - with pytest.raises(h3.H3ResolutionError): - h3.polyfill(d, 16) + with pytest.raises(H3ResDomainError): + h3.polygon_to_cells(poly, -1) + + with pytest.raises(H3ResDomainError): + h3.polygon_to_cells(poly, 16) def test_invalid_polygon(): @@ -222,27 +224,17 @@ def test_invalid_polygon(): this because we weren't raising errors inside some `cdef` functions. """ - - # one - d = { - 'type': 'Polygon', - 'coordinates': [1, 2, 3], - } with pytest.raises(TypeError): - h3.polyfill(d, 4) + poly = h3.Polygon([1, 2, 3]) + h3.polygon_to_cells(poly, 4) - # two - d = { - 'type': 'Polygon', - 'coordinates': [[1, 2, 3]], - } - with pytest.raises(TypeError): - h3.polyfill(d, 4) + with pytest.raises(ValueError): + poly = h3.Polygon([[1, 2, 3]]) + h3.polygon_to_cells(poly, 4) - # three - d = { - 'type': 'Polygon', - 'coordinates': [(1, 2), (2, 2), (2, 1), (1, 2)], - } - with pytest.raises(TypeError): - h3.polyfill(d, 4) + # d = { + # 'type': 'Polygon', + # 'coordinates': [(1, 2), (2, 2), (2, 1), (1, 2)], + # } + # with pytest.raises(TypeError): + # h3.polyfill(d, 4) diff --git a/tests/test_polygon_class.py b/tests/test_polygon_class.py new file mode 100644 index 0000000..d14b62a --- /dev/null +++ b/tests/test_polygon_class.py @@ -0,0 +1,27 @@ +import h3 + + +def test_repr(): + a = '8928308280fffff' + b = h3.grid_ring(a, 5).pop() + + cells1 = h3.grid_ring(b, 2) | {a} + cells2 = cells1 | {b} + + poly1 = h3.cells_to_polygons(cells1) + poly2 = h3.cells_to_polygons(cells2) + + # unfortunately output order is nondeterministic + poly1 = sorted(map(str, poly1)) + poly2 = sorted(map(str, poly2)) + + assert poly1 == [ + '', + '', + ] + + assert poly2 == [ + '', + '', + '', + ] diff --git a/tests/test_to_multipoly.py b/tests/test_to_multipoly.py index 0b899b9..be2b948 100644 --- a/tests/test_to_multipoly.py +++ b/tests/test_to_multipoly.py @@ -1,61 +1,32 @@ import h3 -def test_h3_set_to_multi_polygon(): +def test_cells_to_polygons(): h = '8928308280fffff' - hexes = h3.k_ring(h, 1) + cells = h3.grid_disk(h, 1) - mpoly = h3.h3_set_to_multi_polygon(hexes) + polys = h3.cells_to_polygons(cells) + poly = polys[0] - out = h3.polyfill_polygon(mpoly[0][0], 9, holes=None, lnglat_order=False) + poly2 = h3.Polygon(poly.outer, *poly.holes) + out = h3.polygon_to_cells(poly2, 9) - assert out == hexes + assert out == cells def test_2_polys(): h = '8928308280fffff' - hexes = h3.hex_ring(h, 2) - hexes = hexes | {h} - # hexes should be a center hex, and the 2-ring around it + cells = h3.grid_ring(h, 2) + cells = cells | {h} + # cells should be a center hex, and the 2-ring around it # (with the 1-ring being absent) + polys = h3.cells_to_polygons(cells) + out = [ - h3.polyfill_polygon(poly[0], 9, holes=poly[1:], lnglat_order=False) - for poly in h3.h3_set_to_multi_polygon(hexes, geo_json=False) + h3.polygon_to_cells(poly, 9) + for poly in polys ] - assert set.union(*out) == hexes - - -def test_2_polys_json(): - h = '8928308280fffff' - hexes = h3.hex_ring(h, 2) - hexes = hexes | {h} - # hexes should be a center hex, and the 2-ring around it - # (with the 1-ring being absent) - - # not deterministic which poly is first.. - poly1, poly2 = h3.h3_set_to_multi_polygon(hexes, geo_json=True) - - assert {len(poly1), len(poly2)} == {1, 2} - - for poly in poly1, poly2: - for loop in poly: - assert loop[0] == loop[-1] - - -def test_2_polys_not_json(): - h = '8928308280fffff' - hexes = h3.hex_ring(h, 2) - hexes = hexes | {h} - # hexes should be a center hex, and the 2-ring around it - # (with the 1-ring being absent) - - # not deterministic which poly is first.. - poly1, poly2 = h3.h3_set_to_multi_polygon(hexes, geo_json=False) - - assert {len(poly1), len(poly2)} == {1, 2} - - for poly in poly1, poly2: - for loop in poly: - assert loop[0] != loop[-1] + assert set.union(*out) == cells + assert set(map(len, out)) == {1, 12} diff --git a/tests/test_unstable_vect.py b/tests/test_unstable_vect.py deleted file mode 100644 index a556aae..0000000 --- a/tests/test_unstable_vect.py +++ /dev/null @@ -1,69 +0,0 @@ -import h3.api.numpy_int as h3 -import numpy as np # only run this test suite if numpy is installed -import pytest - -with pytest.warns( - UserWarning, - match = 'Modules under `h3.unstable` are experimental', -): - import h3.unstable.vect as h3_vect - - -def test_h3_to_parent(): - # At res 9 - h = np.array([617700169958555647, 617700169958555647], np.uint64) - - # Default to res - 1 - arr1 = h3_vect.h3_to_parent(h) - arr2 = h3_vect.h3_to_parent(h, 8) - assert np.array_equal(arr1, arr2) - - # Same as other h3 bindings - arr1 = h3_vect.h3_to_parent(h) - arr2 = np.array(list(map(h3.h3_to_parent, h)), dtype=np.uint64) - assert np.array_equal(arr1, arr2) - - # Test with a number passed to res - arr1 = h3_vect.h3_to_parent(h, 7) - arr2 = np.array([h3.h3_to_parent(c, 7) for c in h], dtype=np.uint64) - assert np.array_equal(arr1, arr2) - - # Test with an array passed to res - arr1 = h3_vect.h3_to_parent(h, np.array([7, 5], np.intc)) - arr2 = h3_vect.h3_to_parent(h, [7, 5]) - - arr3 = [] - for c, res in zip(h, [7, 5]): - arr3.append(h3.h3_to_parent(c, res)) - - assert np.array_equal(arr1, arr2) - assert np.array_equal(arr1, np.array(arr3, dtype=np.uint64)) - - # Test with array-like (but not np.array) cell input - arr1 = h3_vect.h3_to_parent(list(h)) - arr2 = np.array(list(map(h3.h3_to_parent, h)), dtype=np.uint64) - assert np.array_equal(arr1, arr2) - - -def test_h3_to_parent_multiple_res(): - h = np.array([617700169958555647, 613196570331971583], np.uint64) - - # Cells at res 9, 8 - assert list(h3_vect.h3_get_resolution(h)) == [9, 8] - - # Same as other h3 bindings - arr1 = h3_vect.h3_to_parent(h) - arr2 = np.array(list(map(h3.h3_to_parent, h)), dtype=np.uint64) - assert np.array_equal(arr1, arr2) - - # Parent cells are 8, 7 - parents = h3_vect.h3_to_parent(h) - assert list(h3_vect.h3_get_resolution(parents)) == [8, 7] - - -def test_h3_get_resolution(): - h = np.array([617700169958555647], np.uint64) - - arr1 = h3_vect.h3_get_resolution(h) - arr2 = np.array(list(map(h3.h3_get_resolution, h)), dtype=np.intc) - assert np.array_equal(arr1, arr2) From a12a887b9be742c961941d2a29fa28e5d855f475 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Tue, 23 Aug 2022 12:35:37 -0400 Subject: [PATCH 062/177] prep for v4.0 beta 1 release (#280) --- CHANGELOG.md | 13 +++++++++++++ src/h3/_polygon.py | 4 ++++ src/h3/_version.py | 2 +- 3 files changed, 18 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cbab906..d5fba1a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,19 @@ avoid adding features or APIs which do not map onto the - None +## [4.0.0b1] - 2022-08-23 + +Beta release; feedback welcome! + +- Move to v4.0 of the core C library (#250) + + Function name changes: https://github.com/uber/h3/blob/master/dev-docs/RFCs/v4.0.0/names_for_concepts_types_functions.md + + New error system + + New interfaces for `polygon_to_cells` and `cells_to_polygons` + involving a new `h3.Polygon` class +- Expose the Cython API (#234) + + Note: The Cython API is not yet stable, and should only be used for + experimentation + ## [3.7.4] - 2022-04-14 - Website and API documentation; along with docstring cleanup. diff --git a/src/h3/_polygon.py b/src/h3/_polygon.py index 6ef2e94..e5f81ee 100644 --- a/src/h3/_polygon.py +++ b/src/h3/_polygon.py @@ -38,6 +38,10 @@ class Polygon: ... ) + TODO + ---- + + - Add GeoJSON translation support. """ def __init__(self, outer, *holes): self.outer = outer diff --git a/src/h3/_version.py b/src/h3/_version.py index 41540d5..55bd81e 100644 --- a/src/h3/_version.py +++ b/src/h3/_version.py @@ -1,4 +1,4 @@ -__version__ = '4.0.0' +__version__ = '4.0.0b1' __description__ = 'Hierarchical hexagonal geospatial indexing system' __url__ = 'https://github.com/uber/h3-py' __license__ = 'Apache 2.0 License' From 5ed4102152538fbc9bfde70f3df690ddadc2c5f2 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Tue, 23 Aug 2022 13:06:02 -0400 Subject: [PATCH 063/177] fix TODO issue with docs (#282) --- src/h3/_polygon.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/h3/_polygon.py b/src/h3/_polygon.py index e5f81ee..c36c569 100644 --- a/src/h3/_polygon.py +++ b/src/h3/_polygon.py @@ -38,10 +38,10 @@ class Polygon: ... ) - TODO - ---- + Notes + ----- - - Add GeoJSON translation support. + - TODO: Add GeoJSON translation support. """ def __init__(self, outer, *holes): self.outer = outer From d2ca8f31fa88736b8499f1629f60ded2633365dc Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Fri, 26 Aug 2022 19:37:19 -0400 Subject: [PATCH 064/177] beta announce admonition (#283) * beta announce * try this instead * double the warning! * meh, let's see how github renders it * try the quote block again * try br * try some hrules * bah * move around * merp * headers * revert because it adds a horizontal line in github * ooofffffff --- .github/workflows/deploy_docs.yml | 5 ++++- readme.md | 14 +++++++++++++- 2 files changed, 17 insertions(+), 2 deletions(-) diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml index d932763..360dc00 100644 --- a/.github/workflows/deploy_docs.yml +++ b/.github/workflows/deploy_docs.yml @@ -34,8 +34,11 @@ jobs: # Build the book - name: Build the book + # turn off warningiserror just for https://github.com/uber/h3-py/pull/283 + # jupyter-book build docs/ --warningiserror --keep-going --all run: | - jupyter-book build docs/ --warningiserror --keep-going --all + jupyter-book build docs/ --keep-going --all + # Deploy the book's HTML to gh-pages branch - name: GitHub Pages action diff --git a/readme.md b/readme.md index 3ab3803..07aabb0 100644 --- a/readme.md +++ b/readme.md @@ -13,12 +13,24 @@ [![Tests](https://github.com/uber/h3-py/workflows/tests/badge.svg)](https://github.com/uber/h3-py/actions) [![codecov](https://codecov.io/gh/uber/h3-py/branch/master/graph/badge.svg)](https://codecov.io/gh/uber/h3-py) +---- +### ANNOUNCEMENT: v4.0.0 beta released! +Install the latest beta version with `pip install h3 --pre` +or +`pip install 'h3==4.0.0b1'`.
+Feedback is welcome via +[Issues](https://github.com/uber/h3-py/issues/new), +[Discussions](https://github.com/uber/h3/discussions), +and +[Slack](https://join.slack.com/t/h3-core/shared_invite/zt-g6u5r1hf-W_~uVJmfeiWtMQuBGc1NNg). + +---- + Python bindings for the [H3 core library](https://h3geo.org/). - Documentation: [uber.github.io/h3-py](https://uber.github.io/h3-py) - GitHub repo: [github.com/uber/h3-py](https://github.com/uber/h3-py) - ## Installation From [PyPI](https://pypi.org/project/h3/): From 454a404fd1068805a4139284322ea70c33514ab7 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 28 Aug 2022 16:45:30 -0700 Subject: [PATCH 065/177] Update readme.md --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 07aabb0..b723c19 100644 --- a/readme.md +++ b/readme.md @@ -16,7 +16,7 @@ ---- ### ANNOUNCEMENT: v4.0.0 beta released! Install the latest beta version with `pip install h3 --pre` -or +or with `pip install 'h3==4.0.0b1'`.
Feedback is welcome via [Issues](https://github.com/uber/h3-py/issues/new), From 2b7ac39aa74c672ca3ca7e1d33eb32ff85831aba Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Wed, 21 Sep 2022 21:05:53 -0400 Subject: [PATCH 066/177] Update _api_template.py (#286) --- src/h3/api/_api_template.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/h3/api/_api_template.py b/src/h3/api/_api_template.py index 7baa27e..ea49092 100644 --- a/src/h3/api/_api_template.py +++ b/src/h3/api/_api_template.py @@ -354,7 +354,7 @@ class _API_FUNCTIONS(object): """ Compact a collection of H3 cells by combining smaller cells into larger cells, if all child cells - are present. + are present. Input cells must all share the same resolution. Parameters ---------- From 939ebaa48e52be90d66282a06930d788658d2ff0 Mon Sep 17 00:00:00 2001 From: SADIK KUZU Date: Fri, 14 Oct 2022 01:15:47 +0300 Subject: [PATCH 067/177] Fix typos (#287) * Fix typo * Fix typo --- tests/test_error_codes.py | 2 +- tests/test_polyfill.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/test_error_codes.py b/tests/test_error_codes.py index d8229b3..9961178 100644 --- a/tests/test_error_codes.py +++ b/tests/test_error_codes.py @@ -51,7 +51,7 @@ def test_unknown(): assert err.args == (weird_code,) -def test_atributes(): +def test_attributes(): # errors always have an `h3_error_code` attribute for err in h3_exceptions: x = err.h3_error_code diff --git a/tests/test_polyfill.py b/tests/test_polyfill.py index 6e2c550..e52be22 100644 --- a/tests/test_polyfill.py +++ b/tests/test_polyfill.py @@ -14,7 +14,7 @@ def drop_last(loop): def toggle_map(func, poly): - """ Return all permuations of `func` being applied or not + """ Return all permutations of `func` being applied or not to each element of `poly` returns iterable of length 2**len(poly) From 3eece401ba311feeba99073eb65db2764ef85557 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Wed, 23 Nov 2022 16:25:00 -0800 Subject: [PATCH 068/177] Prep for 4.0.0b2 release supporting py3.11 (#297) * prep for 4.0.0b2 release supporting py3.11 * update cibuildwheel@v2.11.2 * update a few actions * actions/setup-python@v4.3.0 * ilammy/msvc-dev-cmd@v1.12.0 * docker/setup-qemu-action@v2.1.0 * changelog --- .github/workflows/coverage-lint.yml | 6 +++--- .github/workflows/deploy_docs.yml | 2 +- .github/workflows/tests.yml | 10 +++++----- .github/workflows/wheels.yml | 17 ++++++++++------- CHANGELOG.md | 4 ++++ src/h3/_version.py | 3 ++- 6 files changed, 25 insertions(+), 17 deletions(-) diff --git a/.github/workflows/coverage-lint.yml b/.github/workflows/coverage-lint.yml index 6d33368..a43ba66 100644 --- a/.github/workflows/coverage-lint.yml +++ b/.github/workflows/coverage-lint.yml @@ -2,9 +2,9 @@ name: coverage-lint on: push: - branches: [master, dev_v4] + branches: [master] pull_request: - branches: [master, dev_v4] + branches: [master] jobs: tests: @@ -16,7 +16,7 @@ jobs: with: submodules: recursive - - uses: actions/setup-python@v3.1.1 + - uses: actions/setup-python@v4.3.0 with: python-version: 3.8 diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml index 360dc00..7d8e889 100644 --- a/.github/workflows/deploy_docs.yml +++ b/.github/workflows/deploy_docs.yml @@ -18,7 +18,7 @@ jobs: with: submodules: recursive - - uses: actions/setup-python@v3.1.1 + - uses: actions/setup-python@v4.3.0 with: python-version: 3.8 diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 072e21c..3275d56 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -2,9 +2,9 @@ name: tests on: push: - branches: [master, dev_v4] + branches: [master] pull_request: - branches: [master, dev_v4] + branches: [master] jobs: tests: @@ -14,7 +14,7 @@ jobs: strategy: matrix: os: [macos-latest, windows-latest, ubuntu-latest] - python-version: ['2.7', '3.5', '3.6', '3.7', '3.8', '3.9', '3.10'] + python-version: ['2.7', '3.5', '3.6', '3.7', '3.8', '3.9', '3.10', '3.11'] exclude: - os: windows-latest python-version: 2.7 @@ -26,12 +26,12 @@ jobs: with: submodules: recursive - - uses: actions/setup-python@v3.1.1 + - uses: actions/setup-python@v4.3.0 with: python-version: "${{ matrix.python-version }}" ## Start Windows stuff - - uses: ilammy/msvc-dev-cmd@v1.10.0 + - uses: ilammy/msvc-dev-cmd@v1.12.0 if: startsWith(matrix.os, 'windows') - name: Set Windows Compiler diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index a02f51d..64ef108 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -2,9 +2,9 @@ name: wheels on: push: - branches: [master, dev_v4] + branches: [master] pull_request: - branches: [master, dev_v4] + branches: [master] types: # Opened, synchronize, and reopened are the default types # We add ready_for_review to additionally trigger when converting from draft to non-draft @@ -33,7 +33,7 @@ jobs: submodules: recursive - name: Setup Python - uses: actions/setup-python@v3.1.2 + uses: actions/setup-python@v4.3.0 - name: Make sdist run: | @@ -128,6 +128,9 @@ jobs: - os: ubuntu-latest build: "cp310-manylinux_aarch64" name: Linux Aarch64 3.10 + - os: ubuntu-latest + build: "cp311-manylinux_aarch64" + name: Linux Aarch64 3.11 steps: - uses: actions/checkout@v3 @@ -136,7 +139,7 @@ jobs: ## Setup Env - - uses: ilammy/msvc-dev-cmd@v1.10.0 + - uses: ilammy/msvc-dev-cmd@v1.12.0 if: runner.os == 'Windows' - name: Set Windows variables @@ -148,13 +151,13 @@ jobs: - name: Set up QEMU if: runner.os == 'Linux' - uses: docker/setup-qemu-action@v1.2.0 + uses: docker/setup-qemu-action@v2.1.0 with: platforms: aarch64 ## Build - - uses: pypa/cibuildwheel@v2.4.0 + - uses: pypa/cibuildwheel@v2.11.2 env: CIBW_TEST_REQUIRES: pytest numpy CIBW_TEST_COMMAND: pytest {project}/tests @@ -183,6 +186,6 @@ jobs: name: artifact path: dist - - uses: pypa/gh-action-pypi-publish@v1.5.0 + - uses: pypa/gh-action-pypi-publish@v1.5.1 with: password: ${{ secrets.pypi_password }} diff --git a/CHANGELOG.md b/CHANGELOG.md index d5fba1a..7fb30c6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,10 @@ avoid adding features or APIs which do not map onto the - None +## [4.0.0b2] - 2022-11-23 + +- Build Python 3.11 wheels (#297) + ## [4.0.0b1] - 2022-08-23 Beta release; feedback welcome! diff --git a/src/h3/_version.py b/src/h3/_version.py index 55bd81e..56fe687 100644 --- a/src/h3/_version.py +++ b/src/h3/_version.py @@ -1,4 +1,4 @@ -__version__ = '4.0.0b1' +__version__ = '4.0.0b2' __description__ = 'Hierarchical hexagonal geospatial indexing system' __url__ = 'https://github.com/uber/h3-py' __license__ = 'Apache 2.0 License' @@ -18,6 +18,7 @@ __classifiers__ = [ 'Programming Language :: Python :: 3.8', 'Programming Language :: Python :: 3.9', 'Programming Language :: Python :: 3.10', + 'Programming Language :: Python :: 3.11', 'Operating System :: MacOS :: MacOS X', 'Operating System :: POSIX :: Linux', 'Operating System :: Microsoft :: Windows', From 1e1459b336301efee4267bcbee6eba81ab431ef7 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 24 Nov 2022 13:30:31 -0800 Subject: [PATCH 069/177] Resetting the submodule --- dev_notes.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/dev_notes.md b/dev_notes.md index 51c1c5f..f1b3d53 100644 --- a/dev_notes.md +++ b/dev_notes.md @@ -35,6 +35,16 @@ git add h3lib git commit ... ``` +## Resetting the submodule + +For when moving between `h3-py` branches using different versions of the +`h3lib` submodule. + +```sh +git submodule deinit -f . +git submodule update --init +``` + ## Releasing a new version - update `CHANGELOG.md` to reflect any changes since the last release From c667719e4bde0eb7e7edc829572a8d6818bbcab5 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 24 Nov 2022 13:32:44 -0800 Subject: [PATCH 070/177] Update readme.md --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index b723c19..eab09ad 100644 --- a/readme.md +++ b/readme.md @@ -17,7 +17,7 @@ ### ANNOUNCEMENT: v4.0.0 beta released! Install the latest beta version with `pip install h3 --pre` or with -`pip install 'h3==4.0.0b1'`.
+`pip install 'h3==4.0.0b2'`.
Feedback is welcome via [Issues](https://github.com/uber/h3-py/issues/new), [Discussions](https://github.com/uber/h3/discussions), From ae9865c1522e0b62dc668d6b2beb49cd1b4ec63f Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 25 Mar 2023 21:39:00 -0700 Subject: [PATCH 071/177] Update github actions (#317) * actions/setup-python@v4.5.0 * Solution copied from https://github.com/actions/setup-python/issues/544 --- .github/workflows/coverage-lint.yml | 2 +- .github/workflows/deploy_docs.yml | 4 ++-- .github/workflows/tests.yml | 4 ++-- .github/workflows/wheels.yml | 24 ++++++++++++------------ 4 files changed, 17 insertions(+), 17 deletions(-) diff --git a/.github/workflows/coverage-lint.yml b/.github/workflows/coverage-lint.yml index a43ba66..4662661 100644 --- a/.github/workflows/coverage-lint.yml +++ b/.github/workflows/coverage-lint.yml @@ -16,7 +16,7 @@ jobs: with: submodules: recursive - - uses: actions/setup-python@v4.3.0 + - uses: actions/setup-python@v4.5.0 with: python-version: 3.8 diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml index 7d8e889..7902e5f 100644 --- a/.github/workflows/deploy_docs.yml +++ b/.github/workflows/deploy_docs.yml @@ -11,14 +11,14 @@ on: jobs: build-docs: name: Build docs - runs-on: ubuntu-latest + runs-on: ubuntu-20.04 steps: - uses: actions/checkout@v3 with: submodules: recursive - - uses: actions/setup-python@v4.3.0 + - uses: actions/setup-python@v4.5.0 with: python-version: 3.8 diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 3275d56..e972d28 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -13,7 +13,7 @@ jobs: strategy: matrix: - os: [macos-latest, windows-latest, ubuntu-latest] + os: [macos-latest, windows-latest, ubuntu-20.04] python-version: ['2.7', '3.5', '3.6', '3.7', '3.8', '3.9', '3.10', '3.11'] exclude: - os: windows-latest @@ -26,7 +26,7 @@ jobs: with: submodules: recursive - - uses: actions/setup-python@v4.3.0 + - uses: actions/setup-python@v4.5.0 with: python-version: "${{ matrix.python-version }}" diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 64ef108..5bb7a32 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -25,7 +25,7 @@ jobs: strategy: matrix: - os: [ubuntu-latest] + os: [ubuntu-20.04] steps: - uses: actions/checkout@v3 @@ -33,7 +33,7 @@ jobs: submodules: recursive - name: Setup Python - uses: actions/setup-python@v4.3.0 + uses: actions/setup-python@v4.5.0 - name: Make sdist run: | @@ -67,7 +67,7 @@ jobs: - os: macos-latest build: "cp27-macosx_x86_64" name: macOS Intel - - os: ubuntu-latest + - os: ubuntu-20.04 build: "cp27-manylinux_x86_64" name: Linux Intel 64-bit @@ -107,28 +107,28 @@ jobs: - os: windows-latest build: "cp3*-win_amd64" name: Windows 64-bit - - os: ubuntu-latest + - os: ubuntu-20.04 build: "cp*-manylinux_x86_64" name: Linux Intel glibc 64-bit - - os: ubuntu-latest + - os: ubuntu-20.04 build: "cp*-musllinux_x86_64" name: Linux Intel musl 64-bit - - os: ubuntu-latest + - os: ubuntu-20.04 build: "cp36-manylinux_aarch64" name: Linux Aarch64 3.6 - - os: ubuntu-latest + - os: ubuntu-20.04 build: "cp37-manylinux_aarch64" name: Linux Aarch64 3.7 - - os: ubuntu-latest + - os: ubuntu-20.04 build: "cp38-manylinux_aarch64" name: Linux Aarch64 3.8 - - os: ubuntu-latest + - os: ubuntu-20.04 build: "cp39-manylinux_aarch64" name: Linux Aarch64 3.9 - - os: ubuntu-latest + - os: ubuntu-20.04 build: "cp310-manylinux_aarch64" name: Linux Aarch64 3.10 - - os: ubuntu-latest + - os: ubuntu-20.04 build: "cp311-manylinux_aarch64" name: Linux Aarch64 3.11 @@ -177,7 +177,7 @@ jobs: upload_all: needs: [make_sdist, make_cibw_v1_wheels, make_cibw_v2_wheels] - runs-on: ubuntu-latest + runs-on: ubuntu-20.04 if: github.event_name == 'release' && github.event.action == 'published' steps: From a02947be0d5cd60d66463ef12551919ede901c10 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 10 Aug 2023 16:17:59 -1000 Subject: [PATCH 072/177] avoid cython warning --- tests/cython_example.pyx | 1 + 1 file changed, 1 insertion(+) diff --git a/tests/cython_example.pyx b/tests/cython_example.pyx index a465bd6..8e58d2c 100644 --- a/tests/cython_example.pyx +++ b/tests/cython_example.pyx @@ -1,3 +1,4 @@ +#cython: language_level=3 from cython cimport boundscheck, wraparound from h3._cy.h3lib cimport H3int From 45d1df087e5de7b00d9b1b858e6f687534b57e08 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 10 Aug 2023 16:22:41 -1000 Subject: [PATCH 073/177] drop 2.7 --- .github/workflows/tests.yml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index e972d28..2b25e0f 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -14,10 +14,7 @@ jobs: strategy: matrix: os: [macos-latest, windows-latest, ubuntu-20.04] - python-version: ['2.7', '3.5', '3.6', '3.7', '3.8', '3.9', '3.10', '3.11'] - exclude: - - os: windows-latest - python-version: 2.7 + python-version: ['3.5', '3.6', '3.7', '3.8', '3.9', '3.10', '3.11'] - os: windows-latest python-version: 3.5 From c2a20d1c4c0bcb7239498a75aa78e115d91096c9 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 3 Dec 2023 15:46:07 -0800 Subject: [PATCH 074/177] Drop cibuildwheel v1 and 3.5 tests (#325) * Drop cibuildwheel v1 and 3.5 tests * try cibuildwheel@v2.15.0 * drop down to cibuildwheel@v2.14.1 * bump ubuntu from 20.04 to 22.04 * Revert "bump ubuntu from 20.04 to 22.04" This reverts commit f94bea6d8773a49b1c90bb62fa154f070195ae97. * bump Python version from 3.8 to 3.11 for coverage/lint and docs * bump cibuildwheel --- .github/workflows/coverage-lint.yml | 4 +-- .github/workflows/deploy_docs.yml | 2 +- .github/workflows/tests.yml | 4 +-- .github/workflows/wheels.yml | 42 ++--------------------------- 4 files changed, 6 insertions(+), 46 deletions(-) diff --git a/.github/workflows/coverage-lint.yml b/.github/workflows/coverage-lint.yml index 4662661..0280c0c 100644 --- a/.github/workflows/coverage-lint.yml +++ b/.github/workflows/coverage-lint.yml @@ -9,7 +9,7 @@ on: jobs: tests: name: Coverage and Lint - runs-on: ubuntu-latest + runs-on: ubuntu-22.04 steps: - uses: actions/checkout@v3 @@ -18,7 +18,7 @@ jobs: - uses: actions/setup-python@v4.5.0 with: - python-version: 3.8 + python-version: 3.11 - name: Install from source run: | diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml index 7902e5f..c3a4c3e 100644 --- a/.github/workflows/deploy_docs.yml +++ b/.github/workflows/deploy_docs.yml @@ -20,7 +20,7 @@ jobs: - uses: actions/setup-python@v4.5.0 with: - python-version: 3.8 + python-version: 3.11 - name: Install dependencies run: | diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 2b25e0f..f694e47 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -14,9 +14,7 @@ jobs: strategy: matrix: os: [macos-latest, windows-latest, ubuntu-20.04] - python-version: ['3.5', '3.6', '3.7', '3.8', '3.9', '3.10', '3.11'] - - os: windows-latest - python-version: 3.5 + python-version: ['3.6', '3.7', '3.8', '3.9', '3.10', '3.11'] steps: - uses: actions/checkout@v3 diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 5bb7a32..babcea2 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -56,44 +56,6 @@ jobs: with: path: ./dist - make_cibw_v1_wheels: - name: "cibuildwheel v1: ${{ matrix.name }}" - if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }} - runs-on: ${{ matrix.os }} - strategy: - matrix: - # Only build for platforms that cibw v2 doesn't support - include: - - os: macos-latest - build: "cp27-macosx_x86_64" - name: macOS Intel - - os: ubuntu-20.04 - build: "cp27-manylinux_x86_64" - name: Linux Intel 64-bit - - steps: - - uses: actions/checkout@v3 - with: - submodules: recursive - - ## Build - - - uses: pypa/cibuildwheel@v1.12.0 - env: - CIBW_TEST_REQUIRES: pytest numpy - CIBW_TEST_COMMAND: pytest {project}/tests - CIBW_ARCHS_LINUX: auto aarch64 - CIBW_BUILD: ${{ matrix.build }} - - - name: Check with Twine - run: | - pipx run twine check wheelhouse/* - - - name: Upload artifacts to GitHub - uses: actions/upload-artifact@v3 - with: - path: wheelhouse/*.whl - make_cibw_v2_wheels: name: "cibuildwheel v2: ${{ matrix.name }}" if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }} @@ -157,7 +119,7 @@ jobs: ## Build - - uses: pypa/cibuildwheel@v2.11.2 + - uses: pypa/cibuildwheel@v2.16.2 env: CIBW_TEST_REQUIRES: pytest numpy CIBW_TEST_COMMAND: pytest {project}/tests @@ -176,7 +138,7 @@ jobs: path: wheelhouse/*.whl upload_all: - needs: [make_sdist, make_cibw_v1_wheels, make_cibw_v2_wheels] + needs: [make_sdist, make_cibw_v2_wheels] runs-on: ubuntu-20.04 if: github.event_name == 'release' && github.event.action == 'published' From 831d50bbe36bddd3ca789c2500b7c9c74779e0d8 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 30 Dec 2023 15:16:02 -0800 Subject: [PATCH 075/177] GeoJSON functions (#301) * polygons_to_cells * Helpers for cells_to_geojson and geojson_to_cells * ValueError * Remove gj (#316) * Remove geojson logic from cell_to_boundary and directed_edge_to_boundary * fix a warning about return values in tests from pytest * Remove geo_json logic from cells_to_multi_polygon * remove some unused tests * add back in polygons_to_cells * actions/setup-python@v4.5.0 * Solution copied from https://github.com/actions/setup-python/issues/544 * playing around with polygons * make a directory * bah * start migrating `h3.Polygon` to `H3Poly` * migrate most * finish migrating * H3MultiPoly repr * shape_to_cells and cells_to_shape * tests: polygon_to_cells to shape_to_cells * finish migrating tests * update util.py and example * notes * bah * fix lint * fix * remove X_to_shape * run tests * run other CIs too * don't use f-string * test update * change errors per review * remove unused per review * fix lint * test run * fix exclude logic in tests * " to ' in yaml * move conversion logic to geo_to_cells function * linting * few more tests * lint * clean up * complete tests * group geojson/polygon tests into a folder * move MockGeoInterface into the file that uses it * move test_input_format to its own file, since it has a lot of helper functions not used elsewhere * test module description * rename _polygon.py to _h3shape.py * make H3Shape an ABC * shape -> h3shape * geos to polys * rename geo files to latlng * docstrings * __init__.py * lint * notebooks * more interface tests * notebooks * merp * clean up geo_to_h3shape() * simplify sydney coords * simplify far east test * simplify sf coords * tuples * geo interface tests * more interface tests * clean up maine lat/lngs * messed up lat/lng order in tests. this mistake gets made all the time! * expand geo_to_h3shape test * plotting with contextily and geoviews * reprs for H3Shape objects should work better with geopandas * different representations of the same information. which is best? * us "loopcode" in H3Poly and H3MultiPoly reprs * set tight=True as default * can't use f-strings in python 3.5 * notebooks * basic plotting * plotting * plotting * tutorial notebook * cleaning up * clean up geoviews example * remove geoviews example * todos * reworking tutorial order * notebook dump * cleaner * move tutorial * Update src/h3/api/_api_template.py Co-authored-by: Jongbin Jung * Update src/h3/api/_api_template.py Co-authored-by: Isaac Brodsky * Update src/h3/api/_api_template.py Co-authored-by: Jongbin Jung * setting loops * bug and lint --------- Co-authored-by: Isaac Brodsky Co-authored-by: Jongbin Jung --- .flake8 | 2 + .github/workflows/coverage-lint.yml | 2 +- .github/workflows/tests.yml | 4 +- .github/workflows/wheels.yml | 26 +- docs/polygon_tutorial.ipynb | 936 +++++++++++++++++++++++ makefile | 2 +- requirements-dev.txt | 8 + src/h3/__init__.py | 1 - src/h3/_cy/CMakeLists.txt | 6 +- src/h3/_cy/__init__.py | 3 +- src/h3/_cy/{geo.pxd => latlng.pxd} | 0 src/h3/_cy/{geo.pyx => latlng.pyx} | 34 +- src/h3/_cy/to_multipoly.pyx | 17 +- src/h3/_h3shape.py | 311 ++++++++ src/h3/_polygon.py | 56 -- src/h3/api/_api_template.py | 109 ++- src/h3/api/basic_int/__init__.py | 10 +- src/h3/api/basic_int/_public_api.py | 6 +- src/h3/api/basic_str/__init__.py | 10 +- src/h3/api/memview_int/__init__.py | 10 +- src/h3/api/numpy_int/__init__.py | 10 +- tests/cython_example.pyx | 2 +- tests/polyfill/test_h3.py | 379 +++++++++ tests/polyfill/test_polyfill.py | 161 ++++ tests/polyfill/test_polyfill_ordering.py | 96 +++ tests/polyfill/test_polygon_class.py | 37 + tests/polyfill/test_to_multipoly.py | 43 ++ tests/test_cells_and_edges.py | 44 +- tests/test_h3.py | 290 +------ tests/test_polyfill.py | 240 ------ tests/test_polygon_class.py | 27 - tests/test_to_multipoly.py | 32 - 32 files changed, 2158 insertions(+), 756 deletions(-) create mode 100644 docs/polygon_tutorial.ipynb create mode 100644 requirements-dev.txt rename src/h3/_cy/{geo.pxd => latlng.pxd} (100%) rename src/h3/_cy/{geo.pyx => latlng.pyx} (92%) create mode 100644 src/h3/_h3shape.py delete mode 100644 src/h3/_polygon.py create mode 100644 tests/polyfill/test_h3.py create mode 100644 tests/polyfill/test_polyfill.py create mode 100644 tests/polyfill/test_polyfill_ordering.py create mode 100644 tests/polyfill/test_polygon_class.py create mode 100644 tests/polyfill/test_to_multipoly.py delete mode 100644 tests/test_polyfill.py delete mode 100644 tests/test_polygon_class.py delete mode 100644 tests/test_to_multipoly.py diff --git a/.flake8 b/.flake8 index fedf9fd..3f950dd 100644 --- a/.flake8 +++ b/.flake8 @@ -14,3 +14,5 @@ ignore = E241, # E731 do not assign a lambda expression, use a def E731, + # https://stackoverflow.com/questions/67942075/w504-line-break-after-binary-operator + W503,W504 diff --git a/.github/workflows/coverage-lint.yml b/.github/workflows/coverage-lint.yml index 0280c0c..878239a 100644 --- a/.github/workflows/coverage-lint.yml +++ b/.github/workflows/coverage-lint.yml @@ -4,7 +4,7 @@ on: push: branches: [master] pull_request: - branches: [master] + branches: ['*'] jobs: tests: diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index f694e47..a5b4fec 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -4,7 +4,7 @@ on: push: branches: [master] pull_request: - branches: [master] + branches: ['*'] jobs: tests: @@ -23,7 +23,7 @@ jobs: - uses: actions/setup-python@v4.5.0 with: - python-version: "${{ matrix.python-version }}" + python-version: '${{ matrix.python-version }}' ## Start Windows stuff - uses: ilammy/msvc-dev-cmd@v1.12.0 diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index babcea2..5d4bc60 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -4,7 +4,7 @@ on: push: branches: [master] pull_request: - branches: [master] + branches: ['*'] types: # Opened, synchronize, and reopened are the default types # We add ready_for_review to additionally trigger when converting from draft to non-draft @@ -19,7 +19,7 @@ on: jobs: make_sdist: - name: "SDist: ${{ matrix.os }}" + name: 'SDist: ${{ matrix.os }}' if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }} runs-on: ${{ matrix.os }} @@ -57,41 +57,41 @@ jobs: path: ./dist make_cibw_v2_wheels: - name: "cibuildwheel v2: ${{ matrix.name }}" + name: 'cibuildwheel v2: ${{ matrix.name }}' if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }} runs-on: ${{ matrix.os }} strategy: matrix: include: - os: macos-latest - build: "cp*-macosx*" + build: 'cp*-macosx*' name: macOS - os: windows-latest - build: "cp3*-win_amd64" + build: 'cp3*-win_amd64' name: Windows 64-bit - os: ubuntu-20.04 - build: "cp*-manylinux_x86_64" + build: 'cp*-manylinux_x86_64' name: Linux Intel glibc 64-bit - os: ubuntu-20.04 - build: "cp*-musllinux_x86_64" + build: 'cp*-musllinux_x86_64' name: Linux Intel musl 64-bit - os: ubuntu-20.04 - build: "cp36-manylinux_aarch64" + build: 'cp36-manylinux_aarch64' name: Linux Aarch64 3.6 - os: ubuntu-20.04 - build: "cp37-manylinux_aarch64" + build: 'cp37-manylinux_aarch64' name: Linux Aarch64 3.7 - os: ubuntu-20.04 - build: "cp38-manylinux_aarch64" + build: 'cp38-manylinux_aarch64' name: Linux Aarch64 3.8 - os: ubuntu-20.04 - build: "cp39-manylinux_aarch64" + build: 'cp39-manylinux_aarch64' name: Linux Aarch64 3.9 - os: ubuntu-20.04 - build: "cp310-manylinux_aarch64" + build: 'cp310-manylinux_aarch64' name: Linux Aarch64 3.10 - os: ubuntu-20.04 - build: "cp311-manylinux_aarch64" + build: 'cp311-manylinux_aarch64' name: Linux Aarch64 3.11 steps: diff --git a/docs/polygon_tutorial.ipynb b/docs/polygon_tutorial.ipynb new file mode 100644 index 0000000..fde0ce2 --- /dev/null +++ b/docs/polygon_tutorial.ipynb @@ -0,0 +1,936 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "03ee1f11-7a60-4761-aaf7-673ea04e7dca", + "metadata": {}, + "source": [ + "# H3 and (Multi)Polygons\n", + "\n", + "`h3-py` can convert between sets of cells and GeoJSON-like polygon and multipolygon shapes.\n", + "\n", + "We use the abstract base class `H3Shape` and its concrete child classes `H3Poly` and `H3MultiPoly`\n", + "to represent these shapes. \n", + "Any references or function names that use \"H3Shape\" will apply to both `H3Poly` and `H3MultiPoly` objects.\n", + "\n", + "`h3-py` is also compatible with Python objects that implement `__geo_interface__` (https://gist.github.com/sgillies/2217756),\n", + "making it easy to interface with other Python geospatial libraries.\n", + "We'll refer to any such object as a \"geo\" or \"geo object\".\n", + "\n", + "`H3Poly` and `H3MultiPoly` both implement `__geo_interface__` (making them geo objects themselves),\n", + "and can be created from other geo objects, like Shapely's `Polygon` or `MultiPolygon` objects that occur\n", + "when using `geopandas`.\n", + "\n", + "Below, we'll explain the `h3-py` API for working with these shapes, and how the library interacts\n", + "with other Python geospatial libraries.\n", + "\n", + "To start, we'll import relevant libraries, and define some plotting helper functions to visualize the shapes we're dealing with." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0f5454f0-f65e-491c-b534-f1ef08320263", + "metadata": {}, + "outputs": [], + "source": [ + "import h3\n", + "\n", + "import geopandas\n", + "import geodatasets\n", + "import contextily as cx\n", + "import matplotlib.pyplot as plt\n", + "\n", + "def plot_df(df, column=None, ax=None):\n", + " 'Plot based on the `geometry` column of a GeoPandas dataframe'\n", + " df = df.copy()\n", + " df = df.to_crs(epsg=3857) # web mercator\n", + "\n", + " if ax is None:\n", + " fig, ax = plt.subplots(figsize=(8,8))\n", + " ax.get_xaxis().set_visible(False)\n", + " ax.get_yaxis().set_visible(False)\n", + " \n", + " df.plot(\n", + " ax=ax,\n", + " alpha=0.5, edgecolor='k',\n", + " column=column, categorical=True,\n", + " legend=True, legend_kwds={'loc': 'upper left'}, \n", + " )\n", + " cx.add_basemap(ax, crs=df.crs, source=cx.providers.CartoDB.Positron)\n", + "\n", + "def plot_shape(shape, ax=None):\n", + " df = geopandas.GeoDataFrame({'geometry': [shape]}, crs='EPSG:4326')\n", + " plot_df(df, ax=ax)\n", + "\n", + "def plot_cells(cells, ax=None):\n", + " shape = h3.cells_to_h3shape(cells)\n", + " plot_shape(shape, ax=ax)\n", + "\n", + "def plot_shape_and_cells(shape, res=9):\n", + " fig, axs = plt.subplots(1,2, figsize=(10,5), sharex=True, sharey=True)\n", + " plot_shape(shape, ax=axs[0])\n", + " plot_cells(h3.h3shape_to_cells(shape, res), ax=axs[1])\n", + " fig.tight_layout()" + ] + }, + { + "cell_type": "markdown", + "id": "c5a41e2b-0c9e-45f5-8005-51af2ef8af32", + "metadata": {}, + "source": [ + "# H3Poly\n", + "\n", + "We can create a simple `H3Poly` object by providing a list of the **latitude/longitude pairs** that describe its exterior.\n", + "Optionally, holes can be added to the polygon by appending additional lat/lng lists do describe them." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1e9e3e2a-a4cf-43df-a498-ee7d15a8cc4b", + "metadata": {}, + "outputs": [], + "source": [ + "outer = [\n", + " (37.804, -122.412),\n", + " (37.778, -122.507),\n", + " (37.733, -122.501)\n", + "]\n", + "\n", + "poly = h3.H3Poly(outer)\n", + "print(poly)\n", + "plot_shape(poly)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6872b341-afc9-4405-b27a-b5f2b8a19847", + "metadata": {}, + "outputs": [], + "source": [ + "hole1 = [\n", + " (37.782, -122.449),\n", + " (37.779, -122.465),\n", + " (37.788, -122.454),\n", + "]\n", + "\n", + "poly = h3.H3Poly(outer, hole1)\n", + "print(poly)\n", + "plot_shape(poly)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2d7ae0fb-fa96-46fe-8d06-7778575642dd", + "metadata": {}, + "outputs": [], + "source": [ + "hole2 = [\n", + " (37.771, -122.484),\n", + " (37.761, -122.481),\n", + " (37.758, -122.494),\n", + " (37.769, -122.496),\n", + "]\n", + "\n", + "poly = h3.H3Poly(outer, hole1, hole2)\n", + "print(poly)\n", + "plot_shape(poly)" + ] + }, + { + "cell_type": "markdown", + "id": "62317cfd-8a0e-4c8a-b899-131acdec4305", + "metadata": {}, + "source": [ + "## String representation and attributes\n", + "\n", + "The `H3Poly` string representation given by its `__repr__` shows the number of vertices in the outer loop of the polygon, followed\n", + "by the number of vertices in each hole.\n", + "\n", + "A representation like\n", + "\n", + "```\n", + "\n", + "```\n", + "\n", + "denotes a polygon whose outer boundary consists of 3 vertices and which has 2 holes,\n", + "with 3 and 4 vertices respectively.\n", + "\n", + "We can access the coordinates describing the polygon through the attributes:\n", + "\n", + "- `H3Poly.outer` gives the list of lat/lng points making up the outer loop of the polygon.\n", + "- `H3Poly.holes` gives each of the lists of lat/lng points making up the holes of the polygon." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "97c8aa44-12fb-4c47-9254-d931522575ed", + "metadata": {}, + "outputs": [], + "source": [ + "poly = h3.H3Poly(outer, hole1, hole2)\n", + "poly" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "150ae04c-bae2-4b7e-88d0-f5fcf0835e7b", + "metadata": {}, + "outputs": [], + "source": [ + "poly.outer" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "84061e68-60f3-4df4-a279-a0630af7dcc2", + "metadata": {}, + "outputs": [], + "source": [ + "poly.holes" + ] + }, + { + "cell_type": "markdown", + "id": "ae175854-6770-44aa-b796-8d9390f7c856", + "metadata": {}, + "source": [ + "## `__geo_interface__`\n", + "\n", + "`H3Poly.__geo_interface__` gives a GeoJSON representation of the polygon as described in https://gist.github.com/sgillies/2217756\n", + "\n", + "**Note the differences in this representation**: Points are given in **lng/lat** order (but the `H3Poly` constructor expects **lat/lng** order), and the last vertex repeats the first." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "fb79c742-27aa-481c-971b-28c100109efe", + "metadata": {}, + "outputs": [], + "source": [ + "d = poly.__geo_interface__\n", + "d" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "fc1b0ae8-bcce-4e5f-ad88-57e3797518f4", + "metadata": {}, + "outputs": [], + "source": [ + "print(poly.outer)\n", + "print(poly.holes)" + ] + }, + { + "cell_type": "markdown", + "id": "8f567fae-9f4e-472f-afcd-bd6f7bb32cba", + "metadata": {}, + "source": [ + "We can create an `H3Poly` object from a GeoJSON-like dictionary or an object that implements `__geo_interface__` using `h3.geo_to_h3shape()`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "42d7d580-2bba-4cd3-8d13-2434323e4081", + "metadata": {}, + "outputs": [], + "source": [ + "h3.geo_to_h3shape(d)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c70b6fa3-d85d-420e-a295-a75a32bf3dad", + "metadata": {}, + "outputs": [], + "source": [ + "class MockGeo:\n", + " def __init__(self, d):\n", + " self.d = d\n", + "\n", + " @property\n", + " def __geo_interface__(self):\n", + " return self.d\n", + "\n", + "geo = MockGeo(d)\n", + "h3.geo_to_h3shape(geo)" + ] + }, + { + "cell_type": "markdown", + "id": "0ab82119-9d9e-465d-94b5-61083e9d9df3", + "metadata": {}, + "source": [ + "Also note that `H3Poly.__geo_interface__` is equivalent to calling `h3.h3shape_to_geo()` on an `H3Poly` object." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "fd9bd77d-ed1e-46bb-991a-f0cfc10f634b", + "metadata": {}, + "outputs": [], + "source": [ + "poly.__geo_interface__ == h3.h3shape_to_geo(poly)" + ] + }, + { + "cell_type": "markdown", + "id": "55c31b56-c65d-4e06-bf60-edf96bb57e93", + "metadata": {}, + "source": [ + "## Polygon to cells\n", + "\n", + "We can get all the H3 cells whose centroids fall within an `H3Poly` by using `h3.h3shape_to_cells()` and specifying the resolution." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6c310200-30f2-4b24-a967-d705ffc05bd6", + "metadata": {}, + "outputs": [], + "source": [ + "h3.h3shape_to_cells(poly, res=7)" + ] + }, + { + "cell_type": "markdown", + "id": "ec0d8ac7-ba97-46c4-8740-3a12a00e318d", + "metadata": {}, + "source": [ + "We'll use a helper function to show a few different resolutions." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0ac7cd51-1c7e-4509-94b4-92e59fd22c2a", + "metadata": {}, + "outputs": [], + "source": [ + "plot_shape_and_cells(poly, 7)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b0330d60-0adc-46e7-9689-7be1ba957dfc", + "metadata": {}, + "outputs": [], + "source": [ + "plot_shape_and_cells(poly, 9)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "1fd40b0a-34fd-4ac7-9c3a-c367e5041cd8", + "metadata": {}, + "outputs": [], + "source": [ + "plot_shape_and_cells(poly, 10)" + ] + }, + { + "cell_type": "markdown", + "id": "faa6a726-2adc-40cc-9e1e-5d4ee66a08ea", + "metadata": {}, + "source": [ + "## H3 Polygons don't need to follow the right-hand rule\n", + "\n", + "`H3Poly` objects do not need to follow the \"right-hand rule\", unlike GeoJSON Polygons. \n", + "The right-hand rule requires that vertices in outer loops are listed in counterclockwise\n", + "order and holes are listed in clockwise order.\n", + "`h3-py` accepts loops in any order and will usually interpret them as the user intended, for example,\n", + "converting to sets of cells. However, `h3-py` won't re-order your loops to\n", + "conform to the right-hand rule, so be careful if you're using `__geo_interface__` to plot them.\n", + "\n", + "Obeying the right-hand rule is only a concern when creating `H3Poly` objects from external input; `H3Poly` or `H3MultiPoly`\n", + "objects created through `h3.cells_to_shape()` **will respect the right-hand rule**.\n", + "\n", + "For example, if we reverse the order of one of the holes in our example polygon above,\n", + "the hole won't be rendered correctly, but the conversion to cells will remain unchanged." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "34ef8624-c852-419d-9e98-e9ec70ec6bc0", + "metadata": {}, + "outputs": [], + "source": [ + "# Respects right-hand rule\n", + "poly = h3.H3Poly(outer, hole1, hole2)\n", + "plot_shape_and_cells(poly, res=10)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "e52ae550-e34d-406b-9c82-b283fd34a170", + "metadata": {}, + "outputs": [], + "source": [ + "# Does not respect right-hand-rule; second hole is reversed\n", + "# Conversion to cells still works, tho!\n", + "poly = h3.H3Poly(outer, hole1[::-1], hole2)\n", + "plot_shape_and_cells(poly, res=10)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f1940071-eb32-44bc-b07c-2a2eef14b21e", + "metadata": {}, + "outputs": [], + "source": [ + "# Does not respect right-hand-rule; outer loop and second hole are both reversed\n", + "# Conversion to cells still works, tho!\n", + "poly = h3.H3Poly(outer[::-1], hole1[::-1], hole2)\n", + "plot_shape_and_cells(poly, res=10)" + ] + }, + { + "cell_type": "markdown", + "id": "b0b13d4a-a376-4a8f-b314-898d9cf94c59", + "metadata": {}, + "source": [ + "# H3MultiPoly\n", + "\n", + "An `H3MultiPoly` can be created from `H3Poly` objects. The string representation of the `H3MultiPoly`\n", + "gives the number of vertices in the outer loop of each `H3Poly`, along with the number of vertices\n", + "in each hole (if there are any).\n", + "\n", + "For example `` represents an `H3MultiPoly` consisting of two `H3Poly` polygons:\n", + "\n", + "- the first polygon has 3 outer vertices and no holes\n", + "- the second polygon has 4 outer vertices and 1 hole with 5 vertices" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "16b0b4b2-2cfb-461d-bd69-511c87e208a3", + "metadata": {}, + "outputs": [], + "source": [ + "poly1 = h3.H3Poly([(37.804, -122.412), (37.778, -122.507), (37.733, -122.501)])\n", + "poly2 = h3.H3Poly(\n", + " [(37.803, -122.408), (37.736, -122.491), (37.738, -122.380), (37.787, -122.39)],\n", + " [(37.760, -122.441), (37.772, -122.427), (37.773, -122.404), (37.758, -122.401), (37.745, -122.428)]\n", + ")\n", + "mpoly = h3.H3MultiPoly(poly1, poly2)\n", + "\n", + "print(poly1)\n", + "print(poly2)\n", + "print(mpoly)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f2faf991-9d3b-4e0a-8fd4-8c31e19fd07b", + "metadata": {}, + "outputs": [], + "source": [ + "plot_shape(mpoly)" + ] + }, + { + "cell_type": "markdown", + "id": "850912ae-85f1-470c-aeea-1140f549fc95", + "metadata": {}, + "source": [ + "## MultiPolygon to cells\n", + "\n", + "`h3.h3shape_to_cells()` works on both `H3MultiPoly` and `H3Poly` objects (both are subclasses of `H3Shape`)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "944564c0-8198-49ae-81de-cf980dc4b348", + "metadata": {}, + "outputs": [], + "source": [ + "cells = h3.h3shape_to_cells(mpoly, res=9)\n", + "plot_cells(cells)" + ] + }, + { + "cell_type": "markdown", + "id": "f3712d99-cbe2-4f42-80e3-0acf3fcb8e25", + "metadata": {}, + "source": [ + "## H3MultiPoly affordances\n", + "\n", + "- Calling `len()` on an `H3MultiPoly` gives the number of polygons\n", + "- You can iterate through a `H3MultiPoly`, with the elements being the underlying `H3Poly`s" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "217d6e5a-bb8b-4923-b311-0f84ebf48872", + "metadata": {}, + "outputs": [], + "source": [ + "len(mpoly)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "03f6cd31-b18f-4fe7-b259-78741f12c95d", + "metadata": {}, + "outputs": [], + "source": [ + "for p in mpoly:\n", + " print(p)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "4eca4cec-2881-4ed1-a65c-3aea38ac9c63", + "metadata": {}, + "outputs": [], + "source": [ + "list(mpoly)" + ] + }, + { + "cell_type": "markdown", + "id": "2fd0a70c-d0cf-487c-b492-6b459dc13a30", + "metadata": {}, + "source": [ + "## `__geo_interface__`\n", + "\n", + "`H3MultiPoly` implements `__geo_interface__`, and `H3MultiPoly` objects can also be created through `h3.geo_to_h3shape()`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2731474c-b3f8-4438-8932-62af21f8d6cf", + "metadata": {}, + "outputs": [], + "source": [ + "d = mpoly.__geo_interface__\n", + "d" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b5cc947e-0672-492d-a4bf-f303afbb5cfa", + "metadata": {}, + "outputs": [], + "source": [ + "geo = MockGeo(d)\n", + "h3.geo_to_h3shape(geo)" + ] + }, + { + "cell_type": "markdown", + "id": "a2b71ee2-deed-4336-8b2c-2ab740555188", + "metadata": {}, + "source": [ + "# Cells to H3Poly or H3MultiPoly\n", + "\n", + "If you have a set of H3 cells that you would like to visualize, you may want to convert them to `H3Poly` or `H3MultiPoly` objects using `h3.cells_to_h3shape()` and then use `__geo_interface__` to get their GeoJSON representation. Or you could\n", + "use `h3.cells_to_geo()` to get the GeoJSON dictionary directly." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a2305120-adf4-4cee-9e2a-58e793e55cfb", + "metadata": {}, + "outputs": [], + "source": [ + "h = h3.latlng_to_cell(37.804, -122.412, res=9)\n", + "cells = h3.grid_ring(h, 2)\n", + "cells" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "3e242238-af2c-45a3-acd0-8daf3773a2bd", + "metadata": {}, + "outputs": [], + "source": [ + "plot_cells(cells)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a9d124ff-4e49-4e34-a6be-4a49bc00bcd9", + "metadata": {}, + "outputs": [], + "source": [ + "h3.cells_to_h3shape(cells)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b3ca5d18-a78a-4bc6-80d9-d98099da924d", + "metadata": {}, + "outputs": [], + "source": [ + "str(h3.cells_to_geo(cells))[:200]" + ] + }, + { + "cell_type": "markdown", + "id": "0ae6d480-4807-4ca1-ac20-4095a20ded31", + "metadata": {}, + "source": [ + "# API Summary\n", + "\n", + "```\n", + "\"Geo object\" <-> H3Shape <-> H3 cells\n", + "```\n", + "\n", + "\"Geo objects\" are any Python object that implements `__geo_interface__`. This is a widely used\n", + "standard in geospatial Python and is used by libraries like `geopandas` and Shapely.\n", + "\n", + "`H3Shape` is an abstract class implemented by `H3Poly` and `H3MultiPoly`, each of which\n", + "implement `__geo_interface__` and can be created from external \"Geo objects\":\n", + "\n", + "- `geo_to_h3shape()`\n", + "- `h3shape_to_geo()`\n", + "\n", + "`H3Shape` objects can be converted to and from sets of H3 cells:\n", + "\n", + "- `h3shape_to_cells()`\n", + "- `cells_to_h3shape()`\n", + "\n", + "For convience, we provide functions that hide the intermediate `H3Shape` representation:\n", + "\n", + "- `geo_to_cells()`\n", + "- `cells_to_geo()`\n", + "\n", + "## Equivalance notes\n", + "\n", + "Note that if an object `a` is an `H3Shape`\n", + "then the following two expressions are equivalent:\n", + "\n", + "- `h3shape_to_geo(a)`\n", + "- `a.__geo_interface__`\n", + "\n", + "Also note that if `a` is an `H3Shape`, then `a` \"passes through\" `geo_to_h3shape()`:\n", + "\n", + "```python\n", + "geo_to_h3shape(a) == a\n", + "```" + ] + }, + { + "cell_type": "markdown", + "id": "5838f6c8-aacb-4813-be7c-756c87945476", + "metadata": {}, + "source": [ + "# Interfacing with GeoPandas and other libraries\n", + "\n", + "The `__geo_interface__` compatibility allows `h3-py` to work with `geopandas` and other geospatial libraries easily.\n", + "\n", + "To demonstrate, we start with a GeoPandas `GeoDataFrame` describing the five New York City boroughs." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "a872e2a1-dd51-4262-bc98-800500121bc0", + "metadata": {}, + "outputs": [], + "source": [ + "df = geopandas.read_file(geodatasets.get_path('nybb'))\n", + "df" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "bbca69dc-1722-4be4-a1bb-329d7e77ec83", + "metadata": {}, + "outputs": [], + "source": [ + "plot_df(df, column='BoroName')" + ] + }, + { + "cell_type": "markdown", + "id": "a060b933-8f32-402b-ac61-7cd04dcf70df", + "metadata": {}, + "source": [ + "## Use a compatible CRS before applying H3 functions\n", + "\n", + "The function `h3.geo_to_cells(geo, res)` takes some \"geo object\" that implements `__geo_interface__` (https://gist.github.com/sgillies/2217756) — like a Shapely Polygon or MultiPolygon — and converts it to the set of cells whose centroids are contained in `geo`.\n", + "\n", + "**Common Pitfall**: Be careful about what CRS you are using. `h3-py` expects coordinates as latitude-longitude pairs. The CRS of the current dataframe (EPSG:2263) gives coordinates in feet! You should first convert the data to something compatible. A common choice is **EPSG:4326/WGS84**. You'll get incorrect results if you apply `h3.geo_to_cells` without converting." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "83fced81-89f1-4795-84b8-c852c8c3f938", + "metadata": {}, + "outputs": [], + "source": [ + "# Original CRS\n", + "df.crs" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "dfaf3b8a-2e53-4adf-87a5-ef9fe616df32", + "metadata": {}, + "outputs": [], + "source": [ + "df.geometry[0]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "00e1026a-0a0c-448f-9223-8ce6d4d5a9a3", + "metadata": {}, + "outputs": [], + "source": [ + "# Converting to EPSG:4326/WGS84\n", + "df = df.to_crs(epsg=4326)\n", + "df.crs" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "81071108-3c13-4e10-8608-892ed3742054", + "metadata": {}, + "outputs": [], + "source": [ + "# Note that the `geometry` column now has coordinates in degrees\n", + "df" + ] + }, + { + "cell_type": "markdown", + "id": "01ca62b0-61f3-4204-bb0f-a14c9859cd4d", + "metadata": {}, + "source": [ + "## Converting a geo to H3 cells\n", + "\n", + "First, we select one of the boroughs and get the Shapely `MultiPolygon` describing it." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0be200e1-2536-4430-90ef-38dc72a75f9f", + "metadata": {}, + "outputs": [], + "source": [ + "geo = df.geometry[0]\n", + "type(geo)" + ] + }, + { + "cell_type": "markdown", + "id": "0a3c3c9c-b547-4a69-9030-fb88f486c4aa", + "metadata": {}, + "source": [ + "Note that Shapely `MultiPolygon` objects implement `__geo_interface__`, so we can use `h3.geo_to_cells()` to get the associated set of H3 cells at various resolutions." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c1a12743-b5e2-4cd1-a7fd-848e920fa928", + "metadata": {}, + "outputs": [], + "source": [ + "h3.geo_to_cells(geo, res=6)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "27d24ca5-123f-4462-b37d-bcba6acc4f64", + "metadata": {}, + "outputs": [], + "source": [ + "plot_cells(h3.geo_to_cells(geo, res=9))" + ] + }, + { + "cell_type": "markdown", + "id": "e00d088e-47b9-4bca-a8b3-d22dab747be3", + "metadata": {}, + "source": [ + "## Converting all geos in a GeoDataFrame to cells\n", + "\n", + "We can apply `geo_to_cells()` to each of the Shapely geometries in the `df.geometry` column." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f9901cc3-cd8d-4543-a8fb-98178010700e", + "metadata": {}, + "outputs": [], + "source": [ + "cell_column = df.geometry.apply(lambda x: h3.geo_to_cells(x, res=8))\n", + "cell_column" + ] + }, + { + "cell_type": "markdown", + "id": "502efd48-2c0b-4860-8796-7ea2e4e88687", + "metadata": {}, + "source": [ + "## Converting cells to \"geo objects\"\n", + "\n", + "If we assign `df.geometry = cell_column` we'll get an error because the `geometry` column of a `geopandas.GeoDataFrame` must contain valid geometry objects.\n", + "We can obtain compatible objects by converting the cells to `H3Shape` by applying `h3.cells_to_h3shape()`.\n", + "\n", + "(Note that, unfortunately, Pandas has some logic to identify iterable members of a series and then renders a tuple of the elements, rather than our preferred `H3MultiPoly.__repr__` representation.)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0c5cb00c-9796-4356-8e2a-8dc50c86103c", + "metadata": {}, + "outputs": [], + "source": [ + "shape_column = cell_column.apply(h3.cells_to_h3shape)\n", + "shape_column" + ] + }, + { + "cell_type": "markdown", + "id": "1965d53f-2bba-4840-a627-1bbf55405be3", + "metadata": {}, + "source": [ + "Note that the column now consists of `H3Poly` and `H3MultiPoly` objects." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "9b3eedce-2570-4708-992e-e6d739eecc2f", + "metadata": {}, + "outputs": [], + "source": [ + "shape_column[0]" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "014bc63d-5cfa-4a65-95e6-390ddddd1703", + "metadata": {}, + "outputs": [], + "source": [ + "shape_column[1]" + ] + }, + { + "cell_type": "markdown", + "id": "6ae6afb2-8267-492a-836e-cf371df91e89", + "metadata": {}, + "source": [ + "Now, if we assign `df.geometry = shape_column`, our `H3Shape` objects will automatically be converted to Shapely Polygon and MultiPolygon objects via `__geo_interface__`." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0c5cd4cf-226b-405f-9c36-7f1ccc09c342", + "metadata": {}, + "outputs": [], + "source": [ + "df.geometry = shape_column\n", + "df.geometry" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2608ce79-f2c5-4dbc-bf22-a28255343aea", + "metadata": {}, + "outputs": [], + "source": [ + "type(df.geometry[0])" + ] + }, + { + "cell_type": "markdown", + "id": "d568b20e-88cb-4269-99ce-dc96a73d93d1", + "metadata": {}, + "source": [ + "## Visualizing H3 cells\n", + "\n", + "We took some Shapely geometry objects, converted them to H3 cells, and converted those back to Shapely geometry objects in a `geopandas.GeoDataFrame`. \n", + "\n", + "We can visualize the results with our helper function." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "63ab3ec1-49c2-482d-8b84-154dd8196eda", + "metadata": {}, + "outputs": [], + "source": [ + "plot_df(df, column='BoroName')" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "cd012d79-a653-4d5d-bb30-408031301015", + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.1" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/makefile b/makefile index cf71860..a2f59da 100644 --- a/makefile +++ b/makefile @@ -45,5 +45,5 @@ lint: ./env/bin/pylint --disable=all --enable=import-error tests/ lab: - ./env/bin/pip install jupyterlab + ./env/bin/pip install -r requirements-dev.txt ./env/bin/jupyter lab diff --git a/requirements-dev.txt b/requirements-dev.txt new file mode 100644 index 0000000..c6ffe77 --- /dev/null +++ b/requirements-dev.txt @@ -0,0 +1,8 @@ +jupyterlab +jupyterlab-geojson +geopandas +geodatasets +matplotlib +contextily +cartopy +geoviews diff --git a/src/h3/__init__.py b/src/h3/__init__.py index 366ab02..4f7cb32 100644 --- a/src/h3/__init__.py +++ b/src/h3/__init__.py @@ -2,7 +2,6 @@ from .api.basic_str import * from ._version import __version__ -from ._polygon import Polygon from ._cy import ( UnknownH3ErrorCode, diff --git a/src/h3/_cy/CMakeLists.txt b/src/h3/_cy/CMakeLists.txt index 3cf59d5..5d392d2 100644 --- a/src/h3/_cy/CMakeLists.txt +++ b/src/h3/_cy/CMakeLists.txt @@ -18,7 +18,7 @@ endmacro() # GLOB pattern is recommended against # https://cmake.org/cmake/help/v3.14/command/file.html?highlight=file#filesystem add_cython_file(util) -add_cython_file(geo) +add_cython_file(latlng) add_cython_file(cells) add_cython_file(edges) add_cython_file(to_multipoly) @@ -33,8 +33,8 @@ install( cells.pyx edges.pxd edges.pyx - geo.pxd - geo.pyx + latlng.pxd + latlng.pyx h3lib.pxd util.pxd util.pyx diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index b3647aa..c208711 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -50,10 +50,11 @@ from .edges import ( edge_length, ) -from .geo import ( +from .latlng import ( latlng_to_cell, cell_to_latlng, polygon_to_cells, + polygons_to_cells, cell_to_boundary, directed_edge_to_boundary, great_circle_distance, diff --git a/src/h3/_cy/geo.pxd b/src/h3/_cy/latlng.pxd similarity index 100% rename from src/h3/_cy/geo.pxd rename to src/h3/_cy/latlng.pxd diff --git a/src/h3/_cy/geo.pyx b/src/h3/_cy/latlng.pyx similarity index 92% rename from src/h3/_cy/geo.pyx rename to src/h3/_cy/latlng.pyx index a606c41..520b950 100644 --- a/src/h3/_cy/geo.pyx +++ b/src/h3/_cy/latlng.pyx @@ -172,7 +172,27 @@ def polygon_to_cells(outer, int res, holes=None): return mv -def cell_to_boundary(H3int h, bool geo_json=False): +def polygons_to_cells(polygons, int res): + mvs = [ + polygon_to_cells(outer=poly.outer, res=res, holes=poly.holes) + for poly in polygons + ] + + n = sum(map(len, mvs)) + hmm = H3MemoryManager(n) + + # probably super inefficient, but it is working! + # tood: move this to C + k = 0 + for mv in mvs: + for v in mv: + hmm.ptr[k] = v + k += 1 + + return hmm.to_mv() + + +def cell_to_boundary(H3int h): """Compose an array of geo-coordinates that outlines a hexagonal cell""" cdef: h3lib.CellBoundary gb @@ -186,15 +206,10 @@ def cell_to_boundary(H3int h, bool geo_json=False): for i in range(gb.num_verts) ) - if geo_json: - #lat/lng -> lng/lat and last point same as first - verts += (verts[0],) - verts = tuple(v[::-1] for v in verts) - return verts -def directed_edge_to_boundary(H3int edge, bool geo_json=False): +def directed_edge_to_boundary(H3int edge): """ Returns the CellBoundary containing the coordinates of the edge """ cdef: @@ -210,11 +225,6 @@ def directed_edge_to_boundary(H3int edge, bool geo_json=False): for i in range(gb.num_verts) ) - if geo_json: - #lat/lng -> lng/lat and last point same as first - verts += (verts[0],) - verts = tuple(v[::-1] for v in verts) - return verts diff --git a/src/h3/_cy/to_multipoly.pyx b/src/h3/_cy/to_multipoly.pyx index d19bda8..db29baa 100644 --- a/src/h3/_cy/to_multipoly.pyx +++ b/src/h3/_cy/to_multipoly.pyx @@ -50,26 +50,11 @@ def _to_multi_polygon(const H3int[:] cells): return out -def _geojson_loop(loop): - """ Swap lat/lng order and close loop. - """ - loop = [e[::-1] for e in loop] - loop += [loop[0]] - - return loop - - -def cells_to_multi_polygon(const H3int[:] cells, geo_json=False): +def cells_to_multi_polygon(const H3int[:] cells): # todo: gotta be a more elegant way to handle these... if len(cells) == 0: return [] multipoly = _to_multi_polygon(cells) - if geo_json: - multipoly = [ - [_geojson_loop(loop) for loop in poly] - for poly in multipoly - ] - return multipoly diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py new file mode 100644 index 0000000..353887f --- /dev/null +++ b/src/h3/_h3shape.py @@ -0,0 +1,311 @@ +from abc import ABCMeta, abstractmethod + + +class H3Shape(metaclass=ABCMeta): + @property + @abstractmethod + def __geo_interface__(self): + """ https://github.com/pytest-dev/pytest-cov/issues/428 """ + + +class H3Poly(H3Shape): + """ + Container for loops of lat/lng points describing a polygon. + + Attributes + ---------- + outer : list[tuple[float, float]] + List of lat/lng points describing the outer loop of the polygon + + holes : list[list[tuple[float, float]]] + List of loops of lat/lng points describing the holes of the polygon + + Examples + -------- + + A polygon with a single outer ring consisting of 4 points, having no holes: + + >>> H3Poly( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)], + ... ) + + + The same polygon, but with one hole consisting of 3 points: + + >>> H3Poly( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)], + ... [(37.76, -122.51), (37.76, -122.44), (37.81, -122.51)], + ... ) + + + The same as above, but with one additional hole, made up of 5 points: + + >>> H3Poly( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)], + ... [(37.76, -122.51), (37.76, -122.44), (37.81, -122.51)], + ... [(37.71, -122.43), (37.71, -122.37), (37.73, -122.37), (37.75, -122.41), + ... (37.73, -122.43)], + ... ) + + """ + def __init__(self, outer, *holes): + loops = [outer] + list(holes) + for loop in loops: + if len(loop) in (1, 2): + raise ValueError('Non-empty H3Poly loops need at least 3 points.') + + self.outer = tuple(_open_ring(outer)) + self.holes = tuple( + _open_ring(hole) + for hole in holes + ) + + def __repr__(self): + return ''.format(self.loopcode) + + def __len__(self): + """ + Should this be the number of points in the outer loop, + the number of holes (or +1 for the outer loop)? + """ + raise NotImplementedError('No clear definition of length for H3Poly.') + + @property + def loopcode(self): + """ Short code for describing the length of the outer loop and each hole + + Example: `[382/(18, 6, 6)]` indicates an outer loop of 382 points, + along with 3 holes with 18, 6, and 6 points, respectively. + + Example: `[15]` indicates an outer loop of 15 points and no holes. + """ + outer = len(self.outer) + holes = tuple(map(len, self.holes)) + + outer = str(outer) + + if holes: + out = outer + '/' + str(holes) + else: + out = outer + + return '[' + out + ']' + + @property + def __geo_interface__(self): + ll2 = _polygon_to_LL2(self) + gj_dict = _LL2_to_geojson_dict(ll2) + + return gj_dict + + +class H3MultiPoly(H3Shape): + def __init__(self, *polys): + self.polys = tuple(polys) + + for p in self.polys: + if not isinstance(p, H3Poly): + raise ValueError('H3MultiPoly requires each input to be an H3Poly object, instead got: ' + str(p)) # noqa + + def __repr__(self): + out = [p.loopcode for p in self.polys] + out = ', '.join(out) + out = ''.format(out) + return out + + def __iter__(self): + return iter(self.polys) + + def __len__(self): + """ Give the number of polygons in this multi-polygon. + """ + + """ + TODO: Pandas series or dataframe representation changes depending + on if __len__ is defined. + + I'd prefer the one that states `H3MultiPoly`. It seems like Pandas is assuming + an iterable is best-described by its elements when choosing the representation. + + when __len__ *IS NOT* defined: + + 0 + 1 , , ) + 1 (, , , , , , <... + """ + return len(self.polys) + + def __getitem__(self, index): + return self.polys[index] + + @property + def __geo_interface__(self): + ll3 = _mpoly_to_LL3(self) + gj_dict = _LL3_to_geojson_dict(ll3) + + return gj_dict + + +""" +Helpers for cells_to_geojson and geojson_to_cells. + +Dealing with GeoJSON Polygons and MultiPolygons can be confusing because +there are so many nested lists. To help keep track, we use the following +symbols to denote different levels of nesting. + +LL0: lat/lng or lng/lat pair +LL1: list of LL0s +LL2: list of LL1s (i.e., a polygon with holes) +LL3: list of LL2s (i.e., several polygons with holes) + + +## TODO + +- Allow user to specify "container" in `cells_to_geojson`. + - That is, they may want a MultiPolygon even if the output fits in a Polygon + - 'auto', Polygon, MultiPolygon, FeatureCollection, GeometryCollection, ... +""" + + +def _mpoly_to_LL3(mpoly): + ll3 = tuple( + _polygon_to_LL2(poly) + for poly in mpoly + ) + + return ll3 + + +def _LL3_to_mpoly(ll3): + polys = [ + _LL2_to_polygon(ll2) + for ll2 in ll3 + ] + + mpoly = H3MultiPoly(*polys) + + return mpoly + + +def _polygon_to_LL2(h3poly): + ll2 = [h3poly.outer] + list(h3poly.holes) + ll2 = tuple( + _close_ring(_swap_latlng(ll1)) + for ll1 in ll2 + ) + + return ll2 + + +def _LL2_to_polygon(ll2): + ll2 = [ + _swap_latlng(ll1) + for ll1 in ll2 + ] + h3poly = H3Poly(*ll2) + + return h3poly + + +def _LL2_to_geojson_dict(ll2): + gj_dict = { + 'type': 'Polygon', + 'coordinates': ll2, + } + + return gj_dict + + +def _LL3_to_geojson_dict(ll3): + gj_dict = { + 'type': 'MultiPolygon', + 'coordinates': ll3, + } + + return gj_dict + + +def _swap_latlng(ll1): + ll1 = tuple( + (b, a) for a, b in ll1 + ) + return ll1 + + +def _close_ring(ll1): + """ + Idempotent + """ + if ll1 and (ll1[0] != ll1[-1]): + ll1 = tuple(ll1) + (ll1[0],) + + return ll1 + + +def _open_ring(ll1): + """ + Idempotent + """ + if ll1 and (ll1[0] == ll1[-1]): + ll1 = ll1[:-1] + + return ll1 + + +def geo_to_h3shape(geo): + """ + Translate from __geo_interface__ to H3Shape. + + `geo` either implements `__geo_interface__` or is a dict matching the format + + Returns + ------- + H3Shape + """ + + # geo can be dict, a __geo_interface__, a string, H3Poly or H3MultiPoly + if isinstance(geo, H3Shape): + return geo + + if hasattr(geo, '__geo_interface__'): + # get dict + geo = geo.__geo_interface__ + + assert isinstance(geo, dict) # todo: remove + + t = geo['type'] + coord = geo['coordinates'] + + if t == 'Polygon': + ll2 = coord + h3shape = _LL2_to_polygon(ll2) + elif t == 'MultiPolygon': + ll3 = coord + h3shape = _LL3_to_mpoly(ll3) + else: + raise ValueError('Unrecognized type: ' + str(t)) + + return h3shape + + +def h3shape_to_geo(h3shape): + """ + Translate from H3Shape to a __geo_interface__ dict. + + `h3shape` should be either H3Poly or H3MultiPoly + + Returns + ------- + dict + """ + return h3shape.__geo_interface__ diff --git a/src/h3/_polygon.py b/src/h3/_polygon.py deleted file mode 100644 index c36c569..0000000 --- a/src/h3/_polygon.py +++ /dev/null @@ -1,56 +0,0 @@ -class Polygon: - """ - Container for loops of lat/lng points describing a polygon. - - Attributes - ---------- - outer : list[tuple[float, float]] - List of lat/lng points describing the outer loop of the Polygon - - holes : list[list[tuple[float, float]]] - List of loops of lat/lng points describing the holes of the Polygon - - Examples - -------- - - A polygon with a single outer ring consisting of 4 points, having no holes: - - >>> h3.Polygon( - ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)], - ... ) - - - The same polygon, but with one hole consisting of 3 points: - - >>> h3.Polygon( - ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)], - ... [(37.76, -122.51), (37.76, -122.44), (37.81, -122.51)], - ... ) - - - The same as above, but with one additional hole, made up of 5 points: - - >>> h3.Polygon( - ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)], - ... [(37.76, -122.51), (37.76, -122.44), (37.81, -122.51)], - ... [(37.71, -122.43), (37.71, -122.37), (37.73, -122.37), (37.75, -122.41), - ... (37.73, -122.43)], - ... ) - - - Notes - ----- - - - TODO: Add GeoJSON translation support. - """ - def __init__(self, outer, *holes): - self.outer = outer - self.holes = holes - - def __repr__(self): - s = ''.format( - len(self.outer), - tuple(map(len, self.holes)), - ) - - return s diff --git a/src/h3/api/_api_template.py b/src/h3/api/_api_template.py index ea49092..1b7fd0d 100644 --- a/src/h3/api/_api_template.py +++ b/src/h3/api/_api_template.py @@ -38,7 +38,12 @@ be skipped due to it being inside the `_api_functions` function. """ from .. import _cy -from .._polygon import Polygon +from .._h3shape import ( + H3Poly, + H3MultiPoly, + geo_to_h3shape, + h3shape_to_geo, +) class _API_FUNCTIONS(object): @@ -272,25 +277,19 @@ class _API_FUNCTIONS(object): return d - def cell_to_boundary(self, h, geo_json=False): + def cell_to_boundary(self, h): """ Return tuple of lat/lng pairs describing the cell boundary. Parameters ---------- h : H3Cell - geo_json : bool, optional - If ``True``, return output in GeoJson format: - lng/lat pairs (opposite order), and - have the last pair be the same as the first. - If ``False`` (default), return lat/lng pairs, with the last - pair distinct from the first. Returns ------- - tuple of (float, float) tuples + tuple of (lat, lng) tuples """ - return _cy.cell_to_boundary(self._in_scalar(h), geo_json) + return _cy.cell_to_boundary(self._in_scalar(h)) def grid_disk(self, h, k=1): """ @@ -397,27 +396,29 @@ class _API_FUNCTIONS(object): return self._out_unordered(hu) - def polygon_to_cells(self, polygon, res): + def h3shape_to_cells(self, h3shape, res): """ Return the set of H3 cells at a given resolution whose center points - are contained within a `h3.Polygon` + are contained within an `H3Poly` or `H3MultiPoly`. Parameters ---------- - Polygon : h3.Polygon - A polygon described by an outer ring and optional holes - + h3shape : H3shape res : int Resolution of the output cells + Returns + ------- + unordered collection of H3Cell + Examples -------- - >>> poly = h3.Polygon( + >>> poly = H3Poly( ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), ... (37.82, -122.54)], ... ) - >>> h3.polygon_to_cells(poly, 6) + >>> h3.h3shape_to_cells(poly, 6) {'862830807ffffff', '862830827ffffff', '86283082fffffff', @@ -426,43 +427,79 @@ class _API_FUNCTIONS(object): '862830957ffffff', '86283095fffffff'} """ - mv = _cy.polygon_to_cells(polygon.outer, res, holes=polygon.holes) + + # todo: not sure if i want this dispatch logic here. maybe in the objects? + if isinstance(h3shape, H3Poly): + poly = h3shape + mv = _cy.polygon_to_cells(poly.outer, res, holes=poly.holes) + elif isinstance(h3shape, H3MultiPoly): + mpoly = h3shape + mv = _cy.polygons_to_cells(mpoly.polys, res) + else: + raise ValueError('Unrecognized type: ' + str(type(h3shape))) return self._out_unordered(mv) - # def polygons_to_cells(self, polygons, res): - # # todo: have to figure out how to concat memoryviews cleanly - # # or some other approach - # pass - - def cells_to_polygons(self, cells): + def cells_to_h3shape(self, cells, tight=True): """ - Return a list of h3.Polygon objects describing the area - covered by a set of H3 cells. + Return a H3MultiPoly describing the area covered by a set of H3 cells. Parameters ---------- cells : iterable of H3 cells + tight : bool + If True, return H3Poly if possible. If False, always return H3MultiPoly Returns ------- - list[h3.Polygon] - List of h3.Polygon objects + H3Poly | H3MultiPoly Examples -------- >>> cells = ['8428309ffffffff', '842830dffffffff'] - >>> h3.cells_to_polygons(cells) - [] - + >>> h3.cells_to_h3shape(cells, tight=True) + + >>> h3.cells_to_h3shape(cells, tight=False) + """ cells = self._in_collection(cells) - geos = _cy.cells_to_multi_polygon(cells) + mpoly = _cy.cells_to_multi_polygon(cells) - polys = [Polygon(*geo) for geo in geos] + polys = [H3Poly(*poly) for poly in mpoly] + out = H3MultiPoly(*polys) - return polys + if tight and len(out) == 1: + out = out[0] + + return out + + def geo_to_cells(self, geo, res): + """ Convert from __geo_interface__ to cells. + + Parameters + ---------- + geo : an object implementing `__geo_interface__` or a dictionary in that format. + Both H3Poly and H3MultiPoly implement the interface. + res : int + Resolution of desired output cells. + """ + h3shape = geo_to_h3shape(geo) + return self.h3shape_to_cells(h3shape, res) + + def cells_to_geo(self, cells, tight=True): + """ + Parameters + ---------- + cells : iterable of H3 Cells + + Returns + ------- + dict + in `__geo_interface__` format + """ + h3shape = self.cells_to_h3shape(cells, tight=tight) + return h3shape_to_geo(h3shape) def is_pentagon(self, h): """ @@ -625,8 +662,8 @@ class _API_FUNCTIONS(object): return self._out_unordered(mv) - def directed_edge_to_boundary(self, edge, geo_json=False): - return _cy.directed_edge_to_boundary(self._in_scalar(edge), geo_json=geo_json) + def directed_edge_to_boundary(self, edge): + return _cy.directed_edge_to_boundary(self._in_scalar(edge)) def grid_path_cells(self, start, end): """ diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index 977b40b..a297461 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -1 +1,9 @@ -from ._public_api import * # noqa +# flake8: noqa +from ._public_api import * +from ..._h3shape import ( + H3MultiPoly, + H3Poly, + H3Shape, + geo_to_h3shape, + h3shape_to_geo, +) diff --git a/src/h3/api/basic_int/_public_api.py b/src/h3/api/basic_int/_public_api.py index 6f1b552..8e87df1 100644 --- a/src/h3/api/basic_int/_public_api.py +++ b/src/h3/api/basic_int/_public_api.py @@ -47,8 +47,10 @@ cell_to_center_child = _b.cell_to_center_child compact_cells = _b.compact_cells uncompact_cells = _b.uncompact_cells -polygon_to_cells = _b.polygon_to_cells -cells_to_polygons = _b.cells_to_polygons +h3shape_to_cells = _b.h3shape_to_cells +cells_to_h3shape = _b.cells_to_h3shape +cells_to_geo = _b.cells_to_geo +geo_to_cells = _b.geo_to_cells are_neighbor_cells = _b.are_neighbor_cells cells_to_directed_edge = _b.cells_to_directed_edge diff --git a/src/h3/api/basic_str/__init__.py b/src/h3/api/basic_str/__init__.py index 977b40b..a297461 100644 --- a/src/h3/api/basic_str/__init__.py +++ b/src/h3/api/basic_str/__init__.py @@ -1 +1,9 @@ -from ._public_api import * # noqa +# flake8: noqa +from ._public_api import * +from ..._h3shape import ( + H3MultiPoly, + H3Poly, + H3Shape, + geo_to_h3shape, + h3shape_to_geo, +) diff --git a/src/h3/api/memview_int/__init__.py b/src/h3/api/memview_int/__init__.py index 977b40b..a297461 100644 --- a/src/h3/api/memview_int/__init__.py +++ b/src/h3/api/memview_int/__init__.py @@ -1 +1,9 @@ -from ._public_api import * # noqa +# flake8: noqa +from ._public_api import * +from ..._h3shape import ( + H3MultiPoly, + H3Poly, + H3Shape, + geo_to_h3shape, + h3shape_to_geo, +) diff --git a/src/h3/api/numpy_int/__init__.py b/src/h3/api/numpy_int/__init__.py index 977b40b..a297461 100644 --- a/src/h3/api/numpy_int/__init__.py +++ b/src/h3/api/numpy_int/__init__.py @@ -1 +1,9 @@ -from ._public_api import * # noqa +# flake8: noqa +from ._public_api import * +from ..._h3shape import ( + H3MultiPoly, + H3Poly, + H3Shape, + geo_to_h3shape, + h3shape_to_geo, +) diff --git a/tests/cython_example.pyx b/tests/cython_example.pyx index 8e58d2c..0185f76 100644 --- a/tests/cython_example.pyx +++ b/tests/cython_example.pyx @@ -2,7 +2,7 @@ from cython cimport boundscheck, wraparound from h3._cy.h3lib cimport H3int -from h3._cy.geo cimport latlng_to_cell +from h3._cy.latlng cimport latlng_to_cell @boundscheck(False) @wraparound(False) diff --git a/tests/polyfill/test_h3.py b/tests/polyfill/test_h3.py new file mode 100644 index 0000000..c38ff5f --- /dev/null +++ b/tests/polyfill/test_h3.py @@ -0,0 +1,379 @@ +import h3 +import pytest + + +class MockGeoInterface: + def __init__(self, dictionary): + assert isinstance(dictionary, dict) + self.dictionary = dictionary + + @property + def __geo_interface__(self): + return self.dictionary + + +def latlng_open(): + return [ + [37.813, -122.408], + [37.707, -122.512], + [37.815, -122.479], + ] + + +def latlng_closed(): + loop = latlng_open() + return loop + [loop[0]] + + +def swap_latlng(ll1): + ll1 = tuple( + (b, a) for a, b in ll1 + ) + return ll1 + + +def lnglat_open(): + return swap_latlng(latlng_open()) + + +def lnglat_closed(): + return swap_latlng(latlng_closed()) + + +def get_mocked(loop): + geo = MockGeoInterface({ + 'type': 'Polygon', + 'coordinates': [loop] + }) + + return geo + + +sf_7x7 = [ + (37.813319, -122.408987), + (37.786630, -122.380544), + (37.719806, -122.354474), + (37.707613, -122.512344), + (37.783587, -122.524719), + (37.815157, -122.479877), +] + +sf_hole1 = [ + (37.786980, -122.447120), + (37.766410, -122.459078), + (37.771068, -122.413710), +] + +sf_hole2 = [ + (37.747976, -122.490025), + (37.731550, -122.503758), + (37.725440, -122.452603), +] + + +def test_geo_interface(): + poly = h3.H3Poly(sf_hole1) + mpoly = h3.H3MultiPoly(poly) + + assert poly.__geo_interface__['type'] == 'Polygon' + assert mpoly.__geo_interface__['type'] == 'MultiPolygon' + + assert ( + poly.__geo_interface__['coordinates'] + == + mpoly.__geo_interface__['coordinates'][0] + ) + + +def test_shape_repr(): + poly = h3.H3Poly(sf_hole1) + mpoly = h3.H3MultiPoly(poly) + + assert ( + '' + == str(mpoly) + == repr(mpoly) + ) + + +def test_polyfill(): + poly = h3.H3Poly(sf_7x7) + out = h3.h3shape_to_cells(poly, res=9) + + assert len(out) == 1253 + assert '89283080527ffff' in out + assert '89283095edbffff' in out + + +def test_polyfill_with_hole(): + poly = h3.H3Poly(sf_7x7, sf_hole1) + + out = h3.h3shape_to_cells(poly, res=9) + assert len(out) == 1214 + + foo = lambda x: h3.h3shape_to_cells(h3.H3Poly(x), 9) + # todo: foo = lambda x: h3.H3Poly(x).to_cells(9) + assert out == foo(sf_7x7) - foo(sf_hole1) + + +def test_polyfill_with_two_holes(): + + poly = h3.H3Poly(sf_7x7, sf_hole1, sf_hole2) + out = h3.h3shape_to_cells(poly, 9) + assert len(out) == 1172 + + foo = lambda x: h3.h3shape_to_cells(h3.H3Poly(x), 9) + assert out == foo(sf_7x7) - (foo(sf_hole1) | foo(sf_hole2)) + + +def test_polyfill_geo_json_compliant(): + geo = get_mocked(lnglat_open()).__geo_interface__ + out = h3.geo_to_cells(geo, 9) + assert len(out) > 300 + + +def test_polyfill_geo_interface_compliant(): + geo = get_mocked(lnglat_open()) + out = h3.geo_to_cells(geo, 9) + assert len(out) > 300 + + +def test_poly_opens_loop(): + loop = lnglat_closed() + poly = h3.H3Poly(loop) + + assert loop[0] == loop[-1] + assert len(poly.outer) == len(loop) - 1 + + +def test_geo_to_h3shape(): + h3shapes = [ + h3.geo_to_h3shape(get_mocked(lnglat_open())), + h3.geo_to_h3shape(get_mocked(lnglat_closed())), + h3.H3Poly(latlng_open()), + h3.H3Poly(latlng_closed()), + ] + + for s in h3shapes: + assert len(h3.h3shape_to_cells(s, 8)) == 48 + + expected = { + 'type': 'Polygon', + 'coordinates': (( + (-122.408, 37.813), + (-122.512, 37.707), + (-122.479, 37.815), + (-122.408, 37.813), + ),) + } + + for shape in h3shapes: + assert shape.__geo_interface__ == expected + + mpolys = map(h3.H3MultiPoly, h3shapes) + + multi_expected = { + 'type': 'MultiPolygon', + 'coordinates': ((( + (-122.408, 37.813), + (-122.512, 37.707), + (-122.479, 37.815), + (-122.408, 37.813), + ),),) + } + + for mp in mpolys: + assert mp.__geo_interface__ == multi_expected + + +def test_geo_to_h3shape_passthrough(): + poly = h3.H3Poly(latlng_open()) + mpoly = h3.H3MultiPoly(poly) + + for shape in [poly, mpoly]: + assert h3.geo_to_h3shape(shape) is shape + + +def test_polyfill_down_under(): + sydney = [ + (-33.8556, 151.1979), + (-33.8520, 151.2075), + (-33.8580, 151.2247), + (-33.8582, 151.2255), + (-33.8564, 151.2353), + (-33.8594, 151.2348), + (-33.8641, 151.2335), + (-33.8716, 151.2332), + (-33.8877, 151.2240), + (-33.8874, 151.2194), + (-33.8870, 151.2189), + (-33.8863, 151.2181), + (-33.8851, 151.2158), + (-33.8852, 151.2157), + (-33.8851, 151.2141), + (-33.8847, 151.2116), + (-33.8835, 151.2083), + (-33.8828, 151.2080), + (-33.8816, 151.2059), + (-33.8828, 151.2044), + (-33.8839, 151.2028), + (-33.8839, 151.2023), + (-33.8842, 151.2011), + (-33.8843, 151.1986), + (-33.8842, 151.1986), + (-33.8773, 151.1948), + (-33.8741, 151.1923), + (-33.8697, 151.1851), + (-33.8625, 151.1903), + (-33.8613, 151.1987), + (-33.8556, 151.1979), + ] + + poly = h3.H3Poly(sydney) + out = h3.h3shape_to_cells(poly, 9) + assert len(out) == 92 + assert '89be0e34207ffff' in out + assert '89be0e35ddbffff' in out + + +def test_polyfill_far_east(): + geo = [ + (41.925781, 142.864838), + (42.299659, 142.864838), + (42.299659, 143.415527), + (41.925781, 143.415527), + (41.925781, 142.864838), + ] + + poly = h3.H3Poly(geo) + out = h3.h3shape_to_cells(poly, 9) + assert len(out) == 18507 + assert '892e18d16c3ffff' in out + assert '892e1ebb5a7ffff' in out + + +def test_polyfill_southern_tip(): + geo = [ + (-55.416544, -67.642822), + (-54.354956, -67.642822), + (-54.354956, -64.742432), + (-55.416544, -64.742432), + (-55.416544, -67.642822), + ] + + poly = h3.H3Poly(geo) + out = h3.h3shape_to_cells(poly, 9) + assert len(out) == 223247 + assert '89df4000003ffff' in out + assert '89df4636b27ffff' in out + + +def test_polyfill_null_island(): + geo = [ + (-3, -3), + (+3, -3), + (+3, +3), + (-3, +3), + (-3, -3), + ] + + poly = h3.H3Poly(geo) + out = h3.h3shape_to_cells(poly, 4) + assert len(out) == 345 + assert '847421bffffffff' in out + assert '84825ddffffffff' in out + + +def test_cells_to_h3shape_empty(): + mpoly = h3.cells_to_h3shape([]) + assert list(mpoly) == [] + + +def test_cells_to_h3shape_single(): + h = '89283082837ffff' + cells = {h} + + mpoly = h3.cells_to_h3shape(cells, tight=False) + assert len(mpoly) == 1 + poly = mpoly[0] + + vertices = h3.cell_to_boundary(h) + expected_poly = h3.H3Poly(vertices) + + assert set(poly.outer) == set(expected_poly.outer) + assert poly.holes == expected_poly.holes == () + + +def test_cells_to_h3shape_contiguous(): + a = '89283082837ffff' + b = '89283082833ffff' + assert h3.are_neighbor_cells(a, b) + + mpoly = h3.cells_to_h3shape([a, b], tight=False) + assert len(mpoly) == 1 + poly = mpoly[0] + + assert len(poly.outer) == 10 + assert poly.holes == () + + verts_a = h3.cell_to_boundary(a) + verts_b = h3.cell_to_boundary(b) + assert set(poly.outer) == set(verts_a) | set(verts_b) + + +def test_cells_to_h3shape_non_contiguous(): + a = '89283082837ffff' + b = '8928308280fffff' + assert not h3.are_neighbor_cells(a, b) + + mpoly = h3.cells_to_h3shape([a, b]) + assert len(mpoly) == 2 + + assert all(poly.holes == () for poly in mpoly) + assert all(len(poly.outer) == 6 for poly in mpoly) + + verts_a = h3.cell_to_boundary(a) + verts_b = h3.cell_to_boundary(b) + + verts_both = set.union(*[set(poly.outer) for poly in mpoly]) + assert verts_both == set(verts_a) | set(verts_b) + + +def test_cells_to_h3shape_hole(): + # Six hexagons in a ring around a hole + cells = [ + '892830828c7ffff', '892830828d7ffff', '8928308289bffff', + '89283082813ffff', '8928308288fffff', '89283082883ffff', + ] + mpoly = h3.cells_to_h3shape(cells, tight=False) + + assert len(mpoly) == 1 + poly = mpoly[0] + + assert len(poly.holes) == 1 + assert len(poly.holes[0]) == 6 + assert len(poly.outer) == 6 * 3 + + +def test_cells_to_h3shape_2grid_disk(): + h = '8930062838bffff' + cells = h3.grid_disk(h, 2) + mpoly = h3.cells_to_h3shape(cells, tight=False) + + assert len(mpoly) == 1 + poly = mpoly[0] + + assert len(poly.holes) == 0 + assert len(poly.outer) == 6 * (2 * 2 + 1) + + +def test_multipoly_checks(): + + with pytest.raises(ValueError): + h3.H3MultiPoly('foo') + + with pytest.raises(ValueError): + h3.H3MultiPoly(1) + + with pytest.raises(ValueError): + h3.H3MultiPoly([[(1, 2), (3, 4)]]) diff --git a/tests/polyfill/test_polyfill.py b/tests/polyfill/test_polyfill.py new file mode 100644 index 0000000..7b059eb --- /dev/null +++ b/tests/polyfill/test_polyfill.py @@ -0,0 +1,161 @@ +import h3 +import pytest + +from h3 import H3ResDomainError + + +def get_us_box_coords(): + + # big center chunk of the US in lat/lng order + outer = [ + [42.68, -110.61], + [32.17, -109.02], + [31.57, -94.26], + [42.94, -89.38], + [42.68, -110.61] + ] + + hole1 = [ + [39.77, -105.07], + [34.81, -104.72], + [34.77, -98.39], + [40.14, -96.72], + [39.77, -105.07] + ] + + hole2 = [ + [41.37, -98.61], + [40.04, -91.80], + [42.32, -91.80], + [41.37, -98.61] + ] + + return outer, hole1, hole2 + + +def test_h3shape_to_cells(): + + # approximate lat/lngs for State of Maine + maine = [ + (45.137, -67.137), + (44.810, -66.965), + (44.325, -68.033), + (43.980, -69.060), + (43.684, -70.116), + (43.090, -70.646), + (43.080, -70.751), + (43.220, -70.798), + (43.368, -70.982), + (43.466, -70.944), + (45.305, -71.085), + (45.460, -70.660), + (45.915, -70.305), + (46.693, -70.000), + (47.448, -69.237), + (47.185, -68.905), + (47.355, -68.234), + (47.066, -67.790), + (45.703, -67.791), + (45.137, -67.137), + ] + + # a very rough hexagonal approximation to the State of Maine + expected = { + '832b13fffffffff', + '832b18fffffffff', + '832b1afffffffff', + '832b1efffffffff', + '832ba9fffffffff', + '832badfffffffff' + } + + poly = h3.H3Poly(maine) + out = h3.h3shape_to_cells(poly, 3) + + assert out == expected + + +def test_h3shape_to_cells2(): + lnglat, _, _ = get_us_box_coords() + + poly = h3.H3Poly(lnglat) + out = h3.h3shape_to_cells(poly, 5) + + assert len(out) == 7063 + + +# todo: we can generate segfaults with malformed input data to polyfill +# need to test for this and avoid segfault +# def test_polyfill_segfault(): +# pass + + +def test_h3shape_to_cells_holes(): + + outer, hole1, hole2 = get_us_box_coords() + + assert 7063 == len( + h3.h3shape_to_cells(h3.H3Poly(outer), 5) + ) + + for res in 1, 2, 3, 4, 5: + cells_all = h3.h3shape_to_cells(h3.H3Poly(outer), res) + cells_holes = h3.h3shape_to_cells(h3.H3Poly(outer, hole1, hole2), res=res) + + cells_1 = h3.h3shape_to_cells(h3.H3Poly(hole1), res) + cells_2 = h3.h3shape_to_cells(h3.H3Poly(hole2), res) + + assert len(cells_all) == len(cells_holes) + len(cells_1) + len(cells_2) + assert cells_all == set.union(cells_holes, cells_1, cells_2) + + +def test_resolution(): + poly = h3.H3Poly([]) + + assert h3.h3shape_to_cells(poly, 0) == set() + assert h3.h3shape_to_cells(poly, 15) == set() + + with pytest.raises(H3ResDomainError): + h3.h3shape_to_cells(poly, -1) + + with pytest.raises(H3ResDomainError): + h3.h3shape_to_cells(poly, 16) + + +def test_invalid_polygon(): + """ + We were previously seeing segfaults on data like + this because we weren't raising errors inside + some `cdef` functions. + """ + with pytest.raises(TypeError): + poly = h3.H3Poly([1, 2, 3]) + h3.h3shape_to_cells(poly, 4) + + with pytest.raises(ValueError): + poly = h3.H3Poly([[1, 2, 3]]) + h3.h3shape_to_cells(poly, 4) + + +def test_bad_geo_input(): + with pytest.raises(ValueError): + h3.h3shape_to_cells('not a shape', 9) + + with pytest.raises(ValueError): + h3.geo_to_cells({'type': 'not a shape', 'coordinates': None}, 9) + + +def test_cells_to_geo(): + h = '89754e64993ffff' + res = h3.get_resolution(h) + + geo = h3.cells_to_geo([h], tight=False) + coord = geo['coordinates'] + + assert geo['type'] == 'MultiPolygon' # todo: TBD + assert len(coord) == 1 + coord = coord[0] + assert len(coord[0]) == 7 + assert coord[0][0] == coord[0][-1] + + assert h3.geo_to_cells(geo, res) == {h} diff --git a/tests/polyfill/test_polyfill_ordering.py b/tests/polyfill/test_polyfill_ordering.py new file mode 100644 index 0000000..0206138 --- /dev/null +++ b/tests/polyfill/test_polyfill_ordering.py @@ -0,0 +1,96 @@ +""" Test that `h3shape_to_cells` can take in polygon inputs +where the LinearRings may or may not follow the right hand rule, +and they may or may not be closed loops (where the last element +is equal to the first). + +Test all permutations of these rules on polygons with +0, 1, and 2 holes. Ensure that for any polygon, each LinearRing +may follow a different subset of rules. +""" + +import h3 +import itertools + + +def reverse(loop): + return list(reversed(loop)) + + +def drop_last(loop): + return loop[:-1] + + +def toggle_map(func, poly): + """ Return all permutations of `func` being applied or not + to each element of `poly` + + returns iterable of length 2**len(poly) + """ + mapped = (list(func(loop)) for loop in poly) + + return itertools.product(*zip(poly, mapped)) + + +def chain_toggle_map(func, seq): + seq = (toggle_map(func, p) for p in seq) + seq = itertools.chain(*seq) + + return seq + + +def input_permutations(geo, res=5): + g = [geo] + g = chain_toggle_map(drop_last, g) + g = chain_toggle_map(reverse, g) + + for p in g: + poly = h3.H3Poly(*p) + cells = h3.h3shape_to_cells(poly, res=res) + yield cells + + +def get_us_box_coords(): + + # big center chunk of the US in lat/lng order + outer = [ + [42.68, -110.61], + [32.17, -109.02], + [31.57, -94.26], + [42.94, -89.38], + [42.68, -110.61] + ] + + hole1 = [ + [39.77, -105.07], + [34.81, -104.72], + [34.77, -98.39], + [40.14, -96.72], + [39.77, -105.07] + ] + + hole2 = [ + [41.37, -98.61], + [40.04, -91.80], + [42.32, -91.80], + [41.37, -98.61] + ] + + return outer, hole1, hole2 + + +def test_input_format(): + geo = get_us_box_coords() + + assert len(geo) == 3 + + # two holes + for cells in input_permutations(geo[:3]): + assert len(cells) == 5437 + + # one hole + for cells in input_permutations(geo[:2]): + assert len(cells) == 5726 + + # zero holes + for cells in input_permutations(geo[:1]): + assert len(cells) == 7063 diff --git a/tests/polyfill/test_polygon_class.py b/tests/polyfill/test_polygon_class.py new file mode 100644 index 0000000..721eb75 --- /dev/null +++ b/tests/polyfill/test_polygon_class.py @@ -0,0 +1,37 @@ +import h3 +import pytest + + +def test_repr(): + a = '8928308280fffff' + b = h3.grid_ring(a, 5).pop() + + cells1 = h3.grid_ring(b, 2) | {a} + cells2 = cells1 | {b} + + mpoly1 = h3.cells_to_h3shape(cells1) + mpoly2 = h3.cells_to_h3shape(cells2) + + # unfortunately output order is nondeterministic + mpoly1 = sorted(map(str, mpoly1)) + mpoly2 = sorted(map(str, mpoly2)) + + assert mpoly1 == [ + '', + '', + ] + + assert mpoly2 == [ + '', + '', + '', + ] + + +def test_h3poly_len(): + cells = {'8928308280fffff'} + + poly = h3.cells_to_h3shape(cells, tight=True) + + with pytest.raises(NotImplementedError): + len(poly) diff --git a/tests/polyfill/test_to_multipoly.py b/tests/polyfill/test_to_multipoly.py new file mode 100644 index 0000000..e613d4d --- /dev/null +++ b/tests/polyfill/test_to_multipoly.py @@ -0,0 +1,43 @@ +import h3 + + +def test_cells_to_h3shape(): + h = '8928308280fffff' + cells = h3.grid_disk(h, 1) + + mpoly = h3.cells_to_h3shape(cells, tight=False) + poly = mpoly[0] + + poly2 = h3.H3Poly(poly.outer, *poly.holes) + out = h3.h3shape_to_cells(poly2, 9) + + assert out == cells + + +def test_cells_to_h3shape_tight(): + h = '8928308280fffff' + cells = h3.grid_disk(h, 1) + + poly = h3.cells_to_h3shape(cells, tight=True) + poly2 = h3.H3Poly(poly.outer, *poly.holes) + out = h3.h3shape_to_cells(poly2, 9) + + assert out == cells + + +def test_2_polys(): + h = '8928308280fffff' + cells = h3.grid_ring(h, 2) + cells = cells | {h} + # cells should be a center hex, and the 2-ring around it + # (with the 1-ring being absent) + + mpoly = h3.cells_to_h3shape(cells) + + out = [ + h3.h3shape_to_cells(poly, 9) + for poly in mpoly + ] + + assert set.union(*out) == cells + assert set(map(len, out)) == {1, 12} diff --git a/tests/test_cells_and_edges.py b/tests/test_cells_and_edges.py index 4746569..c82c6ab 100644 --- a/tests/test_cells_and_edges.py +++ b/tests/test_cells_and_edges.py @@ -47,21 +47,6 @@ def test3(): assert approx2(out, expected) -def test4(): - expected = ( - (-122.41719971841658, 37.775197782893386), - (-122.41612835779264, 37.77688044840226), - (-122.4173879761762, 37.778385004930925), - (-122.41971895414807, 37.77820687262238), - (-122.42079024541877, 37.77652420699321), - (-122.4195306280734, 37.775019673792606), - (-122.41719971841658, 37.775197782893386) - ) - - out = h3.cell_to_boundary('8928308280fffff', geo_json=True) - assert approx2(out, expected) - - def test_grid_disk_distance(): with pytest.raises(H3DomainError): h3.grid_disk('8928308280fffff', -10) @@ -228,10 +213,9 @@ def test_distance_error(): h3.grid_distance(h1, h2) -def test_compact_cells(): - +def get_maine_cells(): # lat/lngs for State of Maine - maine = h3.Polygon([ + poly = h3.H3Poly([ (45.137451890638886, -67.13734351262877), (44.8097, -66.96466), (44.3252, -68.03252), @@ -255,23 +239,25 @@ def test_compact_cells(): ]) res = 5 - h_uncomp = h3.polygon_to_cells(maine, res=res) - h_comp = h3.compact_cells(h_uncomp) + cells_uncomp = h3.h3shape_to_cells(poly, res=res) - expected = {'852b114ffffffff', '852b189bfffffff', '852b1163fffffff', '842ba9bffffffff', '842bad3ffffffff', '852ba9cffffffff', '842badbffffffff', '852b1e8bfffffff', '852a346ffffffff', '842b1e3ffffffff', '852b116ffffffff', '842b185ffffffff', '852b1bdbfffffff', '852bad47fffffff', '852ba9c3fffffff', '852b106bfffffff', '852a30d3fffffff', '842b1edffffffff', '852b12a7fffffff', '852b1027fffffff', '842baddffffffff', '852a349bfffffff', '852b1227fffffff', '852a3473fffffff', '852b117bfffffff', '842ba99ffffffff', '852a341bfffffff', '852ba9d3fffffff', '852b1067fffffff', '852a3463fffffff', '852baca7fffffff', '852b116bfffffff', '852b1c6bfffffff', '852a3493fffffff', '852ba9dbfffffff', '852b180bfffffff', '842bad7ffffffff', '852b1063fffffff', '842ba93ffffffff', '852a3693fffffff', '852ba977fffffff', '852b1e9bfffffff', '852bad53fffffff', '852b100ffffffff', '852b102bfffffff', '852a3413fffffff', '852ba8b7fffffff', '852bad43fffffff', '852b1c6ffffffff', '852a340bfffffff', '852b103bfffffff', '852b1813fffffff', '852b12affffffff', '842a34dffffffff', '852b1873fffffff', '852b106ffffffff', '852b115bfffffff', '852baca3fffffff', '852b114bfffffff', '852b1143fffffff', '852a348bfffffff', '852a30d7fffffff', '852b181bfffffff', '842a345ffffffff', '852b1e8ffffffff', '852b1883fffffff', '852b1147fffffff', '852a3483fffffff', '852b12a3fffffff', '852a346bfffffff', '852ba9d7fffffff', '842b18dffffffff', '852b188bfffffff', '852a36a7fffffff', '852bacb3fffffff', '852b187bfffffff', '852bacb7fffffff', '842b1ebffffffff', '842b1e5ffffffff', '852ba8a7fffffff', '842bad9ffffffff', '852a36b7fffffff', '852a347bfffffff', '832b13fffffffff', '852ba9c7fffffff', '832b1afffffffff', '842ba91ffffffff', '852bad57fffffff', '852ba8affffffff', '852b1803fffffff', '842b1e7ffffffff', '852bad4ffffffff', '852b102ffffffff', '852b1077fffffff', '852b1237fffffff', '852b1153fffffff', '852a3697fffffff', '852a36b3fffffff', '842bad1ffffffff', '842b1e1ffffffff', '852b186bfffffff', '852b1023fffffff'} # noqa + # the expected result from h3.compact_cells(cells_uncomp) + cells_comp = {'852b114ffffffff', '852b189bfffffff', '852b1163fffffff', '842ba9bffffffff', '842bad3ffffffff', '852ba9cffffffff', '842badbffffffff', '852b1e8bfffffff', '852a346ffffffff', '842b1e3ffffffff', '852b116ffffffff', '842b185ffffffff', '852b1bdbfffffff', '852bad47fffffff', '852ba9c3fffffff', '852b106bfffffff', '852a30d3fffffff', '842b1edffffffff', '852b12a7fffffff', '852b1027fffffff', '842baddffffffff', '852a349bfffffff', '852b1227fffffff', '852a3473fffffff', '852b117bfffffff', '842ba99ffffffff', '852a341bfffffff', '852ba9d3fffffff', '852b1067fffffff', '852a3463fffffff', '852baca7fffffff', '852b116bfffffff', '852b1c6bfffffff', '852a3493fffffff', '852ba9dbfffffff', '852b180bfffffff', '842bad7ffffffff', '852b1063fffffff', '842ba93ffffffff', '852a3693fffffff', '852ba977fffffff', '852b1e9bfffffff', '852bad53fffffff', '852b100ffffffff', '852b102bfffffff', '852a3413fffffff', '852ba8b7fffffff', '852bad43fffffff', '852b1c6ffffffff', '852a340bfffffff', '852b103bfffffff', '852b1813fffffff', '852b12affffffff', '842a34dffffffff', '852b1873fffffff', '852b106ffffffff', '852b115bfffffff', '852baca3fffffff', '852b114bfffffff', '852b1143fffffff', '852a348bfffffff', '852a30d7fffffff', '852b181bfffffff', '842a345ffffffff', '852b1e8ffffffff', '852b1883fffffff', '852b1147fffffff', '852a3483fffffff', '852b12a3fffffff', '852a346bfffffff', '852ba9d7fffffff', '842b18dffffffff', '852b188bfffffff', '852a36a7fffffff', '852bacb3fffffff', '852b187bfffffff', '852bacb7fffffff', '842b1ebffffffff', '842b1e5ffffffff', '852ba8a7fffffff', '842bad9ffffffff', '852a36b7fffffff', '852a347bfffffff', '832b13fffffffff', '852ba9c7fffffff', '832b1afffffffff', '842ba91ffffffff', '852bad57fffffff', '852ba8affffffff', '852b1803fffffff', '842b1e7ffffffff', '852bad4ffffffff', '852b102ffffffff', '852b1077fffffff', '852b1237fffffff', '852b1153fffffff', '852a3697fffffff', '852a36b3fffffff', '842bad1ffffffff', '842b1e1ffffffff', '852b186bfffffff', '852b1023fffffff'} # noqa - assert h_comp == expected + return cells_uncomp, cells_comp, res - return h_uncomp, h_comp, res + +def test_compact_cells(): + cells_uncomp, cells_comp, _ = get_maine_cells() + out = h3.compact_cells(cells_uncomp) + + assert out == cells_comp def test_uncompact_cells(): - - h_uncomp, h_comp, res = test_compact_cells() - - out = h3.uncompact_cells(h_comp, res) - - assert out == h_uncomp + cells_uncomp, cells_comp, res = get_maine_cells() + out = h3.uncompact_cells(cells_comp, res) + assert out == cells_uncomp def test_get_num_cells(): diff --git a/tests/test_h3.py b/tests/test_h3.py index 5900db9..94a9a94 100644 --- a/tests/test_h3.py +++ b/tests/test_h3.py @@ -61,25 +61,6 @@ def test_cell_to_boundary(): assert o == approx(e) -def test_cell_to_boundary_geo_json(): - out = h3.cell_to_boundary('85283473fffffff', True) - - expected = [ - [-121.91508032705622, 37.271355866731895], - [-121.86222328902491, 37.353926450852256], - [-121.9235499963016, 37.42834118609435], - [-122.0377349642703, 37.42012867767778], - [-122.09042892904395, 37.33755608435298], - [-122.02910130919, 37.26319797461824], - [-121.91508032705622, 37.271355866731895], - ] - - assert len(out) == len(expected) - - for o, e in zip(out, expected): - assert o == approx(e) - - def test_grid_disk(): h = '8928308280fffff' out = h3.grid_disk(h, 1) @@ -148,255 +129,6 @@ def test_grid_disk_pentagon(): assert out == expected -sf_7x7 = [ - (37.813318999983238, -122.4089866999972145), - (37.7866302000007224, -122.3805436999997056), - (37.7198061999978478, -122.3544736999993603), - (37.7076131999975672, -122.5123436999983966), - (37.7835871999971715, -122.5247187000021967), - (37.8151571999998453, -122.4798767000009008), -] - -sf_hole1 = [ - (37.7869802, -122.4471197), - (37.7664102, -122.4590777), - (37.7710682, -122.4137097), -] - -sf_hole2 = [ - (37.747976, -122.490025), - (37.731550, -122.503758), - (37.725440, -122.452603), -] - - -def test_polyfill(): - poly = h3.Polygon(sf_7x7) - out = h3.polygon_to_cells(poly, res=9) - - assert len(out) == 1253 - assert '89283080527ffff' in out - assert '89283095edbffff' in out - - -# def test_polyfill_bogus_geo_json(): -# with pytest.raises(ValueError): -# bad_geo = {'type': 'whatwhat'} -# h3.polyfill(bad_geo, 9) - - -def test_polyfill_with_hole(): - poly = h3.Polygon(sf_7x7, sf_hole1) - - out = h3.polygon_to_cells(poly, res=9) - assert len(out) == 1214 - - foo = lambda x: h3.polygon_to_cells(h3.Polygon(x), 9) - # todo: foo = lambda x: h3.Polygon(x).to_cells(9) - assert out == foo(sf_7x7) - foo(sf_hole1) - - -def test_polyfill_with_two_holes(): - - poly = h3.Polygon(sf_7x7, sf_hole1, sf_hole2) - out = h3.polygon_to_cells(poly, 9) - assert len(out) == 1172 - - foo = lambda x: h3.polygon_to_cells(h3.Polygon(x), 9) - assert out == foo(sf_7x7) - (foo(sf_hole1) | foo(sf_hole2)) - -# def test_polyfill_geo_json_compliant(): -# geo = { -# 'type': 'Polygon', -# 'coordinates': [ -# [ -# [-122.4089866999972145, 37.813318999983238], -# [-122.3805436999997056, 37.7866302000007224], -# [-122.3544736999993603, 37.7198061999978478], -# [-122.5123436999983966, 37.7076131999975672], -# [-122.5247187000021967, 37.7835871999971715], -# [-122.4798767000009008, 37.8151571999998453], -# ] -# ] -# } - -# out = h3.polyfill(geo, 9, True) -# assert len(out) > 1000 - - -def test_polyfill_down_under(): - sydney = [ - (-33.8555555, 151.1979259), - (-33.8519779, 151.2074556), - (-33.8579597, 151.224743), - (-33.8582212, 151.2254986), - (-33.8564183032, 151.235313348), - (-33.8594049408, 151.234799568), - (-33.8641069037, 151.233485084), - (-33.8715791334, 151.233181742), - (-33.8876967719, 151.223980353), - (-33.8873877027, 151.219388501), - (-33.8869995, 151.2189209), - (-33.886283399999996, 151.2181177), - (-33.8851287, 151.2157995), - (-33.8852471, 151.2156925), - (-33.8851287, 151.2141233), - (-33.8847438, 151.2116267), - (-33.8834707, 151.2083456), - (-33.8827601, 151.2080246), - (-33.8816053, 151.2059204), - (-33.8827601, 151.2043868), - (-33.8838556, 151.2028176), - (-33.8839148, 151.2022826), - (-33.8842405, 151.2011057), - (-33.8842819, 151.1986114), - (-33.8842405, 151.1986091), - (-33.8773416, 151.1948287), - (-33.8740845, 151.1923322), - (-33.8697019, 151.1850566), - (-33.8625354, 151.1902636), - (-33.8612915, 151.1986805), - (-33.8555555, 151.1979259), - ] - - poly = h3.Polygon(sydney) - out = h3.polygon_to_cells(poly, 9) - assert len(out) == 92 - assert '89be0e34207ffff' in out - assert '89be0e35ddbffff' in out - - -def test_polyfill_far_east(): - geo = [ - (41.92578147109541, 142.86483764648438), - (42.29965889253408, 142.86483764648438), - (42.29965889253408, 143.41552734375), - (41.92578147109541, 143.41552734375), - (41.92578147109541, 142.86483764648438), - ] - - poly = h3.Polygon(geo) - out = h3.polygon_to_cells(poly, 9) - assert len(out) == 18507 - assert '892e18d16c3ffff' in out - assert '892e1ebb5a7ffff' in out - - -def test_polyfill_southern_tip(): - geo = [ - (-55.41654360858007, -67.642822265625), - (-54.354955689554096, -67.642822265625), - (-54.354955689554096, -64.742431640625), - (-55.41654360858007, -64.742431640625), - (-55.41654360858007, -67.642822265625), - ] - - poly = h3.Polygon(geo) - out = h3.polygon_to_cells(poly, 9) - assert len(out) == 223247 - assert '89df4000003ffff' in out - assert '89df4636b27ffff' in out - - -def test_polyfill_null_island(): - geo = [ - (-3, -3), - (+3, -3), - (+3, +3), - (-3, +3), - (-3, -3), - ] - - poly = h3.Polygon(geo) - out = h3.polygon_to_cells(poly, 4) - assert len(out) == 345 - assert '847421bffffffff' in out - assert '84825ddffffffff' in out - - -def test_cells_to_polygons_empty(): - polys = h3.cells_to_polygons([]) - assert polys == [] - - -def test_cells_to_polygons_single(): - h = '89283082837ffff' - cells = {h} - - polys = h3.cells_to_polygons(cells) - assert len(polys) == 1 - poly = polys[0] - - vertices = h3.cell_to_boundary(h) - expected_poly = h3.Polygon(vertices) - - assert set(poly.outer) == set(expected_poly.outer) - assert poly.holes == expected_poly.holes == () - - -def test_cells_to_polygons_contiguous(): - a = '89283082837ffff' - b = '89283082833ffff' - assert h3.are_neighbor_cells(a, b) - - polys = h3.cells_to_polygons([a, b]) - assert len(polys) == 1 - poly = polys[0] - - assert len(poly.outer) == 10 - assert poly.holes == () - - verts_a = h3.cell_to_boundary(a) - verts_b = h3.cell_to_boundary(b) - assert set(poly.outer) == set(verts_a) | set(verts_b) - - -def test_cells_to_polygons_non_contiguous(): - a = '89283082837ffff' - b = '8928308280fffff' - assert not h3.are_neighbor_cells(a, b) - - polys = h3.cells_to_polygons([a, b]) - assert len(polys) == 2 - - assert all(poly.holes == () for poly in polys) - assert all(len(poly.outer) == 6 for poly in polys) - - verts_a = h3.cell_to_boundary(a) - verts_b = h3.cell_to_boundary(b) - - verts_both = set.union(*[set(poly.outer) for poly in polys]) - assert verts_both == set(verts_a) | set(verts_b) - - -def test_cells_to_polygons_hole(): - # Six hexagons in a ring around a hole - cells = [ - '892830828c7ffff', '892830828d7ffff', '8928308289bffff', - '89283082813ffff', '8928308288fffff', '89283082883ffff', - ] - polys = h3.cells_to_polygons(cells) - - assert len(polys) == 1 - poly = polys[0] - - assert len(poly.holes) == 1 - assert len(poly.holes[0]) == 6 - assert len(poly.outer) == 6 * 3 - - -def test_cells_to_polygons_2grid_disk(): - h = '8930062838bffff' - cells = h3.grid_disk(h, 2) - polys = h3.cells_to_polygons(cells) - - assert len(polys) == 1 - poly = polys[0] - - assert len(poly.holes) == 0 - assert len(poly.outer) == 6 * (2 * 2 + 1) - - def test_grid_ring(): h = '8928308280fffff' out = h3.grid_ring(h, 1) @@ -452,8 +184,17 @@ def test_grid_ring_pentagon(): def test_compact_and_uncompact_cells(): - poly = h3.Polygon(sf_7x7) - cells = h3.polygon_to_cells(poly, 9) + sf_7x7 = [ + (37.813318999983238, -122.4089866999972145), + (37.7866302000007224, -122.3805436999997056), + (37.7198061999978478, -122.3544736999993603), + (37.7076131999975672, -122.5123436999983966), + (37.7835871999971715, -122.5247187000021967), + (37.8151571999998453, -122.4798767000009008), + ] + + poly = h3.H3Poly(sf_7x7) + cells = h3.h3shape_to_cells(poly, 9) compact_cells = h3.compact_cells(cells) assert len(compact_cells) == 209 @@ -586,15 +327,6 @@ def test_origin_to_directed_edges(): assert len(h3_uni_edge_pentagon) == 5 -def test_directed_edge_to_boundary(): - e = '11928308280fffff' - boundary = h3.directed_edge_to_boundary(e) - assert len(boundary) == 2 - - boundary_geo_json = h3.directed_edge_to_boundary(e, True) - assert len(boundary_geo_json) == 3 - - def test_grid_distance(): h = '89283082993ffff' diff --git a/tests/test_polyfill.py b/tests/test_polyfill.py deleted file mode 100644 index e52be22..0000000 --- a/tests/test_polyfill.py +++ /dev/null @@ -1,240 +0,0 @@ -import h3 -import itertools -import pytest - -from h3 import H3ResDomainError - - -def reverse(loop): - return list(reversed(loop)) - - -def drop_last(loop): - return loop[:-1] - - -def toggle_map(func, poly): - """ Return all permutations of `func` being applied or not - to each element of `poly` - - returns iterable of length 2**len(poly) - """ - mapped = (list(func(loop)) for loop in poly) - - return itertools.product(*zip(poly, mapped)) - - -def chain_toggle_map(func, seq): - seq = (toggle_map(func, p) for p in seq) - seq = itertools.chain(*seq) - - return seq - - -def input_permutations(geo, res=5): - g = [geo] - g = chain_toggle_map(drop_last, g) - g = chain_toggle_map(reverse, g) - - for p in g: - poly = h3.Polygon(*p) - cells = h3.polygon_to_cells(poly, res=res) - yield cells - - -def swap_element_order(seq): - return [e[::-1] for e in seq] - - -def get_us_box_coords(): - - # big center chunk of the US in lat/lng order - outer = [ - [42.68, -110.61], - [32.17, -109.02], - [31.57, -94.26], - [42.94, -89.38], - [42.68, -110.61] - ] - - hole1 = [ - [39.77, -105.07], - [34.81, -104.72], - [34.77, -98.39], - [40.14, -96.72], - [39.77, -105.07] - ] - - hole2 = [ - [41.37, -98.61], - [40.04, -91.80], - [42.32, -91.80], - [41.37, -98.61] - ] - - return outer, hole1, hole2 - - -def test_polygon_to_cells(): - - # lat/lngs for State of Maine - maine = [ - (45.137451890638886, -67.13734351262877), - (44.8097, -66.96466), - (44.3252, -68.03252), - (43.98, -69.06), - (43.68405, -70.11617), - (43.090083319667144, -70.64573401557249), - (43.08003225358635, -70.75102474636725), - (43.21973948828747, -70.79761105007827), - (43.36789581966826, -70.98176001655037), - (43.46633942318431, -70.94416541205806), - (45.3052400000002, -71.08482), - (45.46022288673396, -70.6600225491012), - (45.914794623389355, -70.30495378282376), - (46.69317088478567, -70.00014034695016), - (47.44777598732787, -69.23708614772835), - (47.184794623394396, -68.90478084987546), - (47.35462921812177, -68.23430497910454), - (47.066248887716995, -67.79035274928509), - (45.702585354182816, -67.79141211614706), - (45.137451890638886, -67.13734351262877) - ] - - # a very rough hexagonal approximation to the State of Maine - expected = { - '832b13fffffffff', - '832b18fffffffff', - '832b1afffffffff', - '832b1efffffffff', - '832ba9fffffffff', - '832badfffffffff' - } - - poly = h3.Polygon(maine) - out = h3.polygon_to_cells(poly, 3) - - assert out == expected - - -def test_polygon_to_cells2(): - lnglat, _, _ = get_us_box_coords() - - poly = h3.Polygon(lnglat) - out = h3.polygon_to_cells(poly, 5) - - assert len(out) == 7063 - - -# todo: we can generate segfaults with malformed input data to polyfill -# need to test for this and avoid segfault -# def test_polyfill_segfault(): -# pass - - -def test_polygon_to_cells_holes(): - - outer, hole1, hole2 = get_us_box_coords() - - assert 7063 == len( - h3.polygon_to_cells(h3.Polygon(outer), 5) - ) - - for res in 1, 2, 3, 4, 5: - cells_all = h3.polygon_to_cells(h3.Polygon(outer), res) - cells_holes = h3.polygon_to_cells(h3.Polygon(outer, hole1, hole2), res=res) - - cells_1 = h3.polygon_to_cells(h3.Polygon(hole1), res) - cells_2 = h3.polygon_to_cells(h3.Polygon(hole2), res) - - assert len(cells_all) == len(cells_holes) + len(cells_1) + len(cells_2) - assert cells_all == set.union(cells_holes, cells_1, cells_2) - - -# def test_polyfill_geojson(): -# outer, hole1, hole2 = get_us_box_coords(order='lnglat') - -# d = { -# 'type': 'Polygon', -# 'coordinates': [outer], -# } - -# out = h3.polyfill_geojson(d, 5) - -# assert len(out) == 7063 - - -# def test_polyfill(): -# outer, hole1, hole2 = get_us_box_coords(order='lnglat') - -# d = { -# 'type': 'Polygon', -# 'coordinates': [outer], -# } - -# out = h3.polyfill(d, 5, geo_json_conformant=True) - -# assert len(out) == 7063 - - -def test_input_format(): - """ Test that `polygon_to_cells` can take in polygon inputs - where the LinearRings may or may not follow the right hand rule, - and they may or may not be closed loops (where the last element - is equal to the first). - - Test all permutations of these rules on polygons with - 0, 1, and 2 holes. Ensure that for any polygon, each LinearRing - may follow a different subset of rules. - """ - - geo = get_us_box_coords() - - assert len(geo) == 3 - - # two holes - for cells in input_permutations(geo[:3]): - assert len(cells) == 5437 - - # one hole - for cells in input_permutations(geo[:2]): - assert len(cells) == 5726 - - # zero holes - for cells in input_permutations(geo[:1]): - assert len(cells) == 7063 - - -def test_resolution(): - poly = h3.Polygon([]) - - assert h3.polygon_to_cells(poly, 0) == set() - assert h3.polygon_to_cells(poly, 15) == set() - - with pytest.raises(H3ResDomainError): - h3.polygon_to_cells(poly, -1) - - with pytest.raises(H3ResDomainError): - h3.polygon_to_cells(poly, 16) - - -def test_invalid_polygon(): - """ - We were previously seeing segfaults on data like - this because we weren't raising errors inside - some `cdef` functions. - """ - with pytest.raises(TypeError): - poly = h3.Polygon([1, 2, 3]) - h3.polygon_to_cells(poly, 4) - - with pytest.raises(ValueError): - poly = h3.Polygon([[1, 2, 3]]) - h3.polygon_to_cells(poly, 4) - - # d = { - # 'type': 'Polygon', - # 'coordinates': [(1, 2), (2, 2), (2, 1), (1, 2)], - # } - # with pytest.raises(TypeError): - # h3.polyfill(d, 4) diff --git a/tests/test_polygon_class.py b/tests/test_polygon_class.py deleted file mode 100644 index d14b62a..0000000 --- a/tests/test_polygon_class.py +++ /dev/null @@ -1,27 +0,0 @@ -import h3 - - -def test_repr(): - a = '8928308280fffff' - b = h3.grid_ring(a, 5).pop() - - cells1 = h3.grid_ring(b, 2) | {a} - cells2 = cells1 | {b} - - poly1 = h3.cells_to_polygons(cells1) - poly2 = h3.cells_to_polygons(cells2) - - # unfortunately output order is nondeterministic - poly1 = sorted(map(str, poly1)) - poly2 = sorted(map(str, poly2)) - - assert poly1 == [ - '', - '', - ] - - assert poly2 == [ - '', - '', - '', - ] diff --git a/tests/test_to_multipoly.py b/tests/test_to_multipoly.py deleted file mode 100644 index be2b948..0000000 --- a/tests/test_to_multipoly.py +++ /dev/null @@ -1,32 +0,0 @@ -import h3 - - -def test_cells_to_polygons(): - h = '8928308280fffff' - cells = h3.grid_disk(h, 1) - - polys = h3.cells_to_polygons(cells) - poly = polys[0] - - poly2 = h3.Polygon(poly.outer, *poly.holes) - out = h3.polygon_to_cells(poly2, 9) - - assert out == cells - - -def test_2_polys(): - h = '8928308280fffff' - cells = h3.grid_ring(h, 2) - cells = cells | {h} - # cells should be a center hex, and the 2-ring around it - # (with the 1-ring being absent) - - polys = h3.cells_to_polygons(cells) - - out = [ - h3.polygon_to_cells(poly, 9) - for poly in polys - ] - - assert set.union(*out) == cells - assert set(map(len, out)) == {1, 12} From 158f52d9b6e9bc2d19844db5a635e43add72fb7d Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Mon, 1 Jan 2024 15:15:30 -0800 Subject: [PATCH 076/177] Use functions instead of methods for the interface functions (#334) * starting refactor * remove stuff * unindent * remove self from function signatures * remove self. * remove staticmethod * set up symlinks * some linting * test for bad H3Shape * symlink note * just put everything in __init__.py * reorganize conversion functions * rename _api_funcs.py to _convert.py * use lazy import of numpy so we don't have to special case h3.api.numpy_int * DRY --- .coveragerc | 5 + src/h3/api/__init__.py | 1 + src/h3/api/_api_template.py | 945 -------------------------- src/h3/api/basic_int/__init__.py | 944 ++++++++++++++++++++++++- src/h3/api/basic_int/_binding.py | 36 - src/h3/api/basic_int/_convert.py | 18 + src/h3/api/basic_int/_public_api.py | 63 -- src/h3/api/basic_str/__init__.py | 10 +- src/h3/api/basic_str/_binding.py | 43 -- src/h3/api/basic_str/_convert.py | 20 + src/h3/api/basic_str/_public_api.py | 1 - src/h3/api/memview_int/__init__.py | 10 +- src/h3/api/memview_int/_binding.py | 31 - src/h3/api/memview_int/_convert.py | 9 + src/h3/api/memview_int/_public_api.py | 1 - src/h3/api/numpy_int/__init__.py | 10 +- src/h3/api/numpy_int/_binding.py | 43 -- src/h3/api/numpy_int/_convert.py | 16 + src/h3/api/numpy_int/_public_api.py | 1 - tests/polyfill/test_polygon_class.py | 9 + tests/test_api_bindings_match.py | 9 +- 21 files changed, 1022 insertions(+), 1203 deletions(-) create mode 100644 .coveragerc delete mode 100644 src/h3/api/_api_template.py delete mode 100644 src/h3/api/basic_int/_binding.py create mode 100644 src/h3/api/basic_int/_convert.py delete mode 100644 src/h3/api/basic_int/_public_api.py mode change 100644 => 120000 src/h3/api/basic_str/__init__.py delete mode 100644 src/h3/api/basic_str/_binding.py create mode 100644 src/h3/api/basic_str/_convert.py delete mode 120000 src/h3/api/basic_str/_public_api.py mode change 100644 => 120000 src/h3/api/memview_int/__init__.py delete mode 100644 src/h3/api/memview_int/_binding.py create mode 100644 src/h3/api/memview_int/_convert.py delete mode 120000 src/h3/api/memview_int/_public_api.py mode change 100644 => 120000 src/h3/api/numpy_int/__init__.py delete mode 100644 src/h3/api/numpy_int/_binding.py create mode 100644 src/h3/api/numpy_int/_convert.py delete mode 120000 src/h3/api/numpy_int/_public_api.py diff --git a/.coveragerc b/.coveragerc new file mode 100644 index 0000000..662935d --- /dev/null +++ b/.coveragerc @@ -0,0 +1,5 @@ +[run] +omit = + */h3/api/basic_int/__init__.py + */h3/api/memview_int/__init__.py + */h3/api/numpy_int/__init__.py diff --git a/src/h3/api/__init__.py b/src/h3/api/__init__.py index 9bc858a..435b13a 100644 --- a/src/h3/api/__init__.py +++ b/src/h3/api/__init__.py @@ -3,3 +3,4 @@ from . import basic_int from . import basic_str from . import memview_int +from . import numpy_int diff --git a/src/h3/api/_api_template.py b/src/h3/api/_api_template.py deleted file mode 100644 index 1b7fd0d..0000000 --- a/src/h3/api/_api_template.py +++ /dev/null @@ -1,945 +0,0 @@ -""" -Module to DRY-up code which is repeated across API modules. - -Definitions of types --------------------- -H3Index: - An unsigned 64-bit integer representing a valid H3 cell or - unidirectional edge. - Depending on the API, an H3Index may be represented as an - unsigned integer type, or as a hexadecimal string. - -H3 cell: - A pentagon or hexagon that can be represented by an H3Index. - -H3Cell: - H3Index representation of an H3 cell. - -H3Edge: - H3Index representation of an H3 unidirectional edge. - - -Definitions of collections --------------------------- -Collection types vary between APIs. We'll use the following terms: - -unordered collection: - Inputs and outputs are interpreted as *unordered* collections. - Examples: `set`, `numpy.ndarray`. - -ordered collection: - Inputs and outputs are interpreted as *ordered* collections. - Examples: `list`, `numpy.ndarray`. - -Notes --------------------- -todo: how do we lint these functions and docstrings? it seems to currently -be skipped due to it being inside the `_api_functions` function. -""" - -from .. import _cy -from .._h3shape import ( - H3Poly, - H3MultiPoly, - geo_to_h3shape, - h3shape_to_geo, -) - - -class _API_FUNCTIONS(object): - def __init__( - self, - _in_scalar, - _out_scalar, - _in_collection, - _out_unordered, - _out_ordered, - ): - self._in_scalar = _in_scalar - self._out_scalar = _out_scalar - self._in_collection = _in_collection - self._out_unordered = _out_unordered - self._out_ordered = _out_ordered - - @staticmethod - def versions(): - """ - Version numbers for the Python (wrapper) and C (wrapped) libraries. - - Versions are output as strings of the form ``'X.Y.Z'``. - C and Python should match on ``X`` (major) and ``Y`` (minor), - but may differ on ``Z`` (patch). - - Returns - ------- - dict like ``{'c': 'X.Y.Z', 'python': 'A.B.C'}`` - """ - from .._version import __version__ - - v = { - 'c': _cy.c_version(), - 'python': __version__, - } - - return v - - @staticmethod - def str_to_int(h): - """ - Converts a hexadecimal string to an H3 64-bit integer index. - - Parameters - ---------- - h : str - Hexadecimal string like ``'89754e64993ffff'`` - - Returns - ------- - int - Unsigned 64-bit integer - """ - return _cy.str_to_int(h) - - @staticmethod - def int_to_str(x): - """ - Converts an H3 64-bit integer index to a hexadecimal string. - - Parameters - ---------- - x : int - Unsigned 64-bit integer - - Returns - ------- - str - Hexadecimal string like ``'89754e64993ffff'`` - """ - return _cy.int_to_str(x) - - @staticmethod - def get_num_cells(res): - """ - Return the total number of *cells* (hexagons and pentagons) - for the given resolution. - - Returns - ------- - int - """ - return _cy.get_num_cells(res) - - @staticmethod - def average_hexagon_area(res, unit='km^2'): - """ - Return the average area of an H3 *hexagon* - for the given resolution. - - This average *excludes* pentagons. - - Returns - ------- - float - """ - return _cy.average_hexagon_area(res, unit) - - @staticmethod - def average_hexagon_edge_length(res, unit='km'): - """ - Return the average *hexagon* edge length - for the given resolution. - - This average *excludes* pentagons. - - Returns - ------- - float - """ - return _cy.average_hexagon_edge_length(res, unit) - - def is_valid_cell(self, h): - """ - Validates an H3 cell (hexagon or pentagon). - - Returns - ------- - bool - """ - try: - h = self._in_scalar(h) - return _cy.is_valid_cell(h) - except (ValueError, TypeError): - return False - - def is_valid_directed_edge(self, edge): - """ - Validates an H3 unidirectional edge. - - Returns - ------- - bool - """ - try: - e = self._in_scalar(edge) - return _cy.is_valid_directed_edge(e) - except (ValueError, TypeError): - return False - - def latlng_to_cell(self, lat, lng, res): - """ - Return the cell containing the (lat, lng) point - for a given resolution. - - Returns - ------- - H3Cell - - """ - return self._out_scalar(_cy.latlng_to_cell(lat, lng, res)) - - def cell_to_latlng(self, h): - """ - Return the center point of an H3 cell as a lat/lng pair. - - Parameters - ---------- - h : H3Cell - - Returns - ------- - lat : float - Latitude - lng : float - Longitude - """ - return _cy.cell_to_latlng(self._in_scalar(h)) - - def get_resolution(self, h): - """ - Return the resolution of an H3 cell. - - Parameters - ---------- - h : H3Cell - - Returns - ------- - int - """ - # todo: could also work for edges - return _cy.get_resolution(self._in_scalar(h)) - - def cell_to_parent(self, h, res=None): - """ - Get the parent of a cell. - - Parameters - ---------- - h : H3Cell - res : int or None, optional - The resolution for the parent - If ``None``, then ``res = resolution(h) - 1`` - - Returns - ------- - H3Cell - """ - h = self._in_scalar(h) - p = _cy.cell_to_parent(h, res) - p = self._out_scalar(p) - - return p - - def grid_distance(self, h1, h2): - """ - Compute the H3 distance between two cells. - - The H3 distance is defined as the length of the shortest - path between the cells in the graph formed by connecting - adjacent cells. - - This function will raise an exception if the - cells are too far apart to compute the distance. - - Parameters - ---------- - h1 : H3Cell - h2 : H3Cell - - Returns - ------- - int - """ - h1 = self._in_scalar(h1) - h2 = self._in_scalar(h2) - - d = _cy.grid_distance(h1, h2) - - return d - - def cell_to_boundary(self, h): - """ - Return tuple of lat/lng pairs describing the cell boundary. - - Parameters - ---------- - h : H3Cell - - Returns - ------- - tuple of (lat, lng) tuples - """ - return _cy.cell_to_boundary(self._in_scalar(h)) - - def grid_disk(self, h, k=1): - """ - Return unordered set of cells with H3 distance ``<= k`` from ``h``. - That is, the "filled-in" disk. - - Parameters - ---------- - h : H3Cell - k : int - Size of disk. - - Returns - ------- - unordered collection of H3Cell - """ - mv = _cy.grid_disk(self._in_scalar(h), k) - - return self._out_unordered(mv) - - def grid_ring(self, h, k=1): - """ - Return unordered set of cells with H3 distance ``== k`` from ``h``. - That is, the "hollow" ring. - - Parameters - ---------- - h : H3Cell - k : int - Size of ring. - - Returns - ------- - unordered collection of H3Cell - """ - mv = _cy.grid_ring(self._in_scalar(h), k) - - return self._out_unordered(mv) - - def cell_to_children(self, h, res=None): - """ - Children of a cell. - - Parameters - ---------- - h : H3Cell - res : int or None, optional - The resolution for the children. - If ``None``, then ``res = resolution(h) + 1`` - - Returns - ------- - unordered collection of H3Cell - """ - mv = _cy.cell_to_children(self._in_scalar(h), res) - - return self._out_unordered(mv) - - # todo: nogil for expensive C operation? - def compact_cells(self, cells): - """ - Compact a collection of H3 cells by combining - smaller cells into larger cells, if all child cells - are present. Input cells must all share the same resolution. - - Parameters - ---------- - cells : iterable of H3 Cells - - Returns - ------- - unordered collection of H3Cell - """ - # todo: does compact_cells work on mixed-resolution collections? - hu = self._in_collection(cells) - hc = _cy.compact_cells(hu) - - return self._out_unordered(hc) - - def uncompact_cells(self, cells, res): - """ - Reverse the `compact_cells` operation. - - Return a collection of H3 cells, all of resolution ``res``. - - Parameters - ---------- - cells : iterable of H3Cell - res : int - Resolution of desired output cells. - - Returns - ------- - unordered collection of H3Cell - - Raises - ------ - todo: add test to make sure an error is returned when input - contains cell smaller than output res. - https://github.com/uber/h3/blob/master/src/h3lib/lib/h3Index.c#L425 - """ - hc = self._in_collection(cells) - hu = _cy.uncompact_cells(hc, res) - - return self._out_unordered(hu) - - def h3shape_to_cells(self, h3shape, res): - """ - Return the set of H3 cells at a given resolution whose center points - are contained within an `H3Poly` or `H3MultiPoly`. - - Parameters - ---------- - h3shape : H3shape - res : int - Resolution of the output cells - - Returns - ------- - unordered collection of H3Cell - - Examples - -------- - - >>> poly = H3Poly( - ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), - ... (37.82, -122.54)], - ... ) - >>> h3.h3shape_to_cells(poly, 6) - {'862830807ffffff', - '862830827ffffff', - '86283082fffffff', - '862830877ffffff', - '862830947ffffff', - '862830957ffffff', - '86283095fffffff'} - """ - - # todo: not sure if i want this dispatch logic here. maybe in the objects? - if isinstance(h3shape, H3Poly): - poly = h3shape - mv = _cy.polygon_to_cells(poly.outer, res, holes=poly.holes) - elif isinstance(h3shape, H3MultiPoly): - mpoly = h3shape - mv = _cy.polygons_to_cells(mpoly.polys, res) - else: - raise ValueError('Unrecognized type: ' + str(type(h3shape))) - - return self._out_unordered(mv) - - def cells_to_h3shape(self, cells, tight=True): - """ - Return a H3MultiPoly describing the area covered by a set of H3 cells. - - Parameters - ---------- - cells : iterable of H3 cells - tight : bool - If True, return H3Poly if possible. If False, always return H3MultiPoly - - Returns - ------- - H3Poly | H3MultiPoly - - Examples - -------- - - >>> cells = ['8428309ffffffff', '842830dffffffff'] - >>> h3.cells_to_h3shape(cells, tight=True) - - >>> h3.cells_to_h3shape(cells, tight=False) - - """ - cells = self._in_collection(cells) - mpoly = _cy.cells_to_multi_polygon(cells) - - polys = [H3Poly(*poly) for poly in mpoly] - out = H3MultiPoly(*polys) - - if tight and len(out) == 1: - out = out[0] - - return out - - def geo_to_cells(self, geo, res): - """ Convert from __geo_interface__ to cells. - - Parameters - ---------- - geo : an object implementing `__geo_interface__` or a dictionary in that format. - Both H3Poly and H3MultiPoly implement the interface. - res : int - Resolution of desired output cells. - """ - h3shape = geo_to_h3shape(geo) - return self.h3shape_to_cells(h3shape, res) - - def cells_to_geo(self, cells, tight=True): - """ - Parameters - ---------- - cells : iterable of H3 Cells - - Returns - ------- - dict - in `__geo_interface__` format - """ - h3shape = self.cells_to_h3shape(cells, tight=tight) - return h3shape_to_geo(h3shape) - - def is_pentagon(self, h): - """ - Identify if an H3 cell is a pentagon. - - Parameters - ---------- - h : H3Index - - Returns - ------- - bool - ``True`` if input is a valid H3 cell which is a pentagon. - - Notes - ----- - A pentagon should *also* pass ``is_valid_cell()``. - Will return ``False`` for valid H3Edge. - """ - return _cy.is_pentagon(self._in_scalar(h)) - - def get_base_cell_number(self, h): - """ - Return the base cell *number* (``0`` to ``121``) of the given cell. - - The base cell *number* and the H3Index are two different representations - of the same cell: the parent cell of resolution ``0``. - - The base cell *number* is encoded within the corresponding - H3Index. - - todo: could work with edges - - Parameters - ---------- - h : H3Cell - - Returns - ------- - int - """ - return _cy.get_base_cell_number(self._in_scalar(h)) - - def are_neighbor_cells(self, h1, h2): - """ - Returns ``True`` if ``h1`` and ``h2`` are neighboring cells. - - Parameters - ---------- - h1 : H3Cell - h2 : H3Cell - - Returns - ------- - bool - """ - h1 = self._in_scalar(h1) - h2 = self._in_scalar(h2) - - return _cy.are_neighbor_cells(h1, h2) - - def cells_to_directed_edge(self, origin, destination): - """ - Create an H3 Index denoting a unidirectional edge. - - The edge is constructed from neighboring cells ``origin`` and - ``destination``. - - Parameters - ---------- - origin : H3Cell - destination : H3Cell - - Raises - ------ - ValueError - When cells are not adjacent. - - Returns - ------- - H3Edge - """ - o = self._in_scalar(origin) - d = self._in_scalar(destination) - e = _cy.cells_to_directed_edge(o, d) - e = self._out_scalar(e) - - return e - - def get_directed_edge_origin(self, e): - """ - Origin cell from an H3 directed edge. - - Parameters - ---------- - e : H3Edge - - Returns - ------- - H3Cell - """ - e = self._in_scalar(e) - o = _cy.get_directed_edge_origin(e) - o = self._out_scalar(o) - - return o - - def get_directed_edge_destination(self, e): - """ - Destination cell from an H3 directed edge. - - Parameters - ---------- - e : H3Edge - - Returns - ------- - H3Cell - """ - e = self._in_scalar(e) - d = _cy.get_directed_edge_destination(e) - d = self._out_scalar(d) - - return d - - def directed_edge_to_cells(self, e): - """ - Return (origin, destination) tuple from H3 directed edge - - Parameters - ---------- - e : H3Edge - - Returns - ------- - H3Cell - Origin cell of edge - H3Cell - Destination cell of edge - """ - e = self._in_scalar(e) - o, d = _cy.directed_edge_to_cells(e) - o, d = self._out_scalar(o), self._out_scalar(d) - - return o, d - - def origin_to_directed_edges(self, origin): - """ - Return all directed edges starting from ``origin`` cell. - - Parameters - ---------- - origin : H3Cell - - Returns - ------- - unordered collection of H3Edge - """ - mv = _cy.origin_to_directed_edges(self._in_scalar(origin)) - - return self._out_unordered(mv) - - def directed_edge_to_boundary(self, edge): - return _cy.directed_edge_to_boundary(self._in_scalar(edge)) - - def grid_path_cells(self, start, end): - """ - Returns the ordered collection of cells denoting a - minimum-length non-unique path between cells. - - Parameters - ---------- - start : H3Cell - end : H3Cell - - Returns - ------- - ordered collection of H3Cell - Starting with ``start``, and ending with ``end``. - """ - mv = _cy.grid_path_cells(self._in_scalar(start), self._in_scalar(end)) - - return self._out_ordered(mv) - - def is_res_class_III(self, h): - """ - Determine if cell has orientation "Class II" or "Class III". - - The orientation of pentagons/hexagons on the icosahedron can be one - of two types: "Class II" or "Class III". - - All cells within a resolution have the same type, and the type - alternates between resolutions. - - "Class II" cells have resolutions: 0,2,4,6,8,10,12,14 - "Class III" cells have resolutions: 1,3,5,7,9,11,13,15 - - Parameters - ---------- - h : H3Cell - - Returns - ------- - bool - ``True`` if ``h`` is "Class III". - ``False`` if ``h`` is "Class II". - - References - ---------- - 1. https://uber.github.io/h3/#/documentation/core-library/coordinate-systems - """ - return _cy.is_res_class_iii(self._in_scalar(h)) - - def get_pentagons(self, res): - """ - Return all pentagons at a given resolution. - - Parameters - ---------- - res : int - Resolution of the pentagons - - Returns - ------- - unordered collection of H3Cell - """ - mv = _cy.get_pentagons(res) - - return self._out_unordered(mv) - - def get_res0_cells(self): - """ - Return all cells at resolution 0. - - Parameters - ---------- - None - - Returns - ------- - unordered collection of H3Cell - """ - mv = _cy.get_res0_cells() - - return self._out_unordered(mv) - - def cell_to_center_child(self, h, res=None): - """ - Get the center child of a cell at some finer resolution. - - Parameters - ---------- - h : H3Cell - res : int or None, optional - The resolution for the child cell - If ``None``, then ``res = resolution(h) + 1`` - - Returns - ------- - H3Cell - """ - h = self._in_scalar(h) - p = _cy.cell_to_center_child(h, res) - p = self._out_scalar(p) - - return p - - def get_icosahedron_faces(self, h): - """ - Return icosahedron faces intersecting a given H3 cell. - - There are twenty possible faces, ranging from 0--19. - - Note: Every interface returns a Python ``set`` of ``int``. - - Parameters - ---------- - h : H3Cell - - Returns - ------- - Python ``set`` of ``int`` - """ - h = self._in_scalar(h) - faces = _cy.get_icosahedron_faces(h) - - return faces - - def cell_to_local_ij(self, origin, h): - """ - Return local (i,j) coordinates of cell ``h`` in relation to ``origin`` cell - - - Parameters - ---------- - origin : H3Cell - Origin/central cell for defining i,j coordinates. - h: H3Cell - Destination cell whose i,j coordinates we'd like, based off - of the origin cell. - - - Returns - ------- - Tuple (i, j) of integer local coordinates of cell ``h`` - - - Notes - ----- - - The ``origin`` cell does not define (0, 0) for the IJ coordinate space. - (0, 0) refers to the center of the base cell containing origin at the - resolution of `origin`. - Subtracting the IJ coordinates of ``origin`` from every cell would get - you the property of (0, 0) being the ``origin``. - - This is done so we don't need to keep recomputing the coordinates of - ``origin`` if not needed. - """ - origin = self._in_scalar(origin) - h = self._in_scalar(h) - - i, j = _cy.cell_to_local_ij(origin, h) - - return i, j - - def local_ij_to_cell(self, origin, i, j): - """ - Return cell at local (i,j) position relative to the ``origin`` cell. - - Parameters - ---------- - origin : H3Cell - Origin/central cell for defining i,j coordinates. - i, j: int - Integer coordinates with respect to ``origin`` cell. - - - Returns - ------- - H3Cell at local (i,j) position relative to the ``origin`` cell - - - Notes - ----- - - The ``origin`` cell does not define (0, 0) for the IJ coordinate space. - (0, 0) refers to the center of the base cell containing origin at the - resolution of ``origin``. - Subtracting the IJ coordinates of ``origin`` from every cell would get - you the property of (0, 0) being the ``origin``. - - This is done so we don't need to keep recomputing the coordinates of - ``origin`` if not needed. - """ - origin = self._in_scalar(origin) - - h = _cy.local_ij_to_cell(origin, i, j) - h = self._out_scalar(h) - - return h - - def cell_area(self, h, unit='km^2'): - """ - Compute the spherical surface area of a specific H3 cell. - - Parameters - ---------- - h : H3Cell - unit: str - Unit for area result (``'km^2'``, 'm^2', or 'rads^2') - - - Returns - ------- - The area of the H3 cell in the given units - - - Notes - ----- - This function breaks the cell into spherical triangles, and computes - their spherical area. - The function uses the spherical distance calculation given by - `great_circle_distance`. - """ - h = self._in_scalar(h) - - return _cy.cell_area(h, unit=unit) - - def edge_length(self, e, unit='km'): - """ - Compute the spherical length of a specific H3 edge. - - Parameters - ---------- - h : H3Cell - unit: str - Unit for length result ('km', 'm', or 'rads') - - - Returns - ------- - The length of the edge in the given units - - - Notes - ----- - This function uses the spherical distance calculation given by - `great_circle_distance`. - """ - e = self._in_scalar(e) - - return _cy.edge_length(e, unit=unit) - - @staticmethod - def great_circle_distance(latlng1, latlng2, unit='km'): - """ - Compute the spherical distance between two (lat, lng) points. - AKA: great circle distance or "haversine" distance. - - todo: overload to allow two cell inputs? - - Parameters - ---------- - latlng1 : tuple - (lat, lng) tuple in degrees - latlng2 : tuple - (lat, lng) tuple in degrees - unit: str - Unit for distance result ('km', 'm', or 'rads') - - - Returns - ------- - The spherical distance between the points in the given units - """ - lat1, lng1 = latlng1 - lat2, lng2 = latlng2 - return _cy.great_circle_distance( - lat1, lng1, - lat2, lng2, - unit = unit - ) diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index a297461..a9858cb 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -1,9 +1,939 @@ -# flake8: noqa -from ._public_api import * +# This file is **symlinked** across the APIs to ensure they are exactly the same. + +from ... import _cy from ..._h3shape import ( - H3MultiPoly, - H3Poly, - H3Shape, - geo_to_h3shape, - h3shape_to_geo, + H3Shape, + H3Poly, + H3MultiPoly, + geo_to_h3shape, + h3shape_to_geo, ) + +from ._convert import ( + _in_scalar, + _out_scalar, + _in_collection, + _out_unordered, + _out_ordered, +) + + +def versions(): + """ + Version numbers for the Python (wrapper) and C (wrapped) libraries. + + Versions are output as strings of the form ``'X.Y.Z'``. + C and Python should match on ``X`` (major) and ``Y`` (minor), + but may differ on ``Z`` (patch). + + Returns + ------- + dict like ``{'c': 'X.Y.Z', 'python': 'A.B.C'}`` + """ + from ..._version import __version__ + + v = { + 'c': _cy.c_version(), + 'python': __version__, + } + + return v + + +def str_to_int(h): + """ + Converts a hexadecimal string to an H3 64-bit integer index. + + Parameters + ---------- + h : str + Hexadecimal string like ``'89754e64993ffff'`` + + Returns + ------- + int + Unsigned 64-bit integer + """ + return _cy.str_to_int(h) + + +def int_to_str(x): + """ + Converts an H3 64-bit integer index to a hexadecimal string. + + Parameters + ---------- + x : int + Unsigned 64-bit integer + + Returns + ------- + str + Hexadecimal string like ``'89754e64993ffff'`` + """ + return _cy.int_to_str(x) + + +def get_num_cells(res): + """ + Return the total number of *cells* (hexagons and pentagons) + for the given resolution. + + Returns + ------- + int + """ + return _cy.get_num_cells(res) + + +def average_hexagon_area(res, unit='km^2'): + """ + Return the average area of an H3 *hexagon* + for the given resolution. + + This average *excludes* pentagons. + + Returns + ------- + float + """ + return _cy.average_hexagon_area(res, unit) + + +def average_hexagon_edge_length(res, unit='km'): + """ + Return the average *hexagon* edge length + for the given resolution. + + This average *excludes* pentagons. + + Returns + ------- + float + """ + return _cy.average_hexagon_edge_length(res, unit) + + +def is_valid_cell(h): + """ + Validates an H3 cell (hexagon or pentagon). + + Returns + ------- + bool + """ + try: + h = _in_scalar(h) + return _cy.is_valid_cell(h) + except (ValueError, TypeError): + return False + + +def is_valid_directed_edge(edge): + """ + Validates an H3 unidirectional edge. + + Returns + ------- + bool + """ + try: + e = _in_scalar(edge) + return _cy.is_valid_directed_edge(e) + except (ValueError, TypeError): + return False + + +def latlng_to_cell(lat, lng, res): + """ + Return the cell containing the (lat, lng) point + for a given resolution. + + Returns + ------- + H3Cell + + """ + return _out_scalar(_cy.latlng_to_cell(lat, lng, res)) + + +def cell_to_latlng(h): + """ + Return the center point of an H3 cell as a lat/lng pair. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + lat : float + Latitude + lng : float + Longitude + """ + return _cy.cell_to_latlng(_in_scalar(h)) + + +def get_resolution(h): + """ + Return the resolution of an H3 cell. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + int + """ + # todo: could also work for edges + return _cy.get_resolution(_in_scalar(h)) + + +def cell_to_parent(h, res=None): + """ + Get the parent of a cell. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the parent + If ``None``, then ``res = resolution(h) - 1`` + + Returns + ------- + H3Cell + """ + h = _in_scalar(h) + p = _cy.cell_to_parent(h, res) + p = _out_scalar(p) + + return p + + +def grid_distance(h1, h2): + """ + Compute the H3 distance between two cells. + + The H3 distance is defined as the length of the shortest + path between the cells in the graph formed by connecting + adjacent cells. + + This function will raise an exception if the + cells are too far apart to compute the distance. + + Parameters + ---------- + h1 : H3Cell + h2 : H3Cell + + Returns + ------- + int + """ + h1 = _in_scalar(h1) + h2 = _in_scalar(h2) + + d = _cy.grid_distance(h1, h2) + + return d + + +def cell_to_boundary(h): + """ + Return tuple of lat/lng pairs describing the cell boundary. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + tuple of (lat, lng) tuples + """ + return _cy.cell_to_boundary(_in_scalar(h)) + + +def grid_disk(h, k=1): + """ + Return unordered set of cells with H3 distance ``<= k`` from ``h``. + That is, the 'filled-in' disk. + + Parameters + ---------- + h : H3Cell + k : int + Size of disk. + + Returns + ------- + unordered collection of H3Cell + """ + mv = _cy.grid_disk(_in_scalar(h), k) + + return _out_unordered(mv) + + +def grid_ring(h, k=1): + """ + Return unordered set of cells with H3 distance ``== k`` from ``h``. + That is, the "hollow" ring. + + Parameters + ---------- + h : H3Cell + k : int + Size of ring. + + Returns + ------- + unordered collection of H3Cell + """ + mv = _cy.grid_ring(_in_scalar(h), k) + + return _out_unordered(mv) + + +def cell_to_children(h, res=None): + """ + Children of a cell. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the children. + If ``None``, then ``res = resolution(h) + 1`` + + Returns + ------- + unordered collection of H3Cell + """ + mv = _cy.cell_to_children(_in_scalar(h), res) + + return _out_unordered(mv) + + +# todo: nogil for expensive C operation? +def compact_cells(cells): + """ + Compact a collection of H3 cells by combining + smaller cells into larger cells, if all child cells + are present. Input cells must all share the same resolution. + + Parameters + ---------- + cells : iterable of H3 Cells + + Returns + ------- + unordered collection of H3Cell + """ + # todo: does compact_cells work on mixed-resolution collections? + hu = _in_collection(cells) + hc = _cy.compact_cells(hu) + + return _out_unordered(hc) + + +def uncompact_cells(cells, res): + """ + Reverse the `compact_cells` operation. + + Return a collection of H3 cells, all of resolution ``res``. + + Parameters + ---------- + cells : iterable of H3Cell + res : int + Resolution of desired output cells. + + Returns + ------- + unordered collection of H3Cell + + Raises + ------ + todo: add test to make sure an error is returned when input + contains cell smaller than output res. + https://github.com/uber/h3/blob/master/src/h3lib/lib/h3Index.c#L425 + """ + hc = _in_collection(cells) + hu = _cy.uncompact_cells(hc, res) + + return _out_unordered(hu) + + +def h3shape_to_cells(h3shape, res): + """ + Return the set of H3 cells at a given resolution whose center points + are contained within an `H3Poly` or `H3MultiPoly`. + + Parameters + ---------- + h3shape : H3shape + res : int + Resolution of the output cells + + Returns + ------- + unordered collection of H3Cell + + Examples + -------- + + >>> poly = H3Poly( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), + ... (37.82, -122.54)], + ... ) + >>> h3.h3shape_to_cells(poly, 6) + {'862830807ffffff', + '862830827ffffff', + '86283082fffffff', + '862830877ffffff', + '862830947ffffff', + '862830957ffffff', + '86283095fffffff'} + """ + + # todo: not sure if i want this dispatch logic here. maybe in the objects? + if isinstance(h3shape, H3Poly): + poly = h3shape + mv = _cy.polygon_to_cells(poly.outer, res, holes=poly.holes) + elif isinstance(h3shape, H3MultiPoly): + mpoly = h3shape + mv = _cy.polygons_to_cells(mpoly.polys, res) + elif isinstance(h3shape, H3Shape): + raise ValueError('Unrecognized H3Shape: ' + str(h3shape)) + else: + raise ValueError('Unrecognized type: ' + str(type(h3shape))) + + return _out_unordered(mv) + + +def cells_to_h3shape(cells, tight=True): + """ + Return a H3MultiPoly describing the area covered by a set of H3 cells. + + Parameters + ---------- + cells : iterable of H3 cells + tight : bool + If True, return H3Poly if possible. If False, always return H3MultiPoly + + Returns + ------- + H3Poly | H3MultiPoly + + Examples + -------- + + >>> cells = ['8428309ffffffff', '842830dffffffff'] + >>> h3.cells_to_h3shape(cells, tight=True) + + >>> h3.cells_to_h3shape(cells, tight=False) + + """ + cells = _in_collection(cells) + mpoly = _cy.cells_to_multi_polygon(cells) + + polys = [H3Poly(*poly) for poly in mpoly] + out = H3MultiPoly(*polys) + + if tight and len(out) == 1: + out = out[0] + + return out + + +def geo_to_cells(geo, res): + """Convert from __geo_interface__ to cells. + + Parameters + ---------- + geo : an object implementing `__geo_interface__` or a dictionary in that format. + Both H3Poly and H3MultiPoly implement the interface. + res : int + Resolution of desired output cells. + """ + h3shape = geo_to_h3shape(geo) + return h3shape_to_cells(h3shape, res) + + +def cells_to_geo(cells, tight=True): + """ + Parameters + ---------- + cells : iterable of H3 Cells + + Returns + ------- + dict + in `__geo_interface__` format + """ + h3shape = cells_to_h3shape(cells, tight=tight) + return h3shape_to_geo(h3shape) + + +def is_pentagon(h): + """ + Identify if an H3 cell is a pentagon. + + Parameters + ---------- + h : H3Index + + Returns + ------- + bool + ``True`` if input is a valid H3 cell which is a pentagon. + + Notes + ----- + A pentagon should *also* pass ``is_valid_cell()``. + Will return ``False`` for valid H3Edge. + """ + return _cy.is_pentagon(_in_scalar(h)) + + +def get_base_cell_number(h): + """ + Return the base cell *number* (``0`` to ``121``) of the given cell. + + The base cell *number* and the H3Index are two different representations + of the same cell: the parent cell of resolution ``0``. + + The base cell *number* is encoded within the corresponding + H3Index. + + todo: could work with edges + + Parameters + ---------- + h : H3Cell + + Returns + ------- + int + """ + return _cy.get_base_cell_number(_in_scalar(h)) + + +def are_neighbor_cells(h1, h2): + """ + Returns ``True`` if ``h1`` and ``h2`` are neighboring cells. + + Parameters + ---------- + h1 : H3Cell + h2 : H3Cell + + Returns + ------- + bool + """ + h1 = _in_scalar(h1) + h2 = _in_scalar(h2) + + return _cy.are_neighbor_cells(h1, h2) + + +def cells_to_directed_edge(origin, destination): + """ + Create an H3 Index denoting a unidirectional edge. + + The edge is constructed from neighboring cells ``origin`` and + ``destination``. + + Parameters + ---------- + origin : H3Cell + destination : H3Cell + + Raises + ------ + ValueError + When cells are not adjacent. + + Returns + ------- + H3Edge + """ + o = _in_scalar(origin) + d = _in_scalar(destination) + e = _cy.cells_to_directed_edge(o, d) + e = _out_scalar(e) + + return e + + +def get_directed_edge_origin(e): + """ + Origin cell from an H3 directed edge. + + Parameters + ---------- + e : H3Edge + + Returns + ------- + H3Cell + """ + e = _in_scalar(e) + o = _cy.get_directed_edge_origin(e) + o = _out_scalar(o) + + return o + + +def get_directed_edge_destination(e): + """ + Destination cell from an H3 directed edge. + + Parameters + ---------- + e : H3Edge + + Returns + ------- + H3Cell + """ + e = _in_scalar(e) + d = _cy.get_directed_edge_destination(e) + d = _out_scalar(d) + + return d + + +def directed_edge_to_cells(e): + """ + Return (origin, destination) tuple from H3 directed edge + + Parameters + ---------- + e : H3Edge + + Returns + ------- + H3Cell + Origin cell of edge + H3Cell + Destination cell of edge + """ + e = _in_scalar(e) + o, d = _cy.directed_edge_to_cells(e) + o, d = _out_scalar(o), _out_scalar(d) + + return o, d + + +def origin_to_directed_edges(origin): + """ + Return all directed edges starting from ``origin`` cell. + + Parameters + ---------- + origin : H3Cell + + Returns + ------- + unordered collection of H3Edge + """ + mv = _cy.origin_to_directed_edges(_in_scalar(origin)) + + return _out_unordered(mv) + + +def directed_edge_to_boundary(edge): + return _cy.directed_edge_to_boundary(_in_scalar(edge)) + + +def grid_path_cells(start, end): + """ + Returns the ordered collection of cells denoting a + minimum-length non-unique path between cells. + + Parameters + ---------- + start : H3Cell + end : H3Cell + + Returns + ------- + ordered collection of H3Cell + Starting with ``start``, and ending with ``end``. + """ + mv = _cy.grid_path_cells(_in_scalar(start), _in_scalar(end)) + + return _out_ordered(mv) + + +def is_res_class_III(h): + """ + Determine if cell has orientation "Class II" or "Class III". + + The orientation of pentagons/hexagons on the icosahedron can be one + of two types: "Class II" or "Class III". + + All cells within a resolution have the same type, and the type + alternates between resolutions. + + "Class II" cells have resolutions: 0,2,4,6,8,10,12,14 + "Class III" cells have resolutions: 1,3,5,7,9,11,13,15 + + Parameters + ---------- + h : H3Cell + + Returns + ------- + bool + ``True`` if ``h`` is "Class III". + ``False`` if ``h`` is "Class II". + + References + ---------- + 1. https://uber.github.io/h3/#/documentation/core-library/coordinate-systems + """ + return _cy.is_res_class_iii(_in_scalar(h)) + + +def get_pentagons(res): + """ + Return all pentagons at a given resolution. + + Parameters + ---------- + res : int + Resolution of the pentagons + + Returns + ------- + unordered collection of H3Cell + """ + mv = _cy.get_pentagons(res) + + return _out_unordered(mv) + + +def get_res0_cells(): + """ + Return all cells at resolution 0. + + Parameters + ---------- + None + + Returns + ------- + unordered collection of H3Cell + """ + mv = _cy.get_res0_cells() + + return _out_unordered(mv) + + +def cell_to_center_child(h, res=None): + """ + Get the center child of a cell at some finer resolution. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the child cell + If ``None``, then ``res = resolution(h) + 1`` + + Returns + ------- + H3Cell + """ + h = _in_scalar(h) + p = _cy.cell_to_center_child(h, res) + p = _out_scalar(p) + + return p + + +def get_icosahedron_faces(h): + """ + Return icosahedron faces intersecting a given H3 cell. + + There are twenty possible faces, ranging from 0--19. + + Note: Every interface returns a Python ``set`` of ``int``. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + Python ``set`` of ``int`` + """ + h = _in_scalar(h) + faces = _cy.get_icosahedron_faces(h) + + return faces + + +def cell_to_local_ij(origin, h): + """ + Return local (i,j) coordinates of cell ``h`` in relation to ``origin`` cell + + + Parameters + ---------- + origin : H3Cell + Origin/central cell for defining i,j coordinates. + h: H3Cell + Destination cell whose i,j coordinates we'd like, based off + of the origin cell. + + + Returns + ------- + Tuple (i, j) of integer local coordinates of cell ``h`` + + + Notes + ----- + + The ``origin`` cell does not define (0, 0) for the IJ coordinate space. + (0, 0) refers to the center of the base cell containing origin at the + resolution of `origin`. + Subtracting the IJ coordinates of ``origin`` from every cell would get + you the property of (0, 0) being the ``origin``. + + This is done so we don't need to keep recomputing the coordinates of + ``origin`` if not needed. + """ + origin = _in_scalar(origin) + h = _in_scalar(h) + + i, j = _cy.cell_to_local_ij(origin, h) + + return i, j + + +def local_ij_to_cell(origin, i, j): + """ + Return cell at local (i,j) position relative to the ``origin`` cell. + + Parameters + ---------- + origin : H3Cell + Origin/central cell for defining i,j coordinates. + i, j: int + Integer coordinates with respect to ``origin`` cell. + + + Returns + ------- + H3Cell at local (i,j) position relative to the ``origin`` cell + + + Notes + ----- + + The ``origin`` cell does not define (0, 0) for the IJ coordinate space. + (0, 0) refers to the center of the base cell containing origin at the + resolution of ``origin``. + Subtracting the IJ coordinates of ``origin`` from every cell would get + you the property of (0, 0) being the ``origin``. + + This is done so we don't need to keep recomputing the coordinates of + ``origin`` if not needed. + """ + origin = _in_scalar(origin) + + h = _cy.local_ij_to_cell(origin, i, j) + h = _out_scalar(h) + + return h + + +def cell_area(h, unit='km^2'): + """ + Compute the spherical surface area of a specific H3 cell. + + Parameters + ---------- + h : H3Cell + unit: str + Unit for area result (``'km^2'``, 'm^2', or 'rads^2') + + + Returns + ------- + The area of the H3 cell in the given units + + + Notes + ----- + This function breaks the cell into spherical triangles, and computes + their spherical area. + The function uses the spherical distance calculation given by + `great_circle_distance`. + """ + h = _in_scalar(h) + + return _cy.cell_area(h, unit=unit) + + +def edge_length(e, unit='km'): + """ + Compute the spherical length of a specific H3 edge. + + Parameters + ---------- + h : H3Cell + unit: str + Unit for length result ('km', 'm', or 'rads') + + + Returns + ------- + The length of the edge in the given units + + + Notes + ----- + This function uses the spherical distance calculation given by + `great_circle_distance`. + """ + e = _in_scalar(e) + + return _cy.edge_length(e, unit=unit) + + +def great_circle_distance(latlng1, latlng2, unit='km'): + """ + Compute the spherical distance between two (lat, lng) points. + AKA: great circle distance or "haversine" distance. + + todo: overload to allow two cell inputs? + + Parameters + ---------- + latlng1 : tuple + (lat, lng) tuple in degrees + latlng2 : tuple + (lat, lng) tuple in degrees + unit: str + Unit for distance result ('km', 'm', or 'rads') + + + Returns + ------- + The spherical distance between the points in the given units + """ + lat1, lng1 = latlng1 + lat2, lng2 = latlng2 + return _cy.great_circle_distance( + lat1, lng1, + lat2, lng2, + unit = unit + ) diff --git a/src/h3/api/basic_int/_binding.py b/src/h3/api/basic_int/_binding.py deleted file mode 100644 index 28002dd..0000000 --- a/src/h3/api/basic_int/_binding.py +++ /dev/null @@ -1,36 +0,0 @@ -""" -This API handles H3 Indexes of type `int`, using -basic Python collections (`set`, `list`, `tuple`). -`h3` will interpret these Indexes as unsigned 64-bit integers. - -Input collections: - -- `Iterable[int]` - -Output collections: - -- `Set[int]` for unordered -- `List[int]` for ordered -""" - -from ... import _cy -from .._api_template import _API_FUNCTIONS - - -def _id(x): - return x - - -def _in_collection(cells): - it = list(cells) - - return _cy.iter_to_mv(it) - - -_binding = _API_FUNCTIONS( - _in_scalar=_id, - _out_scalar=_id, - _in_collection=_in_collection, - _out_unordered=set, # todo: should this be an (immutable) frozenset? - _out_ordered=list, # todo: should this be an (immutable) tuple? -) diff --git a/src/h3/api/basic_int/_convert.py b/src/h3/api/basic_int/_convert.py new file mode 100644 index 0000000..48cfcb9 --- /dev/null +++ b/src/h3/api/basic_int/_convert.py @@ -0,0 +1,18 @@ +from ... import _cy + + +def _in_scalar(x): + return x + + +_out_scalar = _in_scalar + + +def _in_collection(cells): + it = list(cells) + + return _cy.iter_to_mv(it) + + +_out_unordered = set +_out_ordered = list diff --git a/src/h3/api/basic_int/_public_api.py b/src/h3/api/basic_int/_public_api.py deleted file mode 100644 index 8e87df1..0000000 --- a/src/h3/api/basic_int/_public_api.py +++ /dev/null @@ -1,63 +0,0 @@ -"""Binding of public API names to module scope - -Prior to binding the API to module scope explicitly, we dynamically modified the -`globals` object when `h3` was imported, which caused problems with static tooling not -being able to understand the H3 API. - -This file exists to avoid dynamically modifying `globals` and support static tooling. -""" -from ._binding import _binding as _b - - -is_valid_cell = _b.is_valid_cell -is_pentagon = _b.is_pentagon -is_valid_directed_edge = _b.is_valid_directed_edge -is_res_class_III = _b.is_res_class_III - -int_to_str = _b.int_to_str -str_to_int = _b.str_to_int - -cell_area = _b.cell_area -edge_length = _b.edge_length -great_circle_distance = _b.great_circle_distance -average_hexagon_area = _b.average_hexagon_area -average_hexagon_edge_length = _b.average_hexagon_edge_length - -latlng_to_cell = _b.latlng_to_cell -cell_to_latlng = _b.cell_to_latlng -cell_to_boundary = _b.cell_to_boundary -cell_to_local_ij = _b.cell_to_local_ij -local_ij_to_cell = _b.local_ij_to_cell - -grid_ring = _b.grid_ring -grid_disk = _b.grid_disk -grid_distance = _b.grid_distance -grid_path_cells = _b.grid_path_cells - -get_num_cells = _b.get_num_cells -get_pentagons = _b.get_pentagons -get_res0_cells = _b.get_res0_cells -get_resolution = _b.get_resolution -get_base_cell_number = _b.get_base_cell_number -get_icosahedron_faces = _b.get_icosahedron_faces - -cell_to_parent = _b.cell_to_parent -cell_to_children = _b.cell_to_children -cell_to_center_child = _b.cell_to_center_child -compact_cells = _b.compact_cells -uncompact_cells = _b.uncompact_cells - -h3shape_to_cells = _b.h3shape_to_cells -cells_to_h3shape = _b.cells_to_h3shape -cells_to_geo = _b.cells_to_geo -geo_to_cells = _b.geo_to_cells - -are_neighbor_cells = _b.are_neighbor_cells -cells_to_directed_edge = _b.cells_to_directed_edge -directed_edge_to_cells = _b.directed_edge_to_cells -origin_to_directed_edges = _b.origin_to_directed_edges -get_directed_edge_origin = _b.get_directed_edge_origin -get_directed_edge_destination = _b.get_directed_edge_destination -directed_edge_to_boundary = _b.directed_edge_to_boundary - -versions = _b.versions diff --git a/src/h3/api/basic_str/__init__.py b/src/h3/api/basic_str/__init__.py deleted file mode 100644 index a297461..0000000 --- a/src/h3/api/basic_str/__init__.py +++ /dev/null @@ -1,9 +0,0 @@ -# flake8: noqa -from ._public_api import * -from ..._h3shape import ( - H3MultiPoly, - H3Poly, - H3Shape, - geo_to_h3shape, - h3shape_to_geo, -) diff --git a/src/h3/api/basic_str/__init__.py b/src/h3/api/basic_str/__init__.py new file mode 120000 index 0000000..92056a2 --- /dev/null +++ b/src/h3/api/basic_str/__init__.py @@ -0,0 +1 @@ +../basic_int/__init__.py \ No newline at end of file diff --git a/src/h3/api/basic_str/_binding.py b/src/h3/api/basic_str/_binding.py deleted file mode 100644 index 4ebd5fb..0000000 --- a/src/h3/api/basic_str/_binding.py +++ /dev/null @@ -1,43 +0,0 @@ -""" -This API handles H3 Indexes of type `str`, using -basic Python collections (`set`, `list`, `tuple`). -`h3` will interpret these Indexes as hexadecimal -representations of unsigned 64-bit integers. - -Input collections: - -- `Iterable[str]` - -Output collections: - -- `Set[str]` for unordered -- `List[str]` for ordered -""" - -from ... import _cy -from .._api_template import _API_FUNCTIONS - - -def _in_collection(cells): - it = [_cy.str_to_int(h) for h in cells] - - return _cy.iter_to_mv(it) - - -def _out_unordered(mv): - # todo: should this be an (immutable) frozenset? - return set(_cy.int_to_str(h) for h in mv) - - -def _out_ordered(mv): - # todo: should this be an (immutable) tuple? - return list(_cy.int_to_str(h) for h in mv) - - -_binding = _API_FUNCTIONS( - _in_scalar = _cy.str_to_int, - _out_scalar = _cy.int_to_str, - _in_collection = _in_collection, - _out_unordered = _out_unordered, - _out_ordered = _out_ordered, -) diff --git a/src/h3/api/basic_str/_convert.py b/src/h3/api/basic_str/_convert.py new file mode 100644 index 0000000..bad3a95 --- /dev/null +++ b/src/h3/api/basic_str/_convert.py @@ -0,0 +1,20 @@ +from ... import _cy + +_in_scalar = _cy.str_to_int +_out_scalar = _cy.int_to_str + + +def _in_collection(cells): + it = [_cy.str_to_int(h) for h in cells] + + return _cy.iter_to_mv(it) + + +def _out_unordered(mv): + # todo: should this be an (immutable) frozenset? + return set(_cy.int_to_str(h) for h in mv) + + +def _out_ordered(mv): + # todo: should this be an (immutable) tuple? + return list(_cy.int_to_str(h) for h in mv) diff --git a/src/h3/api/basic_str/_public_api.py b/src/h3/api/basic_str/_public_api.py deleted file mode 120000 index c4a6ebd..0000000 --- a/src/h3/api/basic_str/_public_api.py +++ /dev/null @@ -1 +0,0 @@ -../basic_int/_public_api.py \ No newline at end of file diff --git a/src/h3/api/memview_int/__init__.py b/src/h3/api/memview_int/__init__.py deleted file mode 100644 index a297461..0000000 --- a/src/h3/api/memview_int/__init__.py +++ /dev/null @@ -1,9 +0,0 @@ -# flake8: noqa -from ._public_api import * -from ..._h3shape import ( - H3MultiPoly, - H3Poly, - H3Shape, - geo_to_h3shape, - h3shape_to_geo, -) diff --git a/src/h3/api/memview_int/__init__.py b/src/h3/api/memview_int/__init__.py new file mode 120000 index 0000000..92056a2 --- /dev/null +++ b/src/h3/api/memview_int/__init__.py @@ -0,0 +1 @@ +../basic_int/__init__.py \ No newline at end of file diff --git a/src/h3/api/memview_int/_binding.py b/src/h3/api/memview_int/_binding.py deleted file mode 100644 index 96efb77..0000000 --- a/src/h3/api/memview_int/_binding.py +++ /dev/null @@ -1,31 +0,0 @@ -""" -This API handles H3 Indexes of type `int` (specifically, `uint64`), -using Python `memoryview` objects for collections. -`h3` will interpret these Indexes as unsigned 64-bit integers. - -Input collections: - -- `memoryview[uint64]`, i.e., anything that supports the buffer protocol - - `dtype` must be `uint64`. for example, `long` will raise an error - - `list` or `set` inputs will not be accepted - -Output collections: - -- `memoryview[uint64]` for unordered -- `memoryview[uint64]` for ordered -""" - -from .._api_template import _API_FUNCTIONS - - -def _id(x): - return x - - -_binding = _API_FUNCTIONS( - _in_scalar = _id, - _out_scalar = _id, - _in_collection = _id, - _out_unordered = _id, - _out_ordered = _id, -) diff --git a/src/h3/api/memview_int/_convert.py b/src/h3/api/memview_int/_convert.py new file mode 100644 index 0000000..9145baf --- /dev/null +++ b/src/h3/api/memview_int/_convert.py @@ -0,0 +1,9 @@ +def _id(x): + return x + + +_in_scalar = _id +_out_scalar = _id +_in_collection = _id +_out_unordered = _id +_out_ordered = _id diff --git a/src/h3/api/memview_int/_public_api.py b/src/h3/api/memview_int/_public_api.py deleted file mode 120000 index c4a6ebd..0000000 --- a/src/h3/api/memview_int/_public_api.py +++ /dev/null @@ -1 +0,0 @@ -../basic_int/_public_api.py \ No newline at end of file diff --git a/src/h3/api/numpy_int/__init__.py b/src/h3/api/numpy_int/__init__.py deleted file mode 100644 index a297461..0000000 --- a/src/h3/api/numpy_int/__init__.py +++ /dev/null @@ -1,9 +0,0 @@ -# flake8: noqa -from ._public_api import * -from ..._h3shape import ( - H3MultiPoly, - H3Poly, - H3Shape, - geo_to_h3shape, - h3shape_to_geo, -) diff --git a/src/h3/api/numpy_int/__init__.py b/src/h3/api/numpy_int/__init__.py new file mode 120000 index 0000000..92056a2 --- /dev/null +++ b/src/h3/api/numpy_int/__init__.py @@ -0,0 +1 @@ +../basic_int/__init__.py \ No newline at end of file diff --git a/src/h3/api/numpy_int/_binding.py b/src/h3/api/numpy_int/_binding.py deleted file mode 100644 index c00275e..0000000 --- a/src/h3/api/numpy_int/_binding.py +++ /dev/null @@ -1,43 +0,0 @@ -""" -This API handles H3 Indexes of type `int` (specifically, `uint64`), -using `numpy.array` objects for collections. -`h3` will interpret these Indexes as unsigned 64-bit integers. - -This API is **optional**, and will only work if the -user has `numpy` installed. - -Input collections: - -- `Iterable[int]` - - works for `lists`, but not `sets` - - will attempt to convert `int` to `uint64` - - no memory copy is made if input dtype is `uint64` - -Output collections: - -- `np.ndarray[np.uint64]` for unordered -- `np.ndarray[np.uint64]` for ordered -""" - -import numpy as np - -from .._api_template import _API_FUNCTIONS - - -def _id(x): - return x - - -def _in_collection(x): - # array is copied only if dtype does not match - # `list`s should work, but not `set`s of integers - return np.asarray(x, dtype='uint64') - - -_binding = _API_FUNCTIONS( - _in_scalar = _id, - _out_scalar = _id, - _in_collection = _in_collection, - _out_unordered = np.asarray, - _out_ordered = np.asarray, -) diff --git a/src/h3/api/numpy_int/_convert.py b/src/h3/api/numpy_int/_convert.py new file mode 100644 index 0000000..2db5b14 --- /dev/null +++ b/src/h3/api/numpy_int/_convert.py @@ -0,0 +1,16 @@ +def _in_scalar(x): + return x + + +_out_scalar = _in_scalar + + +def _in_collection(x): + import numpy as np + # array is copied only if dtype does not match + # `list`s should work, but not `set`s of integers + return np.asarray(x, dtype='uint64') + + +_out_unordered = _in_collection +_out_ordered = _in_collection diff --git a/src/h3/api/numpy_int/_public_api.py b/src/h3/api/numpy_int/_public_api.py deleted file mode 120000 index c4a6ebd..0000000 --- a/src/h3/api/numpy_int/_public_api.py +++ /dev/null @@ -1 +0,0 @@ -../basic_int/_public_api.py \ No newline at end of file diff --git a/tests/polyfill/test_polygon_class.py b/tests/polyfill/test_polygon_class.py index 721eb75..ec450f5 100644 --- a/tests/polyfill/test_polygon_class.py +++ b/tests/polyfill/test_polygon_class.py @@ -35,3 +35,12 @@ def test_h3poly_len(): with pytest.raises(NotImplementedError): len(poly) + + +def test_bad_subclass(): + class H3Shoop(h3.H3Shape): + def __geo_interface__(): + pass + + with pytest.raises(ValueError): + h3.h3shape_to_cells(H3Shoop(), res=9) diff --git a/tests/test_api_bindings_match.py b/tests/test_api_bindings_match.py index 9bcb60b..ccc2a9c 100644 --- a/tests/test_api_bindings_match.py +++ b/tests/test_api_bindings_match.py @@ -3,13 +3,12 @@ import inspect def test_api_copy_match(): import h3 - import h3.api.numpy_int apis = [ - h3.api.basic_int._public_api, - h3.api.basic_str._public_api, - h3.api.memview_int._public_api, - h3.api.numpy_int._public_api, + h3.api.basic_int, + h3.api.basic_str, + h3.api.memview_int, + h3.api.numpy_int, ] api_set = {inspect.getsource(api) for api in apis} From e64ff6731b83054d9e67b7d94ef23e186dca89ef Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 9 Mar 2024 16:26:03 -0800 Subject: [PATCH 077/177] Replace _out_unordered and _out_ordered with _out_collection (#339) * Replace _out_unordered and _out_ordered with _out_collection * update batch of tests * lint * few more tests * group tests around APIs * few more tests * few more tests * couple few * final tests * test_icosahedron_faces * lint * remove redundant tests * consolidate same_set * same_set * update makefile * remove the .so files * Add note indicating that there is no guaranteed ordering of cells for many functions * bump to pypa/cibuildwheel@v2.16.5 --- .github/workflows/wheels.yml | 2 +- makefile | 4 +- src/h3/_cy/cells.pyx | 2 +- src/h3/api/basic_int/__init__.py | 61 +++++++++++---- src/h3/api/basic_int/_convert.py | 3 +- src/h3/api/basic_str/_convert.py | 8 +- src/h3/api/memview_int/_convert.py | 3 +- src/h3/api/numpy_int/_convert.py | 3 +- tests/polyfill/__init__.py | 0 tests/polyfill/test_h3.py | 18 +++-- tests/polyfill/test_polyfill.py | 21 +++-- tests/polyfill/test_polygon_class.py | 4 +- tests/polyfill/test_to_multipoly.py | 16 ++-- tests/test_apis/__init__.py | 0 .../test_api_bindings_match.py | 0 tests/{ => test_apis}/test_basic_int.py | 28 ++----- tests/{ => test_apis}/test_basic_str.py | 9 ++- .../{ => test_apis}/test_collection_inputs.py | 10 +-- tests/test_apis/test_ico_faces.py | 30 +++++++ tests/{ => test_apis}/test_memview_int.py | 17 ---- tests/{ => test_apis}/test_numpy_int.py | 23 +----- tests/test_cells_and_edges.py | 78 +++++++------------ tests/test_h3.py | 30 ++++--- tests/test_length_area.py | 14 +--- tests/util.py | 21 +++++ 25 files changed, 216 insertions(+), 189 deletions(-) create mode 100644 tests/polyfill/__init__.py create mode 100644 tests/test_apis/__init__.py rename tests/{ => test_apis}/test_api_bindings_match.py (100%) rename tests/{ => test_apis}/test_basic_int.py (55%) rename tests/{ => test_apis}/test_basic_str.py (82%) rename tests/{ => test_apis}/test_collection_inputs.py (93%) create mode 100644 tests/test_apis/test_ico_faces.py rename tests/{ => test_apis}/test_memview_int.py (60%) rename tests/{ => test_apis}/test_numpy_int.py (59%) create mode 100644 tests/util.py diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 5d4bc60..e6f9d74 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -119,7 +119,7 @@ jobs: ## Build - - uses: pypa/cibuildwheel@v2.16.2 + - uses: pypa/cibuildwheel@v2.16.5 env: CIBW_TEST_REQUIRES: pytest numpy CIBW_TEST_COMMAND: pytest {project}/tests diff --git a/makefile b/makefile index a2f59da..31b47cb 100644 --- a/makefile +++ b/makefile @@ -20,9 +20,11 @@ clear: -./env/bin/pip uninstall -y h3 -@rm -rf MANIFEST -@rm -rf annotations - -@rm -rf .pytest_cache tests/__pycache__ __pycache__ _skbuild dist .coverage + -@rm -rf .pytest_cache _skbuild dist .coverage build + -@find . -type d -name '__pycache__' | xargs rm -r -@find . -type d -name '*.egg-info' | xargs rm -r -@find . -type f -name '*.pyc' | xargs rm -r + -@find . -type f -name '*.so' | xargs rm -r -@find . -type d -name '*.ipynb_checkpoints' | xargs rm -r -@find ./tests -type f -name '*.c' | xargs rm -r diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 6a21576..64be807 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -386,7 +386,7 @@ cpdef get_icosahedron_faces(H3int h): # todo: wait? do faces start from 0 or 1? # we could do this check/processing in the int_mv object - out = {f for f in faces if f >= 0} + out = [f for f in faces if f >= 0] return out diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index a9858cb..b0c7e9b 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -13,8 +13,7 @@ from ._convert import ( _in_scalar, _out_scalar, _in_collection, - _out_unordered, - _out_ordered, + _out_collection, ) @@ -258,7 +257,7 @@ def cell_to_boundary(h): def grid_disk(h, k=1): """ - Return unordered set of cells with H3 distance ``<= k`` from ``h``. + Return unordered collection of cells with H3 distance ``<= k`` from ``h``. That is, the 'filled-in' disk. Parameters @@ -270,15 +269,19 @@ def grid_disk(h, k=1): Returns ------- unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. """ mv = _cy.grid_disk(_in_scalar(h), k) - return _out_unordered(mv) + return _out_collection(mv) def grid_ring(h, k=1): """ - Return unordered set of cells with H3 distance ``== k`` from ``h``. + Return unordered collection of cells with H3 distance ``== k`` from ``h``. That is, the "hollow" ring. Parameters @@ -290,15 +293,19 @@ def grid_ring(h, k=1): Returns ------- unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. """ mv = _cy.grid_ring(_in_scalar(h), k) - return _out_unordered(mv) + return _out_collection(mv) def cell_to_children(h, res=None): """ - Children of a cell. + Children of a cell as an unordered collection. Parameters ---------- @@ -310,10 +317,14 @@ def cell_to_children(h, res=None): Returns ------- unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. """ mv = _cy.cell_to_children(_in_scalar(h), res) - return _out_unordered(mv) + return _out_collection(mv) # todo: nogil for expensive C operation? @@ -330,12 +341,16 @@ def compact_cells(cells): Returns ------- unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. """ # todo: does compact_cells work on mixed-resolution collections? hu = _in_collection(cells) hc = _cy.compact_cells(hu) - return _out_unordered(hc) + return _out_collection(hc) def uncompact_cells(cells, res): @@ -359,11 +374,15 @@ def uncompact_cells(cells, res): todo: add test to make sure an error is returned when input contains cell smaller than output res. https://github.com/uber/h3/blob/master/src/h3lib/lib/h3Index.c#L425 + + Notes + ----- + There is currently no guaranteed order of the output cells. """ hc = _in_collection(cells) hu = _cy.uncompact_cells(hc, res) - return _out_unordered(hu) + return _out_collection(hu) def h3shape_to_cells(h3shape, res): @@ -396,6 +415,10 @@ def h3shape_to_cells(h3shape, res): '862830947ffffff', '862830957ffffff', '86283095fffffff'} + + Notes + ----- + There is currently no guaranteed order of the output cells. """ # todo: not sure if i want this dispatch logic here. maybe in the objects? @@ -410,7 +433,7 @@ def h3shape_to_cells(h3shape, res): else: raise ValueError('Unrecognized type: ' + str(type(h3shape))) - return _out_unordered(mv) + return _out_collection(mv) def cells_to_h3shape(cells, tight=True): @@ -457,6 +480,10 @@ def geo_to_cells(geo, res): Both H3Poly and H3MultiPoly implement the interface. res : int Resolution of desired output cells. + + Notes + ----- + There is currently no guaranteed order of the output cells. """ h3shape = geo_to_h3shape(geo) return h3shape_to_cells(h3shape, res) @@ -643,7 +670,7 @@ def origin_to_directed_edges(origin): """ mv = _cy.origin_to_directed_edges(_in_scalar(origin)) - return _out_unordered(mv) + return _out_collection(mv) def directed_edge_to_boundary(edge): @@ -667,7 +694,7 @@ def grid_path_cells(start, end): """ mv = _cy.grid_path_cells(_in_scalar(start), _in_scalar(end)) - return _out_ordered(mv) + return _out_collection(mv) def is_res_class_III(h): @@ -715,7 +742,7 @@ def get_pentagons(res): """ mv = _cy.get_pentagons(res) - return _out_unordered(mv) + return _out_collection(mv) def get_res0_cells(): @@ -729,10 +756,14 @@ def get_res0_cells(): Returns ------- unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. """ mv = _cy.get_res0_cells() - return _out_unordered(mv) + return _out_collection(mv) def cell_to_center_child(h, res=None): diff --git a/src/h3/api/basic_int/_convert.py b/src/h3/api/basic_int/_convert.py index 48cfcb9..51f4728 100644 --- a/src/h3/api/basic_int/_convert.py +++ b/src/h3/api/basic_int/_convert.py @@ -14,5 +14,4 @@ def _in_collection(cells): return _cy.iter_to_mv(it) -_out_unordered = set -_out_ordered = list +_out_collection = list diff --git a/src/h3/api/basic_str/_convert.py b/src/h3/api/basic_str/_convert.py index bad3a95..a6c0ba0 100644 --- a/src/h3/api/basic_str/_convert.py +++ b/src/h3/api/basic_str/_convert.py @@ -10,11 +10,5 @@ def _in_collection(cells): return _cy.iter_to_mv(it) -def _out_unordered(mv): - # todo: should this be an (immutable) frozenset? - return set(_cy.int_to_str(h) for h in mv) - - -def _out_ordered(mv): - # todo: should this be an (immutable) tuple? +def _out_collection(mv): return list(_cy.int_to_str(h) for h in mv) diff --git a/src/h3/api/memview_int/_convert.py b/src/h3/api/memview_int/_convert.py index 9145baf..2f054fd 100644 --- a/src/h3/api/memview_int/_convert.py +++ b/src/h3/api/memview_int/_convert.py @@ -5,5 +5,4 @@ def _id(x): _in_scalar = _id _out_scalar = _id _in_collection = _id -_out_unordered = _id -_out_ordered = _id +_out_collection = _id diff --git a/src/h3/api/numpy_int/_convert.py b/src/h3/api/numpy_int/_convert.py index 2db5b14..6b293cc 100644 --- a/src/h3/api/numpy_int/_convert.py +++ b/src/h3/api/numpy_int/_convert.py @@ -12,5 +12,4 @@ def _in_collection(x): return np.asarray(x, dtype='uint64') -_out_unordered = _in_collection -_out_ordered = _in_collection +_out_collection = _in_collection diff --git a/tests/polyfill/__init__.py b/tests/polyfill/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/polyfill/test_h3.py b/tests/polyfill/test_h3.py index c38ff5f..78d3223 100644 --- a/tests/polyfill/test_h3.py +++ b/tests/polyfill/test_h3.py @@ -1,6 +1,8 @@ import h3 import pytest +from .. import util as u + class MockGeoInterface: def __init__(self, dictionary): @@ -111,9 +113,12 @@ def test_polyfill_with_hole(): out = h3.h3shape_to_cells(poly, res=9) assert len(out) == 1214 - foo = lambda x: h3.h3shape_to_cells(h3.H3Poly(x), 9) - # todo: foo = lambda x: h3.H3Poly(x).to_cells(9) - assert out == foo(sf_7x7) - foo(sf_hole1) + foo = lambda x: set(h3.h3shape_to_cells(h3.H3Poly(x), 9)) + + assert u.same_set( + out, + foo(sf_7x7) - foo(sf_hole1) + ) def test_polyfill_with_two_holes(): @@ -122,8 +127,11 @@ def test_polyfill_with_two_holes(): out = h3.h3shape_to_cells(poly, 9) assert len(out) == 1172 - foo = lambda x: h3.h3shape_to_cells(h3.H3Poly(x), 9) - assert out == foo(sf_7x7) - (foo(sf_hole1) | foo(sf_hole2)) + foo = lambda x: set(h3.h3shape_to_cells(h3.H3Poly(x), 9)) + assert u.same_set( + out, + foo(sf_7x7) - (foo(sf_hole1) | foo(sf_hole2)) + ) def test_polyfill_geo_json_compliant(): diff --git a/tests/polyfill/test_polyfill.py b/tests/polyfill/test_polyfill.py index 7b059eb..541c453 100644 --- a/tests/polyfill/test_polyfill.py +++ b/tests/polyfill/test_polyfill.py @@ -3,6 +3,8 @@ import pytest from h3 import H3ResDomainError +from .. import util as u + def get_us_box_coords(): @@ -72,7 +74,7 @@ def test_h3shape_to_cells(): poly = h3.H3Poly(maine) out = h3.h3shape_to_cells(poly, 3) - assert out == expected + assert u.same_set(out, expected) def test_h3shape_to_cells2(): @@ -100,20 +102,23 @@ def test_h3shape_to_cells_holes(): for res in 1, 2, 3, 4, 5: cells_all = h3.h3shape_to_cells(h3.H3Poly(outer), res) - cells_holes = h3.h3shape_to_cells(h3.H3Poly(outer, hole1, hole2), res=res) + cells_holes = set(h3.h3shape_to_cells(h3.H3Poly(outer, hole1, hole2), res=res)) - cells_1 = h3.h3shape_to_cells(h3.H3Poly(hole1), res) - cells_2 = h3.h3shape_to_cells(h3.H3Poly(hole2), res) + cells_1 = set(h3.h3shape_to_cells(h3.H3Poly(hole1), res)) + cells_2 = set(h3.h3shape_to_cells(h3.H3Poly(hole2), res)) assert len(cells_all) == len(cells_holes) + len(cells_1) + len(cells_2) - assert cells_all == set.union(cells_holes, cells_1, cells_2) + assert u.same_set( + cells_all, + set.union(cells_holes, cells_1, cells_2) + ) def test_resolution(): poly = h3.H3Poly([]) - assert h3.h3shape_to_cells(poly, 0) == set() - assert h3.h3shape_to_cells(poly, 15) == set() + assert h3.h3shape_to_cells(poly, 0) == [] + assert h3.h3shape_to_cells(poly, 15) == [] with pytest.raises(H3ResDomainError): h3.h3shape_to_cells(poly, -1) @@ -158,4 +163,4 @@ def test_cells_to_geo(): assert len(coord[0]) == 7 assert coord[0][0] == coord[0][-1] - assert h3.geo_to_cells(geo, res) == {h} + assert h3.geo_to_cells(geo, res) == [h] diff --git a/tests/polyfill/test_polygon_class.py b/tests/polyfill/test_polygon_class.py index ec450f5..4ed7faa 100644 --- a/tests/polyfill/test_polygon_class.py +++ b/tests/polyfill/test_polygon_class.py @@ -6,8 +6,8 @@ def test_repr(): a = '8928308280fffff' b = h3.grid_ring(a, 5).pop() - cells1 = h3.grid_ring(b, 2) | {a} - cells2 = cells1 | {b} + cells1 = h3.grid_ring(b, 2) + [a] + cells2 = cells1 + [b] mpoly1 = h3.cells_to_h3shape(cells1) mpoly2 = h3.cells_to_h3shape(cells2) diff --git a/tests/polyfill/test_to_multipoly.py b/tests/polyfill/test_to_multipoly.py index e613d4d..1207da2 100644 --- a/tests/polyfill/test_to_multipoly.py +++ b/tests/polyfill/test_to_multipoly.py @@ -1,6 +1,9 @@ import h3 +from .. import util as u + + def test_cells_to_h3shape(): h = '8928308280fffff' cells = h3.grid_disk(h, 1) @@ -11,7 +14,7 @@ def test_cells_to_h3shape(): poly2 = h3.H3Poly(poly.outer, *poly.holes) out = h3.h3shape_to_cells(poly2, 9) - assert out == cells + assert u.same_set(out, cells) def test_cells_to_h3shape_tight(): @@ -22,22 +25,25 @@ def test_cells_to_h3shape_tight(): poly2 = h3.H3Poly(poly.outer, *poly.holes) out = h3.h3shape_to_cells(poly2, 9) - assert out == cells + assert u.same_set(out, cells) def test_2_polys(): h = '8928308280fffff' cells = h3.grid_ring(h, 2) - cells = cells | {h} + cells = cells + [h] # cells should be a center hex, and the 2-ring around it # (with the 1-ring being absent) mpoly = h3.cells_to_h3shape(cells) out = [ - h3.h3shape_to_cells(poly, 9) + set(h3.h3shape_to_cells(poly, 9)) for poly in mpoly ] - assert set.union(*out) == cells + assert u.same_set( + set.union(*out), + cells + ) assert set(map(len, out)) == {1, 12} diff --git a/tests/test_apis/__init__.py b/tests/test_apis/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/test_api_bindings_match.py b/tests/test_apis/test_api_bindings_match.py similarity index 100% rename from tests/test_api_bindings_match.py rename to tests/test_apis/test_api_bindings_match.py diff --git a/tests/test_basic_int.py b/tests/test_apis/test_basic_int.py similarity index 55% rename from tests/test_basic_int.py rename to tests/test_apis/test_basic_int.py index 99452fe..a567b3d 100644 --- a/tests/test_basic_int.py +++ b/tests/test_apis/test_basic_int.py @@ -1,6 +1,9 @@ import h3.api.basic_int as h3 +from .. import util as u + + def test_int_output(): lat = 37.7752702151959 lng = -122.418307270836 @@ -10,7 +13,7 @@ def test_int_output(): def test_grid_disk(): - expected = { + expected = [ 617700169957507071, 617700169957769215, 617700169958031359, @@ -18,31 +21,14 @@ def test_grid_disk(): 617700169961177087, 617700169964847103, 617700169965109247, - } + ] out = h3.grid_disk(617700169958293503, 1) - assert out == expected + assert u.same_set(out, expected) def test_compact_cells(): h = 617700169958293503 cells = h3.cell_to_children(h) - assert h3.compact_cells(cells) == {h} - - -def test_get_icosahedron_faces(): - h = 577832942814887935 - expected = {2, 3, 7, 8, 12} - out = h3.get_icosahedron_faces(h) - assert out == expected - - h = 579873636396040191 - expected = {13} - out = h3.get_icosahedron_faces(h) - assert out == expected - - h = 579768083279773695 - expected = {16, 15} - out = h3.get_icosahedron_faces(h) - assert out == expected + assert h3.compact_cells(cells) == [h] diff --git a/tests/test_basic_str.py b/tests/test_apis/test_basic_str.py similarity index 82% rename from tests/test_basic_str.py rename to tests/test_apis/test_basic_str.py index eaae35b..0c65a82 100644 --- a/tests/test_basic_str.py +++ b/tests/test_apis/test_basic_str.py @@ -1,13 +1,16 @@ import h3.api.basic_str as h3 +from .. import util as u + + def test1(): lat, lng = 37.7752702151959, -122.418307270836 assert h3.latlng_to_cell(lat, lng, 9) == '8928308280fffff' def test5(): - expected = { + expected = [ '89283082873ffff', '89283082877ffff', '8928308283bffff', @@ -15,7 +18,7 @@ def test5(): '8928308280bffff', '8928308280fffff', '89283082803ffff' - } + ] out = h3.grid_disk('8928308280fffff', 1) - assert out == expected + assert u.same_set(out, expected) diff --git a/tests/test_collection_inputs.py b/tests/test_apis/test_collection_inputs.py similarity index 93% rename from tests/test_collection_inputs.py rename to tests/test_apis/test_collection_inputs.py index 92a8ba5..5f826a1 100644 --- a/tests/test_collection_inputs.py +++ b/tests/test_apis/test_collection_inputs.py @@ -22,7 +22,7 @@ def test_set(): h = 614553222213795839 - assert basic_int.compact_cells(ints) == {h} + assert basic_int.compact_cells(ints) == [h] with pytest.raises(TypeError): # numpy can't convert from a set @@ -46,7 +46,7 @@ def test_list(): h = 614553222213795839 - assert basic_int.compact_cells(ints) == {h} + assert basic_int.compact_cells(ints) == [h] # numpy can convert from a list OK # (numpy knows to convert it to uint64) @@ -74,7 +74,7 @@ def test_np_array(): h = 614553222213795839 - assert basic_int.compact_cells(ints) == {h} + assert basic_int.compact_cells(ints) == [h] assert numpy_int.compact_cells(ints) == np.array([h], dtype='uint64') assert numpy_int.compact_cells(ints).dtype == np.dtype('uint64') @@ -99,7 +99,7 @@ def test_list_to_array(): h = 614553222213795839 - assert basic_int.compact_cells(ints) == {h} + assert basic_int.compact_cells(ints) == [h] assert numpy_int.compact_cells(ints) == np.array([h], dtype='uint64') with pytest.raises(ValueError): @@ -128,7 +128,7 @@ def test_iterator(): h = 614553222213795839 ints = foo() - assert basic_int.compact_cells(ints) == {h} + assert basic_int.compact_cells(ints) == [h] ints = foo() with pytest.raises(TypeError): diff --git a/tests/test_apis/test_ico_faces.py b/tests/test_apis/test_ico_faces.py new file mode 100644 index 0000000..6466ab0 --- /dev/null +++ b/tests/test_apis/test_ico_faces.py @@ -0,0 +1,30 @@ +import h3 + + +def test_icosahedron_faces(): + """ + get_icosahedron_faces is kind of a special case, because it always returns + a list of integers no matter the API + """ + answers = { + '804dfffffffffff': [2, 3, 7, 8, 12], + '80c1fffffffffff': [13], + '80bbfffffffffff': [15, 16], + } + + interfaces = [ + (h3.api.basic_str, lambda x: x), + (h3.api.basic_int, h3.str_to_int), + (h3.api.memview_int, h3.str_to_int), + (h3.api.numpy_int, h3.str_to_int), + ] + + for api, conv in interfaces: + for h in answers: + expected = answers[h] + + h = conv(h) # convert to int or str, depending on API + out = api.get_icosahedron_faces(h) + + assert isinstance(out, list) + assert set(out) == set(expected) diff --git a/tests/test_memview_int.py b/tests/test_apis/test_memview_int.py similarity index 60% rename from tests/test_memview_int.py rename to tests/test_apis/test_memview_int.py index 0e7e56e..0523794 100644 --- a/tests/test_memview_int.py +++ b/tests/test_apis/test_memview_int.py @@ -23,20 +23,3 @@ def test_line(): ] assert list(out) == expected - - -def test_get_icosahedron_faces(): - h = 577832942814887935 - expected = {2, 3, 7, 8, 12} - out = h3.get_icosahedron_faces(h) - assert out == expected - - h = 579873636396040191 - expected = {13} - out = h3.get_icosahedron_faces(h) - assert out == expected - - h = 579768083279773695 - expected = {16, 15} - out = h3.get_icosahedron_faces(h) - assert out == expected diff --git a/tests/test_numpy_int.py b/tests/test_apis/test_numpy_int.py similarity index 59% rename from tests/test_numpy_int.py rename to tests/test_apis/test_numpy_int.py index c565518..2ffa43f 100644 --- a/tests/test_numpy_int.py +++ b/tests/test_apis/test_numpy_int.py @@ -1,6 +1,8 @@ import h3.api.numpy_int as h3 import numpy as np # only run this test suite if numpy is installed +from .. import util as u + def test1(): lat, lng = 37.7752702151959, -122.418307270836, @@ -20,7 +22,7 @@ def test5(): out = h3.grid_disk(617700169958293503, 1) assert isinstance(out, np.ndarray) - assert set(out) == expected + assert u.same_set(out, expected) def test_compact_cells(): @@ -28,21 +30,4 @@ def test_compact_cells(): cells = h3.cell_to_children(h) assert isinstance(cells, np.ndarray) - assert set(h3.compact_cells(cells)) == {h} - - -def test_get_icosahedron_faces(): - h = 577832942814887935 - expected = {2, 3, 7, 8, 12} - out = h3.get_icosahedron_faces(h) - assert out == expected - - h = 579873636396040191 - expected = {13} - out = h3.get_icosahedron_faces(h) - assert out == expected - - h = 579768083279773695 - expected = {16, 15} - out = h3.get_icosahedron_faces(h) - assert out == expected + assert h3.compact_cells(cells) == [h] diff --git a/tests/test_cells_and_edges.py b/tests/test_cells_and_edges.py index c82c6ab..1e4c5d7 100644 --- a/tests/test_cells_and_edges.py +++ b/tests/test_cells_and_edges.py @@ -11,14 +11,7 @@ from h3 import ( ) -def approx2(a, b): - if len(a) != len(b): - return False - - return all( - x == pytest.approx(y) - for x, y in zip(a, b) - ) +from . import util as u def test1(): @@ -44,7 +37,7 @@ def test3(): ) out = h3.cell_to_boundary('8928308280fffff') - assert approx2(out, expected) + assert u.approx2(out, expected) def test_grid_disk_distance(): @@ -58,7 +51,7 @@ def test_grid_ring_distance(): def test5(): - expected = { + expected = [ '89283082873ffff', '89283082877ffff', '8928308283bffff', @@ -66,30 +59,30 @@ def test5(): '8928308280bffff', '8928308280fffff', '89283082803ffff' - } + ] out = h3.grid_disk('8928308280fffff', 1) - assert out == expected + assert u.same_set(out, expected) def test6(): - expected = {'8928308280fffff'} + expected = ['8928308280fffff'] out = h3.grid_ring('8928308280fffff', 0) - assert out == expected + assert u.same_set(out, expected) def test7(): - expected = { + expected = [ '89283082803ffff', '89283082807ffff', '8928308280bffff', '8928308283bffff', '89283082873ffff', '89283082877ffff' - } + ] out = h3.grid_ring('8928308280fffff', 1) - assert out == expected + assert u.same_set(out, expected) def test8(): @@ -149,10 +142,10 @@ def test_children(): # same resolution is set of just cell itself out = h3.cell_to_children(h, 9) - assert out == {h} + assert out == [h] # one below should give children - expected = { + expected = [ '8a28308280c7fff', '8a28308280cffff', '8a28308280d7fff', @@ -160,9 +153,9 @@ def test_children(): '8a28308280e7fff', '8a28308280effff', '8a28308280f7fff' - } + ] out = h3.cell_to_children(h, 10) - assert out == expected + assert u.same_set(out, expected) # finest resolution cell should return error for children h = '8f04ccb2c45e225' @@ -242,7 +235,7 @@ def get_maine_cells(): cells_uncomp = h3.h3shape_to_cells(poly, res=res) # the expected result from h3.compact_cells(cells_uncomp) - cells_comp = {'852b114ffffffff', '852b189bfffffff', '852b1163fffffff', '842ba9bffffffff', '842bad3ffffffff', '852ba9cffffffff', '842badbffffffff', '852b1e8bfffffff', '852a346ffffffff', '842b1e3ffffffff', '852b116ffffffff', '842b185ffffffff', '852b1bdbfffffff', '852bad47fffffff', '852ba9c3fffffff', '852b106bfffffff', '852a30d3fffffff', '842b1edffffffff', '852b12a7fffffff', '852b1027fffffff', '842baddffffffff', '852a349bfffffff', '852b1227fffffff', '852a3473fffffff', '852b117bfffffff', '842ba99ffffffff', '852a341bfffffff', '852ba9d3fffffff', '852b1067fffffff', '852a3463fffffff', '852baca7fffffff', '852b116bfffffff', '852b1c6bfffffff', '852a3493fffffff', '852ba9dbfffffff', '852b180bfffffff', '842bad7ffffffff', '852b1063fffffff', '842ba93ffffffff', '852a3693fffffff', '852ba977fffffff', '852b1e9bfffffff', '852bad53fffffff', '852b100ffffffff', '852b102bfffffff', '852a3413fffffff', '852ba8b7fffffff', '852bad43fffffff', '852b1c6ffffffff', '852a340bfffffff', '852b103bfffffff', '852b1813fffffff', '852b12affffffff', '842a34dffffffff', '852b1873fffffff', '852b106ffffffff', '852b115bfffffff', '852baca3fffffff', '852b114bfffffff', '852b1143fffffff', '852a348bfffffff', '852a30d7fffffff', '852b181bfffffff', '842a345ffffffff', '852b1e8ffffffff', '852b1883fffffff', '852b1147fffffff', '852a3483fffffff', '852b12a3fffffff', '852a346bfffffff', '852ba9d7fffffff', '842b18dffffffff', '852b188bfffffff', '852a36a7fffffff', '852bacb3fffffff', '852b187bfffffff', '852bacb7fffffff', '842b1ebffffffff', '842b1e5ffffffff', '852ba8a7fffffff', '842bad9ffffffff', '852a36b7fffffff', '852a347bfffffff', '832b13fffffffff', '852ba9c7fffffff', '832b1afffffffff', '842ba91ffffffff', '852bad57fffffff', '852ba8affffffff', '852b1803fffffff', '842b1e7ffffffff', '852bad4ffffffff', '852b102ffffffff', '852b1077fffffff', '852b1237fffffff', '852b1153fffffff', '852a3697fffffff', '852a36b3fffffff', '842bad1ffffffff', '842b1e1ffffffff', '852b186bfffffff', '852b1023fffffff'} # noqa + cells_comp = ['852b114ffffffff', '852b189bfffffff', '852b1163fffffff', '842ba9bffffffff', '842bad3ffffffff', '852ba9cffffffff', '842badbffffffff', '852b1e8bfffffff', '852a346ffffffff', '842b1e3ffffffff', '852b116ffffffff', '842b185ffffffff', '852b1bdbfffffff', '852bad47fffffff', '852ba9c3fffffff', '852b106bfffffff', '852a30d3fffffff', '842b1edffffffff', '852b12a7fffffff', '852b1027fffffff', '842baddffffffff', '852a349bfffffff', '852b1227fffffff', '852a3473fffffff', '852b117bfffffff', '842ba99ffffffff', '852a341bfffffff', '852ba9d3fffffff', '852b1067fffffff', '852a3463fffffff', '852baca7fffffff', '852b116bfffffff', '852b1c6bfffffff', '852a3493fffffff', '852ba9dbfffffff', '852b180bfffffff', '842bad7ffffffff', '852b1063fffffff', '842ba93ffffffff', '852a3693fffffff', '852ba977fffffff', '852b1e9bfffffff', '852bad53fffffff', '852b100ffffffff', '852b102bfffffff', '852a3413fffffff', '852ba8b7fffffff', '852bad43fffffff', '852b1c6ffffffff', '852a340bfffffff', '852b103bfffffff', '852b1813fffffff', '852b12affffffff', '842a34dffffffff', '852b1873fffffff', '852b106ffffffff', '852b115bfffffff', '852baca3fffffff', '852b114bfffffff', '852b1143fffffff', '852a348bfffffff', '852a30d7fffffff', '852b181bfffffff', '842a345ffffffff', '852b1e8ffffffff', '852b1883fffffff', '852b1147fffffff', '852a3483fffffff', '852b12a3fffffff', '852a346bfffffff', '852ba9d7fffffff', '842b18dffffffff', '852b188bfffffff', '852a36a7fffffff', '852bacb3fffffff', '852b187bfffffff', '852bacb7fffffff', '842b1ebffffffff', '842b1e5ffffffff', '852ba8a7fffffff', '842bad9ffffffff', '852a36b7fffffff', '852a347bfffffff', '832b13fffffffff', '852ba9c7fffffff', '832b1afffffffff', '842ba91ffffffff', '852bad57fffffff', '852ba8affffffff', '852b1803fffffff', '842b1e7ffffffff', '852bad4ffffffff', '852b102ffffffff', '852b1077fffffff', '852b1237fffffff', '852b1153fffffff', '852a3697fffffff', '852a36b3fffffff', '842bad1ffffffff', '842b1e1ffffffff', '852b186bfffffff', '852b1023fffffff'] # noqa return cells_uncomp, cells_comp, res @@ -251,13 +244,13 @@ def test_compact_cells(): cells_uncomp, cells_comp, _ = get_maine_cells() out = h3.compact_cells(cells_uncomp) - assert out == cells_comp + assert u.same_set(out, cells_comp) def test_uncompact_cells(): cells_uncomp, cells_comp, res = get_maine_cells() out = h3.uncompact_cells(cells_comp, res) - assert out == cells_uncomp + assert u.same_set(out, cells_uncomp) def test_get_num_cells(): @@ -339,7 +332,7 @@ def test_origin_to_directed_edges(): } neighbors = h3.grid_ring(h, 1) - assert neighbors == destinations + assert u.same_set(neighbors, destinations) def test_edge_boundary(): @@ -484,7 +477,7 @@ def test_edge_is_valid_fail(): def test_get_pentagons(): out = h3.get_pentagons(0) - expected = { + expected = [ '8009fffffffffff', '801dfffffffffff', '8031fffffffffff', @@ -497,13 +490,13 @@ def test_get_pentagons(): '80c3fffffffffff', '80d7fffffffffff', '80ebfffffffffff', - } + ] - assert out == expected + assert u.same_set(out, expected) out = h3.get_pentagons(5) - expected = { + expected = [ '85080003fffffff', '851c0003fffffff', '85300003fffffff', @@ -516,9 +509,9 @@ def test_get_pentagons(): '85c20003fffffff', '85d60003fffffff', '85ea0003fffffff', - } + ] - assert out == expected + assert u.same_set(out, expected) for i in range(16): assert len(h3.get_pentagons(i)) == 12 @@ -541,7 +534,7 @@ def test_get_res0_cells(): # subset pentagons = h3.get_pentagons(0) - assert pentagons < out + assert set(pentagons) < set(out) # all valid assert all(map(h3.is_valid_cell, out)) @@ -558,24 +551,7 @@ def test_get_res0_cells(): '8003fffffffffff', '8005fffffffffff', } - assert sub < out - - -def test_get_icosahedron_faces(): - h = '804dfffffffffff' - expected = {2, 3, 7, 8, 12} - out = h3.get_icosahedron_faces(h) - assert out == expected - - h = '80c1fffffffffff' - expected = {13} - out = h3.get_icosahedron_faces(h) - assert out == expected - - h = '80bbfffffffffff' - expected = {16, 15} - out = h3.get_icosahedron_faces(h) - assert out == expected + assert sub < set(out) def test_to_local_ij_error(): @@ -613,7 +589,7 @@ def test_from_local_ij_error(): for i, j in goodies } - assert out == nb + assert u.same_set(out, nb) def test_to_local_ij_self(): diff --git a/tests/test_h3.py b/tests/test_h3.py index 94a9a94..a7fc415 100644 --- a/tests/test_h3.py +++ b/tests/test_h3.py @@ -3,6 +3,8 @@ from pytest import approx import h3 +from . import util as u + def test_is_valid_cell(): assert h3.is_valid_cell('85283473fffffff') @@ -77,7 +79,7 @@ def test_grid_disk(): '8928308283bffff', } - assert out == expected + assert u.same_set(out, expected) def test_grid_disk2(): @@ -108,7 +110,7 @@ def test_grid_disk2(): '8928308280bffff', } - assert out == expected + assert u.same_set(out, expected) def test_grid_disk_pentagon(): @@ -126,7 +128,7 @@ def test_grid_disk_pentagon(): '821c37fffffffff', } - assert out == expected + assert u.same_set(out, expected) def test_grid_ring(): @@ -141,8 +143,11 @@ def test_grid_ring(): '8928308283bffff', } - assert out == expected - assert out == h3.grid_disk(h, 1) - h3.grid_disk(h, 0) + assert u.same_set(out, expected) + assert u.same_set( + out, + set(h3.grid_disk(h, 1)) - set(h3.grid_disk(h, 0)) + ) def test_grid_ring2(): @@ -164,8 +169,11 @@ def test_grid_ring2(): '89283082867ffff', } - assert out == expected - assert out == h3.grid_disk(h, 2) - h3.grid_disk(h, 1) + assert u.same_set(out, expected) + assert u.same_set( + out, + set(h3.grid_disk(h, 2)) - set(h3.grid_disk(h, 1)) + ) def test_grid_ring_pentagon(): @@ -180,7 +188,7 @@ def test_grid_ring_pentagon(): '821c37fffffffff', } - assert out == expected + assert u.same_set(out, expected) def test_compact_and_uncompact_cells(): @@ -202,12 +210,12 @@ def test_compact_and_uncompact_cells(): uncompact_cells = h3.uncompact_cells(compact_cells, 9) assert len(uncompact_cells) == 1253 - assert uncompact_cells == cells + assert u.same_set(uncompact_cells, cells) def test_compact_cells_and_uncompact_cells_nothing(): - assert h3.compact_cells([]) == set() - assert h3.uncompact_cells([], 9) == set() + assert h3.compact_cells([]) == [] + assert h3.uncompact_cells([], 9) == [] def test_uncompact_cells_error(): diff --git a/tests/test_length_area.py b/tests/test_length_area.py index 8851a4b..1003f56 100644 --- a/tests/test_length_area.py +++ b/tests/test_length_area.py @@ -1,15 +1,7 @@ import h3 import pytest - -def approx2(a, b): - if len(a) != len(b): - return False - - return all( - x == pytest.approx(y) - for x, y in zip(a, b) - ) +from . import util as u def cell_perimiter1(h, unit='km'): @@ -65,7 +57,7 @@ def test_areas_at_00(): for r in range(16) ] - assert approx2(out, areas_km2) + assert u.approx2(out, areas_km2) areas_rads2 = [ 6.312389871006786335e-02, @@ -91,7 +83,7 @@ def test_areas_at_00(): for r in range(16) ] - assert approx2(out, areas_rads2) + assert u.approx2(out, areas_rads2) def test_bad_units(): diff --git a/tests/util.py b/tests/util.py new file mode 100644 index 0000000..f6d3177 --- /dev/null +++ b/tests/util.py @@ -0,0 +1,21 @@ +import pytest + + +def same_set(a, b): + """Test if two collections are the same if taken as sets""" + set_a = set(a) + set_b = set(b) + + assert len(a) == len(b) == len(set_a) == len(set_b) + + return set_a == set_b + + +def approx2(a, b): + if len(a) != len(b): + return False + + return all( + x == pytest.approx(y) + for x, y in zip(a, b) + ) From 946f6988672bf55c0f7778ff35ea24ff78cd9ec8 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 9 Mar 2024 17:08:01 -0800 Subject: [PATCH 078/177] trying 3.12 wheels and tests (#347) --- .github/workflows/tests.yml | 2 +- .github/workflows/wheels.yml | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index a5b4fec..9e68286 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -14,7 +14,7 @@ jobs: strategy: matrix: os: [macos-latest, windows-latest, ubuntu-20.04] - python-version: ['3.6', '3.7', '3.8', '3.9', '3.10', '3.11'] + python-version: ['3.6', '3.7', '3.8', '3.9', '3.10', '3.11', '3.12'] steps: - uses: actions/checkout@v3 diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index e6f9d74..2b4fa4f 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -93,6 +93,9 @@ jobs: - os: ubuntu-20.04 build: 'cp311-manylinux_aarch64' name: Linux Aarch64 3.11 + - os: ubuntu-20.04 + build: 'cp312-manylinux_aarch64' + name: Linux Aarch64 3.12 steps: - uses: actions/checkout@v3 From eda61ba78f2fb8a179f6ed04c016f4110afea022 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 10 Mar 2024 17:58:25 -0700 Subject: [PATCH 079/177] update actions (#348) * update action to actions/setup-python@v5.0.0 * to actions/upload-artifact@v4.3.1 * to codecov/codecov-action@v4.1.0 * to actions/checkout@v4.1.1 * Revert "to codecov/codecov-action@v4.1.0" This reverts commit 353f48f1b62bf4a4a9c688d26a80e2dbf8d2ddf7. * Revert "to actions/upload-artifact@v4.3.1" This reverts commit b6c6a00586a1df5d9b3cb233d2f705abbe95d920. * ilammy/msvc-dev-cmd@v1.13.0 * docker/setup-qemu-action@v3.0.0 * ubuntu-22.04 * drop 3.6 * peaceiris/actions-gh-pages@v3.9.3 * Revert "Revert "to codecov/codecov-action@v4.1.0"" This reverts commit 63d8eb22d3e6d26c18b4e43699b744e6d1144f12. * Revert "Revert "Revert "to codecov/codecov-action@v4.1.0""" This reverts commit a55a14883b1890135e25aa9001ee9239930b1f2e. --- .github/workflows/coverage-lint.yml | 4 ++-- .github/workflows/deploy_docs.yml | 8 +++---- .github/workflows/tests.yml | 10 ++++----- .github/workflows/wheels.yml | 33 +++++++++++++---------------- 4 files changed, 26 insertions(+), 29 deletions(-) diff --git a/.github/workflows/coverage-lint.yml b/.github/workflows/coverage-lint.yml index 878239a..a423277 100644 --- a/.github/workflows/coverage-lint.yml +++ b/.github/workflows/coverage-lint.yml @@ -12,11 +12,11 @@ jobs: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4.1.1 with: submodules: recursive - - uses: actions/setup-python@v4.5.0 + - uses: actions/setup-python@v5.0.0 with: python-version: 3.11 diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml index c3a4c3e..ceec196 100644 --- a/.github/workflows/deploy_docs.yml +++ b/.github/workflows/deploy_docs.yml @@ -11,14 +11,14 @@ on: jobs: build-docs: name: Build docs - runs-on: ubuntu-20.04 + runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4.1.1 with: submodules: recursive - - uses: actions/setup-python@v4.5.0 + - uses: actions/setup-python@v5.0.0 with: python-version: 3.11 @@ -42,7 +42,7 @@ jobs: # Deploy the book's HTML to gh-pages branch - name: GitHub Pages action - uses: peaceiris/actions-gh-pages@v3.7.3 + uses: peaceiris/actions-gh-pages@v3.9.3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: docs/_build/html diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 9e68286..0d4b58f 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -13,20 +13,20 @@ jobs: strategy: matrix: - os: [macos-latest, windows-latest, ubuntu-20.04] - python-version: ['3.6', '3.7', '3.8', '3.9', '3.10', '3.11', '3.12'] + os: [macos-latest, windows-latest, ubuntu-22.04] + python-version: ['3.7', '3.8', '3.9', '3.10', '3.11', '3.12'] steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4.1.1 with: submodules: recursive - - uses: actions/setup-python@v4.5.0 + - uses: actions/setup-python@v5.0.0 with: python-version: '${{ matrix.python-version }}' ## Start Windows stuff - - uses: ilammy/msvc-dev-cmd@v1.12.0 + - uses: ilammy/msvc-dev-cmd@v1.13.0 if: startsWith(matrix.os, 'windows') - name: Set Windows Compiler diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 2b4fa4f..393d357 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -25,15 +25,15 @@ jobs: strategy: matrix: - os: [ubuntu-20.04] + os: [ubuntu-22.04] steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4.1.1 with: submodules: recursive - name: Setup Python - uses: actions/setup-python@v4.5.0 + uses: actions/setup-python@v5.0.0 - name: Make sdist run: | @@ -69,42 +69,39 @@ jobs: - os: windows-latest build: 'cp3*-win_amd64' name: Windows 64-bit - - os: ubuntu-20.04 + - os: ubuntu-22.04 build: 'cp*-manylinux_x86_64' name: Linux Intel glibc 64-bit - - os: ubuntu-20.04 + - os: ubuntu-22.04 build: 'cp*-musllinux_x86_64' name: Linux Intel musl 64-bit - - os: ubuntu-20.04 - build: 'cp36-manylinux_aarch64' - name: Linux Aarch64 3.6 - - os: ubuntu-20.04 + - os: ubuntu-22.04 build: 'cp37-manylinux_aarch64' name: Linux Aarch64 3.7 - - os: ubuntu-20.04 + - os: ubuntu-22.04 build: 'cp38-manylinux_aarch64' name: Linux Aarch64 3.8 - - os: ubuntu-20.04 + - os: ubuntu-22.04 build: 'cp39-manylinux_aarch64' name: Linux Aarch64 3.9 - - os: ubuntu-20.04 + - os: ubuntu-22.04 build: 'cp310-manylinux_aarch64' name: Linux Aarch64 3.10 - - os: ubuntu-20.04 + - os: ubuntu-22.04 build: 'cp311-manylinux_aarch64' name: Linux Aarch64 3.11 - - os: ubuntu-20.04 + - os: ubuntu-22.04 build: 'cp312-manylinux_aarch64' name: Linux Aarch64 3.12 steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4.1.1 with: submodules: recursive ## Setup Env - - uses: ilammy/msvc-dev-cmd@v1.12.0 + - uses: ilammy/msvc-dev-cmd@v1.13.0 if: runner.os == 'Windows' - name: Set Windows variables @@ -116,7 +113,7 @@ jobs: - name: Set up QEMU if: runner.os == 'Linux' - uses: docker/setup-qemu-action@v2.1.0 + uses: docker/setup-qemu-action@v3.0.0 with: platforms: aarch64 @@ -142,7 +139,7 @@ jobs: upload_all: needs: [make_sdist, make_cibw_v2_wheels] - runs-on: ubuntu-20.04 + runs-on: ubuntu-22.04 if: github.event_name == 'release' && github.event.action == 'published' steps: From bc9e8857a97336168c3aebcaee179354d0cda275 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim=20S=C3=BCll?= Date: Tue, 12 Mar 2024 03:26:56 +0100 Subject: [PATCH 080/177] Moved cython tests to own folder (#349) * fix: moved cython_example.pyx and test_cython.py tests to their own folder * updated test.yml and makefile * fix: updated coverage-lint.yml to match new path * fix: all *.c files in tests/ folder and subfolders of tests/ will now be ignored --------- Co-authored-by: Tim S --- .github/workflows/coverage-lint.yml | 2 +- .github/workflows/tests.yml | 2 +- .gitignore | 2 +- makefile | 2 +- tests/test_cython/__init__.py | 0 tests/{ => test_cython}/cython_example.pyx | 0 tests/{ => test_cython}/test_cython.py | 0 7 files changed, 4 insertions(+), 4 deletions(-) create mode 100644 tests/test_cython/__init__.py rename tests/{ => test_cython}/cython_example.pyx (100%) rename tests/{ => test_cython}/test_cython.py (100%) diff --git a/.github/workflows/coverage-lint.yml b/.github/workflows/coverage-lint.yml index a423277..7f3c181 100644 --- a/.github/workflows/coverage-lint.yml +++ b/.github/workflows/coverage-lint.yml @@ -36,7 +36,7 @@ jobs: - name: Coverage run: | pip install Cython - cythonize -i tests/cython_example.pyx + cythonize -i tests/test_cython/cython_example.pyx pytest --cov=h3 --full-trace --cov-report=xml - name: Upload coverage to Codecov diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 0d4b58f..45f007f 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -44,5 +44,5 @@ jobs: - name: Tests run: | pip install Cython - cythonize -i tests/cython_example.pyx + cythonize -i tests/test_cython/cython_example.pyx pytest tests --cov=h3 --full-trace diff --git a/.gitignore b/.gitignore index 5bd718f..8b6903b 100644 --- a/.gitignore +++ b/.gitignore @@ -4,7 +4,7 @@ h3c/ h3/out/ # Generated C code from Cython test -tests/*.c +tests/**/*.c # Cython HTML annotations *.html diff --git a/makefile b/makefile index 31b47cb..56b97d9 100644 --- a/makefile +++ b/makefile @@ -39,7 +39,7 @@ annotations: rebuild cp _skbuild/*/cmake-build/src/h3/_cy/*.html ./annotations test: - ./env/bin/cythonize -i tests/cython_example.pyx + ./env/bin/cythonize -i tests/test_cython/cython_example.pyx ./env/bin/pytest tests --cov=h3 --cov-report term-missing --durations=10 lint: diff --git a/tests/test_cython/__init__.py b/tests/test_cython/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/cython_example.pyx b/tests/test_cython/cython_example.pyx similarity index 100% rename from tests/cython_example.pyx rename to tests/test_cython/cython_example.pyx diff --git a/tests/test_cython.py b/tests/test_cython/test_cython.py similarity index 100% rename from tests/test_cython.py rename to tests/test_cython/test_cython.py From 89c3720e13ac9a7b7de266788699d08c87b25634 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Tue, 12 Mar 2024 13:43:50 -0700 Subject: [PATCH 081/177] Prep for v4.0.0b3 release (#351) --- CHANGELOG.md | 8 ++++++++ src/h3/_version.py | 6 ++---- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7fb30c6..694ca05 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,14 @@ avoid adding features or APIs which do not map onto the - None +## [4.0.0b3] - 2024-03-11 + +- Change supported Python versions to 3.7, 3.8, 3.9, 3.10, 3.11, 3.12 (#324, #325, #347, #348) +- New `h3.Polygon()`/GeoJSON interface (#301) +- Use functions instead of methods for the interface functions (#334) +- Use `list` instead of `set` for unordered Python outputs (#339) + + ## [4.0.0b2] - 2022-11-23 - Build Python 3.11 wheels (#297) diff --git a/src/h3/_version.py b/src/h3/_version.py index 56fe687..6f94cfb 100644 --- a/src/h3/_version.py +++ b/src/h3/_version.py @@ -1,4 +1,4 @@ -__version__ = '4.0.0b2' +__version__ = '4.0.0b3' __description__ = 'Hierarchical hexagonal geospatial indexing system' __url__ = 'https://github.com/uber/h3-py' __license__ = 'Apache 2.0 License' @@ -11,14 +11,12 @@ __classifiers__ = [ 'License :: OSI Approved :: Apache Software License', 'Programming Language :: C', 'Programming Language :: Cython', - 'Programming Language :: Python :: 2.7', - 'Programming Language :: Python :: 3.5', - 'Programming Language :: Python :: 3.6', 'Programming Language :: Python :: 3.7', 'Programming Language :: Python :: 3.8', 'Programming Language :: Python :: 3.9', 'Programming Language :: Python :: 3.10', 'Programming Language :: Python :: 3.11', + 'Programming Language :: Python :: 3.12', 'Operating System :: MacOS :: MacOS X', 'Operating System :: POSIX :: Linux', 'Operating System :: Microsoft :: Windows', From c09c43ef0ae652f0ea52647940dd7c5ea25da8cd Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 14 Apr 2024 09:36:07 -0700 Subject: [PATCH 082/177] Update docs to include polygon tutorial (#355) * docs building correctly again * drop beta announcement * cleaning up docs a bit * i think this is where it was at... * bump beta in readme announcement * update action * pssssst. it's a secret * separate upload docs step * setps taken * want --warningiserror * need requirements for notebook * no need to run linter here * does this default thing work? * alas, chatgpt led me astray * gimme an artifact to check * bump to actions/upload-artifact@v4.3.1 * slightly better names * artifacts need names now * set python version for sdist * try this one * all unique names * try cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }} * try merge action * try combining sdist and wheels into single result * upload should work * bump to pypa/gh-action-pypi-publish@v1.8.14 * try pypa/cibuildwheel@v2.17.0 * Revert "try pypa/cibuildwheel@v2.17.0" This reverts commit fa8f7c9ab36ae093c66b087b9ba672d0fa67541c. * SDist doesn't need a strategy matrix * shorten names for cibw * bump actions/download-artifact@v4.1.4 --- .github/workflows/build_docs.yml | 47 ++++++++++++++++++++++++++++ .github/workflows/coverage-lint.yml | 6 ++-- .github/workflows/deploy_docs.yml | 48 ----------------------------- .github/workflows/wheels.yml | 44 ++++++++++++++++---------- CHANGELOG.md | 4 ++- docs/_toc.yml | 29 +++++------------ docs/api_comparison.md | 2 +- docs/api_reference.md | 4 +-- docs/polygon_tutorial.ipynb | 4 +-- docs/project_links.md | 19 ++++++++++++ makefile | 1 + readme.md | 6 ++-- 12 files changed, 117 insertions(+), 97 deletions(-) create mode 100644 .github/workflows/build_docs.yml delete mode 100644 .github/workflows/deploy_docs.yml create mode 100644 docs/project_links.md diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml new file mode 100644 index 0000000..f66ad46 --- /dev/null +++ b/.github/workflows/build_docs.yml @@ -0,0 +1,47 @@ +name: build_docs + +on: + push: + branches: [master] + pull_request: + branches: ['*'] + +jobs: + build-docs: + runs-on: ubuntu-22.04 + + steps: + - uses: actions/checkout@v4.1.1 + with: + submodules: recursive + + - uses: actions/setup-python@v5.0.0 + with: + python-version: 3.11 + + - name: Install dependencies + run: | + pip install --upgrade pip setuptools wheel + pip install -r requirements.in + pip install -r requirements-dev.txt + pip install .[all] + + - name: Build the book + run: jupyter-book build docs/ --warningiserror --keep-going --all + + - name: Upload artifacts to GitHub + uses: actions/upload-artifact@v4.3.1 + with: + name: html + path: docs/_build/html + + deploy-docs: + needs: [build-docs] + runs-on: ubuntu-22.04 + if: github.event.pull_request.merged + + steps: + - uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/_build/html diff --git a/.github/workflows/coverage-lint.yml b/.github/workflows/coverage-lint.yml index 7f3c181..24ec82e 100644 --- a/.github/workflows/coverage-lint.yml +++ b/.github/workflows/coverage-lint.yml @@ -40,10 +40,11 @@ jobs: pytest --cov=h3 --full-trace --cov-report=xml - name: Upload coverage to Codecov - uses: codecov/codecov-action@v3.0.0 + uses: codecov/codecov-action@v4.3.0 with: file: ./coverage.xml fail_ci_if_error: true + token: ${{ secrets.CODECOV_TOKEN }} - name: Copy Cython annotations to project dir run: | @@ -51,6 +52,7 @@ jobs: cp _skbuild/*/cmake-build/src/h3/_cy/*.html ./annotations - name: Upload artifacts to GitHub - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4.3.1 with: + name: annotations path: ./annotations diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml deleted file mode 100644 index ceec196..0000000 --- a/.github/workflows/deploy_docs.yml +++ /dev/null @@ -1,48 +0,0 @@ -name: deploy_docs - -# todo: we want to build on PRs, but keep it from pushing to deploy... - -on: - push: - branches: - - master - -# This job installs dependencies, builds the book, and pushes it to `gh-pages` -jobs: - build-docs: - name: Build docs - runs-on: ubuntu-22.04 - - steps: - - uses: actions/checkout@v4.1.1 - with: - submodules: recursive - - - uses: actions/setup-python@v5.0.0 - with: - python-version: 3.11 - - - name: Install dependencies - run: | - pip install --upgrade pip setuptools wheel - pip install -r requirements.in - pip install .[all] - - - name: Lint - # run: flake8 --ignore=E501 h3.py - run: flake8 src/h3 - - # Build the book - - name: Build the book - # turn off warningiserror just for https://github.com/uber/h3-py/pull/283 - # jupyter-book build docs/ --warningiserror --keep-going --all - run: | - jupyter-book build docs/ --keep-going --all - - - # Deploy the book's HTML to gh-pages branch - - name: GitHub Pages action - uses: peaceiris/actions-gh-pages@v3.9.3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: docs/_build/html diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 393d357..828699b 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -19,13 +19,8 @@ on: jobs: make_sdist: - name: 'SDist: ${{ matrix.os }}' if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }} - runs-on: ${{ matrix.os }} - - strategy: - matrix: - os: [ubuntu-22.04] + runs-on: ubuntu-22.04 steps: - uses: actions/checkout@v4.1.1 @@ -34,6 +29,8 @@ jobs: - name: Setup Python uses: actions/setup-python@v5.0.0 + with: + python-version: 3.11 - name: Make sdist run: | @@ -52,12 +49,13 @@ jobs: run: pytest --cov=h3 --full-trace - name: Upload artifacts to GitHub - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4.3.1 with: + name: temp_result_sdist path: ./dist - make_cibw_v2_wheels: - name: 'cibuildwheel v2: ${{ matrix.name }}' + make_wheels: + name: 'cibuildwheel: ${{ matrix.name }}' if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }} runs-on: ${{ matrix.os }} strategy: @@ -133,21 +131,35 @@ jobs: pipx run twine check wheelhouse/* - name: Upload artifacts to GitHub - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4.3.1 with: + name: temp_result_${{ matrix.os }}-${{ strategy.job-index }} path: wheelhouse/*.whl - upload_all: - needs: [make_sdist, make_cibw_v2_wheels] - runs-on: ubuntu-22.04 + merge: + needs: [make_sdist, make_wheels] + runs-on: ubuntu-latest + steps: + - name: Merge Artifacts + uses: actions/upload-artifact/merge@v4 + with: + name: wheels_and_sdist + pattern: temp_result_* + delete-merged: true + retention-days: 7 + compression-level: 9 + + to_pypi: + needs: [merge] if: github.event_name == 'release' && github.event.action == 'published' + runs-on: ubuntu-latest steps: - - uses: actions/download-artifact@v3 + - uses: actions/download-artifact@v4.1.4 with: - name: artifact + name: wheels_and_sdist path: dist - - uses: pypa/gh-action-pypi-publish@v1.5.1 + - uses: pypa/gh-action-pypi-publish@v1.8.14 with: password: ${{ secrets.pypi_password }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 694ca05..1d38898 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,6 @@ -# Versioning +# CHANGELOG + +## Versioning The H3 core library adheres to [Semantic Versioning](http://semver.org/). H3-Py has a `major.minor.patch` version scheme. The major and minor version diff --git a/docs/_toc.yml b/docs/_toc.yml index 9d53f89..9ebe618 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -4,31 +4,16 @@ format: jb-book root: intro parts: -- caption: Getting started +- caption: h3-py chapters: - file: api_comparison - file: api_reference + - file: polygon_tutorial -- caption: Contributing +- caption: Sundries chapters: - - file: contributing - # - file: jupyter_book_notes - file: _changelog - title: Change log - -- caption: External links - chapters: - - url: https://github.com/uber/h3-py-notebooks - title: Example Notebooks - - url: https://h3geo.org/ - title: H3 Project Homepage - - url: https://github.com/uber/h3-py - title: h3-py on GitHub - - url: https://github.com/uber/h3 - title: H3 on GitHub - - url: https://github.com/uber/h3/discussions - title: GitHub Discussions - - url: https://stackoverflow.com/questions/tagged/h3 - title: H3 Stack Overflow - - url: https://join.slack.com/t/h3-core/shared_invite/zt-g6u5r1hf-W_~uVJmfeiWtMQuBGc1NNg - title: H3 Slack + title: CHANGELOG + - file: contributing + - file: project_links + title: Project Links diff --git a/docs/api_comparison.md b/docs/api_comparison.md index e3ce64b..6abfc80 100644 --- a/docs/api_comparison.md +++ b/docs/api_comparison.md @@ -1,4 +1,4 @@ -# API comparison +# API Comparison The `h3-py` library provides several APIs which share the same functions, but differ in their input and output types: diff --git a/docs/api_reference.md b/docs/api_reference.md index 526c85b..e11e8b0 100644 --- a/docs/api_reference.md +++ b/docs/api_reference.md @@ -1,4 +1,4 @@ -# API reference +# API Reference This page lists the functions that are common to each of the [provided APIs](api_comparison). @@ -59,8 +59,6 @@ Functions relating H3 objects to geographic (lat/lng) coordinates. average_hexagon_edge_length cell_to_boundary directed_edge_to_boundary - polygon_to_cells - cells_to_polygons ``` ### Hierarchical relationships diff --git a/docs/polygon_tutorial.ipynb b/docs/polygon_tutorial.ipynb index fde0ce2..c5efd91 100644 --- a/docs/polygon_tutorial.ipynb +++ b/docs/polygon_tutorial.ipynb @@ -5,7 +5,7 @@ "id": "03ee1f11-7a60-4761-aaf7-673ea04e7dca", "metadata": {}, "source": [ - "# H3 and (Multi)Polygons\n", + "# Polygon Tutorial\n", "\n", "`h3-py` can convert between sets of cells and GeoJSON-like polygon and multipolygon shapes.\n", "\n", @@ -928,7 +928,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.1" + "version": "3.11.2" } }, "nbformat": 4, diff --git a/docs/project_links.md b/docs/project_links.md new file mode 100644 index 0000000..d9f9d63 --- /dev/null +++ b/docs/project_links.md @@ -0,0 +1,19 @@ +# Project Links + +## H3 + +Links for the overall H3 project including the core C library and all language bindings (including +Python!). + +- [H3 Project Homepage](https://h3geo.org/) +- [H3 on GitHub](https://github.com/uber/h3) +- [H3 Project GitHub Discussions](https://github.com/uber/h3/discussions) +- [H3 on Stack Overflow](https://stackoverflow.com/questions/tagged/h3) +- [H3 on Slack](https://join.slack.com/t/h3-core/shared_invite/zt-g6u5r1hf-W_~uVJmfeiWtMQuBGc1NNg) + +## h3-py + +Links specific to the H3 Python bindings. + +- [Example Notebooks](https://github.com/uber/h3-py-notebooks) +- [h3-py on GitHub](https://github.com/uber/h3-py) diff --git a/makefile b/makefile index 56b97d9..22b80e5 100644 --- a/makefile +++ b/makefile @@ -4,6 +4,7 @@ PYTHON=$(shell command -v python || command -v python3) build-docs: + ./env/bin/pip install -r requirements-dev.txt ./env/bin/jupyter-book build docs/ --warningiserror --keep-going --all open: diff --git a/readme.md b/readme.md index eab09ad..d4142be 100644 --- a/readme.md +++ b/readme.md @@ -13,11 +13,12 @@ [![Tests](https://github.com/uber/h3-py/workflows/tests/badge.svg)](https://github.com/uber/h3-py/actions) [![codecov](https://codecov.io/gh/uber/h3-py/branch/master/graph/badge.svg)](https://codecov.io/gh/uber/h3-py) + ---- -### ANNOUNCEMENT: v4.0.0 beta released! +## ANNOUNCEMENT: v4.0.0 beta released! Install the latest beta version with `pip install h3 --pre` or with -`pip install 'h3==4.0.0b2'`.
+`pip install 'h3==4.0.0b3'`.
Feedback is welcome via [Issues](https://github.com/uber/h3-py/issues/new), [Discussions](https://github.com/uber/h3/discussions), @@ -26,6 +27,7 @@ and ---- + Python bindings for the [H3 core library](https://h3geo.org/). - Documentation: [uber.github.io/h3-py](https://uber.github.io/h3-py) From 0a588ebef92eda5a0dc4c8fca1aec9f3b7cf3423 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 14 Apr 2024 10:38:11 -0700 Subject: [PATCH 083/177] release to test PyPI upload works after artifact changes (#360) * release to test PyPI upload works after artifact changes * PR for context --- CHANGELOG.md | 4 ++++ src/h3/_version.py | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d38898..011db49 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ avoid adding features or APIs which do not map onto the - None +## [4.0.0b4] - 2024-04-14 + +No changes, just testing: #360 + ## [4.0.0b3] - 2024-03-11 - Change supported Python versions to 3.7, 3.8, 3.9, 3.10, 3.11, 3.12 (#324, #325, #347, #348) diff --git a/src/h3/_version.py b/src/h3/_version.py index 6f94cfb..fd4db08 100644 --- a/src/h3/_version.py +++ b/src/h3/_version.py @@ -1,4 +1,4 @@ -__version__ = '4.0.0b3' +__version__ = '4.0.0b4' __description__ = 'Hierarchical hexagonal geospatial indexing system' __url__ = 'https://github.com/uber/h3-py' __license__ = 'Apache 2.0 License' From b0fe56772df85955b58b4ed58ee94884e1bed40d Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 14 Apr 2024 11:41:10 -0700 Subject: [PATCH 084/177] Fix docs upload (#361) * try to fix deploy docs step * should run just on a PR like this * try it without the separate step * do it as a step instead of a separate job --- .github/workflows/build_docs.yml | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index f66ad46..0ad48ba 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -29,19 +29,15 @@ jobs: - name: Build the book run: jupyter-book build docs/ --warningiserror --keep-going --all - - name: Upload artifacts to GitHub + - name: Upload artifacts uses: actions/upload-artifact@v4.3.1 with: name: html path: docs/_build/html - deploy-docs: - needs: [build-docs] - runs-on: ubuntu-22.04 - if: github.event.pull_request.merged - - steps: - - uses: peaceiris/actions-gh-pages@v4 + - name: Upload to GitHub Pages + uses: peaceiris/actions-gh-pages@v4 + if: github.ref == 'refs/heads/master' with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: docs/_build/html From cd59584b8321259f5230e2588c4306744c208ef0 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Mon, 15 Apr 2024 15:06:36 -0700 Subject: [PATCH 085/177] update cibw (#359) * docs building correctly again * drop beta announcement * cleaning up docs a bit * i think this is where it was at... * bump beta in readme announcement * update action * pssssst. it's a secret * separate upload docs step * setps taken * want --warningiserror * need requirements for notebook * no need to run linter here * does this default thing work? * alas, chatgpt led me astray * gimme an artifact to check * bump to actions/upload-artifact@v4.3.1 * slightly better names * artifacts need names now * set python version for sdist * try this one * all unique names * try cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }} * try merge action * try combining sdist and wheels into single result * upload should work * bump to pypa/gh-action-pypi-publish@v1.8.14 * try pypa/cibuildwheel@v2.17.0 * Revert "try pypa/cibuildwheel@v2.17.0" This reverts commit fa8f7c9ab36ae093c66b087b9ba672d0fa67541c. * SDist doesn't need a strategy matrix * shorten names for cibw * bump actions/download-artifact@v4.1.4 * bump pypa/cibuildwheel@v2.17.0 * . * shouldn't need CIBW_SKIP * keep intermediate results for comparison for now * see if that gets us building the correct subset * formatting * split up musllinux because it currently takes 20 minutes * can still include cp36-manylinux_aarch64 * delete-merged * test dropping CIBW_ARCHS_MACOS --- .github/workflows/wheels.yml | 48 ++++++++++++++++++++++++++---------- 1 file changed, 35 insertions(+), 13 deletions(-) diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 828699b..8df9ed8 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -55,24 +55,52 @@ jobs: path: ./dist make_wheels: - name: 'cibuildwheel: ${{ matrix.name }}' + name: 'cibw: ${{ matrix.name }}' if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }} runs-on: ${{ matrix.os }} strategy: matrix: include: - - os: macos-latest - build: 'cp*-macosx*' - name: macOS + - os: macos-13 + build: 'cp*-macosx_x86_64' + name: macOS13 + - os: macos-14 + build: 'cp*-macosx_arm64' + name: macOS14 + - os: windows-latest build: 'cp3*-win_amd64' name: Windows 64-bit + - os: ubuntu-22.04 build: 'cp*-manylinux_x86_64' name: Linux Intel glibc 64-bit + - os: ubuntu-22.04 - build: 'cp*-musllinux_x86_64' - name: Linux Intel musl 64-bit + build: 'cp36-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.6 + - os: ubuntu-22.04 + build: 'cp37-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.7 + - os: ubuntu-22.04 + build: 'cp38-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.8 + - os: ubuntu-22.04 + build: 'cp39-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.9 + - os: ubuntu-22.04 + build: 'cp310-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.10 + - os: ubuntu-22.04 + build: 'cp311-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.11 + - os: ubuntu-22.04 + build: 'cp312-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.12 + + - os: ubuntu-22.04 + build: 'cp36-manylinux_aarch64' + name: Linux Aarch64 3.6 - os: ubuntu-22.04 build: 'cp37-manylinux_aarch64' name: Linux Aarch64 3.7 @@ -97,8 +125,6 @@ jobs: with: submodules: recursive - ## Setup Env - - uses: ilammy/msvc-dev-cmd@v1.13.0 if: runner.os == 'Windows' @@ -115,16 +141,12 @@ jobs: with: platforms: aarch64 - ## Build - - - uses: pypa/cibuildwheel@v2.16.5 + - uses: pypa/cibuildwheel@v2.17.0 env: CIBW_TEST_REQUIRES: pytest numpy CIBW_TEST_COMMAND: pytest {project}/tests CIBW_ARCHS_LINUX: auto aarch64 - CIBW_ARCHS_MACOS: x86_64 arm64 CIBW_BUILD: ${{ matrix.build }} - CIBW_SKIP: ${{ matrix.skip }} - name: Check with Twine run: | From 26285eff78b4a17435fdb175f0cb34c692933eab Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Wed, 17 Apr 2024 09:32:40 -0700 Subject: [PATCH 086/177] Docs for polygon interface (#362) * initial stab at documenting polygon interface * Separate out verbose descriptions * Nicer flow * improvements * avoid using "set" * move compact functions * move geo functions * "grid distance" is better than "H3 distance" * lint * units * clean up contributing * warning about function name changes * don't need to specify title * update copyright * add a warning about lat/lng order * try this * give the geo_interface link * sphinx 7.3 introduced an issue * document bug * better organization of functions * green is a friendlier color * don't need this * sphinx bug is fixed with 7.3.3 --- docs/_config.yml | 7 +- docs/_toc.yml | 9 +- docs/api_comparison.md | 2 +- docs/api_quick.md | 170 +++++++++++++++++++++++++++++++ docs/api_reference.md | 120 ---------------------- docs/api_verbose.md | 10 ++ docs/contributing.md | 39 ++----- makefile | 2 +- requirements.in | 1 + src/h3/_h3shape.py | 25 +++-- src/h3/api/basic_int/__init__.py | 87 ++++++++++------ 11 files changed, 271 insertions(+), 201 deletions(-) create mode 100644 docs/api_quick.md delete mode 100644 docs/api_reference.md create mode 100644 docs/api_verbose.md diff --git a/docs/_config.yml b/docs/_config.yml index 1a4a8c8..37ee18c 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,11 +1,6 @@ -####################################################################################### -# A default configuration that will be loaded for all jupyter books -# See the documentation for help and more options: -# https://jupyterbook.org/customize/config.html - title: h3-py author: 'Uber Technologies' -copyright: "2021" +copyright: "2024" logo: logo.svg html: diff --git a/docs/_toc.yml b/docs/_toc.yml index 9ebe618..1238199 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -1,19 +1,16 @@ -# Table of contents # Learn more at https://jupyterbook.org/customize/toc.html format: jb-book - root: intro parts: - caption: h3-py chapters: - - file: api_comparison - - file: api_reference + - file: api_quick + - file: api_verbose - file: polygon_tutorial + - file: api_comparison - caption: Sundries chapters: - file: _changelog - title: CHANGELOG - file: contributing - file: project_links - title: Project Links diff --git a/docs/api_comparison.md b/docs/api_comparison.md index 6abfc80..bcf9991 100644 --- a/docs/api_comparison.md +++ b/docs/api_comparison.md @@ -1,4 +1,4 @@ -# API Comparison +# Comparison of APIs The `h3-py` library provides several APIs which share the same functions, but differ in their input and output types: diff --git a/docs/api_quick.md b/docs/api_quick.md new file mode 100644 index 0000000..731f8a9 --- /dev/null +++ b/docs/api_quick.md @@ -0,0 +1,170 @@ +# API Quick Reference + +```{tip} +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](api_comparison). +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](https://h3geo.org/docs/api/indexing), +and should be generally aligned with the +[other language bindings](https://h3geo.org/docs/community/bindings). + +## Identification + +```{eval-rst} +.. currentmodule:: h3 + +.. autosummary:: + is_valid_cell + is_pentagon + is_res_class_III + is_valid_directed_edge +``` + +## Index representation + +```{eval-rst} +.. currentmodule:: h3 + +.. autosummary:: + int_to_str + str_to_int +``` + + +## Cell properties + +```{eval-rst} +.. currentmodule:: h3 + +.. autosummary:: + get_res0_cells + get_pentagons + get_num_cells + get_resolution + get_base_cell_number +``` + +## Geographic coordinates + +Functions relating H3 objects to geographic (lat/lng) coordinates. + +```{eval-rst} +.. 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 + +```{eval-rst} +.. currentmodule:: h3 + +.. autosummary:: + cell_to_parent + cell_to_children + cell_to_center_child + compact_cells + uncompact_cells +``` + +## Cell grid relationships + +```{eval-rst} +.. currentmodule:: h3 + +.. autosummary:: + grid_ring + grid_disk + grid_distance + are_neighbor_cells + grid_path_cells +``` + +## Edges + +```{eval-rst} +.. currentmodule:: h3 + +.. autosummary:: + cells_to_directed_edge + get_directed_edge_destination + directed_edge_to_cells + origin_to_directed_edges + get_directed_edge_origin +``` + +## Polygon interface + +The ``H3Poly`` and ``H3MultiPoly`` 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](https://gist.github.com/sgillies/2217756), which is used by Python geospatial libraries like [GeoPandas](https://geopandas.org/en/stable/docs/reference/api/geopandas.GeoDataFrame.__geo_interface__.html) and many plotting libraries. + +See the [polygon tutorial](./polygon_tutorial.ipynb) for a walkthrough. + +```{tip} +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 + +```{eval-rst} +.. currentmodule:: h3 + +.. autosummary:: + H3Shape + H3Poly + H3MultiPoly +``` + +### Conversion functions + +```{eval-rst} +.. currentmodule:: h3 + +.. autosummary:: + h3shape_to_geo + geo_to_h3shape + h3shape_to_cells + cells_to_h3shape + geo_to_cells + cells_to_geo +``` + + +## Specialized functions + +### `h3-py` library + +```{eval-rst} +.. currentmodule:: h3 + +.. autosummary:: + versions +``` + +### IJ-indexing + +```{eval-rst} +.. currentmodule:: h3 + +.. autosummary:: + get_icosahedron_faces + cell_to_local_ij + local_ij_to_cell +``` diff --git a/docs/api_reference.md b/docs/api_reference.md deleted file mode 100644 index e11e8b0..0000000 --- a/docs/api_reference.md +++ /dev/null @@ -1,120 +0,0 @@ -# API Reference - -This page lists the functions that are common to each of the -[provided APIs](api_comparison). -The APIs differ only in their input/output types -(e.g., `int` vs. `str` or `set` vs `numpy.array`). - -These functions align with those explained in the -[core H3 documentation](https://h3geo.org/docs/api/indexing). - -## Summaries - -There is no strict hierarchy for H3 functions, -but we'll try to group functions in a reasonably logical manner. - -### Identification - -```{eval-rst} -.. currentmodule:: h3 - -.. autosummary:: - is_valid_cell - is_pentagon - is_res_class_III - is_valid_directed_edge - versions -``` - -### Cells - -```{eval-rst} -.. currentmodule:: h3 - -.. autosummary:: - latlng_to_cell - cell_to_latlng - int_to_str - str_to_int - get_res0_cells - get_pentagons - get_num_cells - get_resolution - compact_cells - uncompact_cells -``` - -### Geographic coordinates - -Functions relating H3 objects to geographic (lat/lng) coordinates. - -```{eval-rst} -.. currentmodule:: h3 - -.. autosummary:: - great_circle_distance - average_hexagon_area - cell_area - edge_length - average_hexagon_edge_length - cell_to_boundary - directed_edge_to_boundary -``` - -### Hierarchical relationships - -```{eval-rst} -.. currentmodule:: h3 - -.. autosummary:: - cell_to_parent - cell_to_children - cell_to_center_child -``` - -### Cell grid relationships - -```{eval-rst} -.. currentmodule:: h3 - -.. autosummary:: - grid_ring - grid_disk - grid_distance - are_neighbor_cells - grid_path_cells -``` - -### Edges - -```{eval-rst} -.. currentmodule:: h3 - -.. autosummary:: - cells_to_directed_edge - get_directed_edge_destination - directed_edge_to_cells - origin_to_directed_edges - get_directed_edge_origin -``` - -### IJ-indexing - -```{eval-rst} -.. currentmodule:: h3 - -.. autosummary:: - get_base_cell_number - get_icosahedron_faces - cell_to_local_ij - local_ij_to_cell -``` - - -## Definitions - -```{eval-rst} -.. automodule:: h3 - :members: - :imported-members: -``` diff --git a/docs/api_verbose.md b/docs/api_verbose.md new file mode 100644 index 0000000..83e5219 --- /dev/null +++ b/docs/api_verbose.md @@ -0,0 +1,10 @@ +# API Verbose Reference + +This page gives the full documentation for each function and object. +Refer back to [](api_quick.md) for context and logical groupings. + +```{eval-rst} +.. automodule:: h3 + :members: + :imported-members: +``` diff --git a/docs/contributing.md b/docs/contributing.md index b6bfcde..a76bfb5 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,33 +1,12 @@ # Contributing -```{attention} -This page still a work in progress. -``` +Contributions from the community are welcome! -## Python and Cython - -todo - -## Project organization - -todo - -## Docstring conventions - -https://numpydoc.readthedocs.io/en/latest/format.html - -## Website - -### TODOs - -- release PDF version of docs with each library verison/release? -- page on "anatomy of an H3 index" - -### Other projects with nice docs - -For reference, here are some other projects whose docs we should -consider when styling our own: - -- https://toolz.readthedocs.io/en/latest/api.html -- http://xarray.pydata.org/ -- https://docs.dask.org/en/latest/api.html +Please feel free to +[file an issue](https://github.com/uber/h3-py/issues), +open a +[pull request](https://github.com/uber/h3-py/pulls), +or start a +[discussion in Github](https://github.com/uber/h3-py/discussions) +or in the +[H3 Slack](https://join.slack.com/t/h3-core/shared_invite/zt-g6u5r1hf-W_~uVJmfeiWtMQuBGc1NNg). \ No newline at end of file diff --git a/makefile b/makefile index 22b80e5..629caa7 100644 --- a/makefile +++ b/makefile @@ -21,7 +21,7 @@ clear: -./env/bin/pip uninstall -y h3 -@rm -rf MANIFEST -@rm -rf annotations - -@rm -rf .pytest_cache _skbuild dist .coverage build + -@rm -rf .pytest_cache _skbuild dist .coverage build docs/_build -@find . -type d -name '__pycache__' | xargs rm -r -@find . -type d -name '*.egg-info' | xargs rm -r -@find . -type f -name '*.pyc' | xargs rm -r diff --git a/requirements.in b/requirements.in index 6412c77..dc355b9 100644 --- a/requirements.in +++ b/requirements.in @@ -12,3 +12,4 @@ cmake jupyter-book flake8 +sphinx>=7.3.3 # https://github.com/sphinx-doc/sphinx/issues/12290 diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py index 353887f..974a91a 100644 --- a/src/h3/_h3shape.py +++ b/src/h3/_h3shape.py @@ -2,6 +2,9 @@ from abc import ABCMeta, abstractmethod class H3Shape(metaclass=ABCMeta): + """ + Abstract parent class of ``H3Poly`` and ``H3MultiPoly``. + """ @property @abstractmethod def __geo_interface__(self): @@ -10,7 +13,7 @@ class H3Shape(metaclass=ABCMeta): class H3Poly(H3Shape): """ - Container for loops of lat/lng points describing a polygon. + Container for loops of lat/lng points describing a polygon, possibly with holes. Attributes ---------- @@ -74,10 +77,10 @@ class H3Poly(H3Shape): def loopcode(self): """ Short code for describing the length of the outer loop and each hole - Example: `[382/(18, 6, 6)]` indicates an outer loop of 382 points, + Example: ``[382/(18, 6, 6)]`` indicates an outer loop of 382 points, along with 3 holes with 18, 6, and 6 points, respectively. - Example: `[15]` indicates an outer loop of 15 points and no holes. + Example: ``[15]`` indicates an outer loop of 15 points and no holes. """ outer = len(self.outer) holes = tuple(map(len, self.holes)) @@ -100,6 +103,14 @@ class H3Poly(H3Shape): class H3MultiPoly(H3Shape): + """ + Container for multiple ``H3Poly`` polygons. + + Attributes + ---------- + polys : list[H3Poly] + List of lat/lng points describing the outer loop of the polygon + """ def __init__(self, *polys): self.polys = tuple(polys) @@ -264,9 +275,9 @@ def _open_ring(ll1): def geo_to_h3shape(geo): """ - Translate from __geo_interface__ to H3Shape. + Translate from ``__geo_interface__`` to H3Shape. - `geo` either implements `__geo_interface__` or is a dict matching the format + ``geo`` either implements ``__geo_interface__`` or is a dict matching the format Returns ------- @@ -300,9 +311,9 @@ def geo_to_h3shape(geo): def h3shape_to_geo(h3shape): """ - Translate from H3Shape to a __geo_interface__ dict. + Translate from an ``H3Shape`` to a ``__geo_interface__`` dict. - `h3shape` should be either H3Poly or H3MultiPoly + ``h3shape`` should be either ``H3Poly`` or ``H3MultiPoly`` Returns ------- diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index b0c7e9b..4106f3b 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -92,6 +92,13 @@ def average_hexagon_area(res, unit='km^2'): This average *excludes* pentagons. + Parameters + ---------- + res : int + H3 resolution + unit: str + Unit for area result (``'km^2'``, ``'m^2'``, or ``'rads^2'``) + Returns ------- float @@ -106,6 +113,13 @@ def average_hexagon_edge_length(res, unit='km'): This average *excludes* pentagons. + Parameters + ---------- + res : int + H3 resolution + unit: str + Unit for length result (``'km'``, ``'m'``, or ``'rads'``) + Returns ------- float @@ -214,9 +228,9 @@ def cell_to_parent(h, res=None): def grid_distance(h1, h2): """ - Compute the H3 distance between two cells. + Compute the grid distance between two cells. - The H3 distance is defined as the length of the shortest + The grid distance is defined as the length of the shortest path between the cells in the graph formed by connecting adjacent cells. @@ -257,8 +271,8 @@ def cell_to_boundary(h): def grid_disk(h, k=1): """ - Return unordered collection of cells with H3 distance ``<= k`` from ``h``. - That is, the 'filled-in' disk. + Return unordered collection of cells with grid distance ``<= k`` from ``h``. + That is, the "filled-in" disk. Parameters ---------- @@ -281,7 +295,7 @@ def grid_disk(h, k=1): def grid_ring(h, k=1): """ - Return unordered collection of cells with H3 distance ``== k`` from ``h``. + Return unordered collection of cells with grid distance ``== k`` from ``h``. That is, the "hollow" ring. Parameters @@ -346,7 +360,6 @@ def compact_cells(cells): ----- There is currently no guaranteed order of the output cells. """ - # todo: does compact_cells work on mixed-resolution collections? hu = _in_collection(cells) hc = _cy.compact_cells(hu) @@ -355,7 +368,7 @@ def compact_cells(cells): def uncompact_cells(cells, res): """ - Reverse the `compact_cells` operation. + Reverse the ``compact_cells`` operation. Return a collection of H3 cells, all of resolution ``res``. @@ -369,16 +382,13 @@ def uncompact_cells(cells, res): ------- unordered collection of H3Cell - Raises - ------ - todo: add test to make sure an error is returned when input - contains cell smaller than output res. - https://github.com/uber/h3/blob/master/src/h3lib/lib/h3Index.c#L425 - Notes ----- There is currently no guaranteed order of the output cells. """ + # TODO: add test to make sure an error is returned when input contains cell + # smaller than output res. + hc = _in_collection(cells) hu = _cy.uncompact_cells(hc, res) @@ -387,18 +397,18 @@ def uncompact_cells(cells, res): def h3shape_to_cells(h3shape, res): """ - Return the set of H3 cells at a given resolution whose center points - are contained within an `H3Poly` or `H3MultiPoly`. + Return the collection of H3 cells at a given resolution whose center points + are contained within an ``H3Poly`` or ``H3MultiPoly``. Parameters ---------- - h3shape : H3shape + h3shape : ``H3shape`` res : int Resolution of the output cells Returns ------- - unordered collection of H3Cell + list of H3Cell Examples -------- @@ -408,13 +418,13 @@ def h3shape_to_cells(h3shape, res): ... (37.82, -122.54)], ... ) >>> h3.h3shape_to_cells(poly, 6) - {'862830807ffffff', + ['862830807ffffff', '862830827ffffff', '86283082fffffff', '862830877ffffff', '862830947ffffff', '862830957ffffff', - '86283095fffffff'} + '86283095fffffff'] Notes ----- @@ -438,13 +448,14 @@ def h3shape_to_cells(h3shape, res): def cells_to_h3shape(cells, tight=True): """ - Return a H3MultiPoly describing the area covered by a set of H3 cells. + Return an ``H3Shape`` describing the area covered by a collection of H3 cells. + Will return ``H3Poly`` or ``H3MultiPoly``. Parameters ---------- cells : iterable of H3 cells tight : bool - If True, return H3Poly if possible. If False, always return H3MultiPoly + If True, return ``H3Poly`` if possible. If False, always return ``H3MultiPoly``. Returns ------- @@ -472,12 +483,12 @@ def cells_to_h3shape(cells, tight=True): def geo_to_cells(geo, res): - """Convert from __geo_interface__ to cells. + """Convert from ``__geo_interface__`` to cells. Parameters ---------- - geo : an object implementing `__geo_interface__` or a dictionary in that format. - Both H3Poly and H3MultiPoly implement the interface. + geo : an object implementing ``__geo_interface__`` or a dictionary in that format. + Both ``H3Poly`` and ``H3MultiPoly`` implement the interface. res : int Resolution of desired output cells. @@ -491,9 +502,14 @@ def geo_to_cells(geo, res): def cells_to_geo(cells, tight=True): """ + Convert from cells to a ``__geo_interface__`` dict. + Parameters ---------- cells : iterable of H3 Cells + tight : bool + When ``True``, returns an ``H3Poly`` when possible. + When ``False``, always returns an ``H3MultiPoly``. Returns ------- @@ -674,6 +690,18 @@ def origin_to_directed_edges(origin): def directed_edge_to_boundary(edge): + """ + Returns points representing the edge (line of points + describing the boundary between two cells). + + Parameters + ---------- + edge : H3Edge + + Returns + ------- + tuple of (lat, lng) tuples + """ return _cy.directed_edge_to_boundary(_in_scalar(edge)) @@ -894,7 +922,7 @@ def cell_area(h, unit='km^2'): ---------- h : H3Cell unit: str - Unit for area result (``'km^2'``, 'm^2', or 'rads^2') + Unit for area result (``'km^2'``, ``'m^2'``, or ``'rads^2'``) Returns @@ -907,7 +935,7 @@ def cell_area(h, unit='km^2'): This function breaks the cell into spherical triangles, and computes their spherical area. The function uses the spherical distance calculation given by - `great_circle_distance`. + ``great_circle_distance()``. """ h = _in_scalar(h) @@ -922,7 +950,7 @@ def edge_length(e, unit='km'): ---------- h : H3Cell unit: str - Unit for length result ('km', 'm', or 'rads') + Unit for length result (``'km'``, ``'m'``, or ``'rads'``) Returns @@ -933,7 +961,7 @@ def edge_length(e, unit='km'): Notes ----- This function uses the spherical distance calculation given by - `great_circle_distance`. + ``great_circle_distance()``. """ e = _in_scalar(e) @@ -954,8 +982,7 @@ def great_circle_distance(latlng1, latlng2, unit='km'): latlng2 : tuple (lat, lng) tuple in degrees unit: str - Unit for distance result ('km', 'm', or 'rads') - + Unit for distance result (``'km'``, ``'m'``, or ``'rads'``) Returns ------- From f0fc6df6c36f80f04554be473629da787b2073ce Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 18 May 2024 09:46:14 -0700 Subject: [PATCH 087/177] Introduce LatLngPoly and LatLngMultiPoly (#364) * introduce LatLngPoly * LatLngPoly in files other than *.py * drop 3.7 tests * intro LatLngMultiPoly to .py files * ...and to non .py files * h3shape to just shape in .py files * Class names * function names * H3Shape -> Shape * filename * Revert "H3Shape -> Shape" This reverts commit 389725312f933727170a4cebc720edee29acdd85. * Revert "filename" This reverts commit b263a3e9dc56b4410c40545be26909948f39457c. * revert * fix docs * fix what David found * rename params from `shape` to `h3shape` * ...and a few more * one more * def cells_to_h3shape(cells, *, tight=True) --- .github/workflows/tests.yml | 2 +- docs/api_quick.md | 6 +- docs/polygon_tutorial.ipynb | 82 ++++++++++++------------ src/h3/_h3shape.py | 77 +++++++++++----------- src/h3/api/basic_int/__init__.py | 37 +++++------ tests/polyfill/test_h3.py | 54 ++++++++-------- tests/polyfill/test_polyfill.py | 21 +++--- tests/polyfill/test_polyfill_ordering.py | 2 +- tests/polyfill/test_polygon_class.py | 12 ++-- tests/polyfill/test_to_multipoly.py | 4 +- tests/test_cells_and_edges.py | 2 +- tests/test_h3.py | 2 +- 12 files changed, 152 insertions(+), 149 deletions(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 45f007f..ee17503 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -14,7 +14,7 @@ jobs: strategy: matrix: os: [macos-latest, windows-latest, ubuntu-22.04] - python-version: ['3.7', '3.8', '3.9', '3.10', '3.11', '3.12'] + python-version: ['3.8', '3.9', '3.10', '3.11', '3.12'] steps: - uses: actions/checkout@v4.1.1 diff --git a/docs/api_quick.md b/docs/api_quick.md index 731f8a9..d73f114 100644 --- a/docs/api_quick.md +++ b/docs/api_quick.md @@ -110,7 +110,7 @@ Functions relating H3 objects to geographic (lat/lng) coordinates. ## Polygon interface -The ``H3Poly`` and ``H3MultiPoly`` objects and their related functions allow users to represent (multi)polygons of lat/lng points and convert back and forth between H3 cells. +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](https://gist.github.com/sgillies/2217756), which is used by Python geospatial libraries like [GeoPandas](https://geopandas.org/en/stable/docs/reference/api/geopandas.GeoDataFrame.__geo_interface__.html) and many plotting libraries. @@ -128,8 +128,8 @@ Note that this is reversed from [``__geo_interface__``](https://gist.github.com/ .. autosummary:: H3Shape - H3Poly - H3MultiPoly + LatLngPoly + LatLngMultiPoly ``` ### Conversion functions diff --git a/docs/polygon_tutorial.ipynb b/docs/polygon_tutorial.ipynb index c5efd91..7e0a1e9 100644 --- a/docs/polygon_tutorial.ipynb +++ b/docs/polygon_tutorial.ipynb @@ -9,15 +9,15 @@ "\n", "`h3-py` can convert between sets of cells and GeoJSON-like polygon and multipolygon shapes.\n", "\n", - "We use the abstract base class `H3Shape` and its concrete child classes `H3Poly` and `H3MultiPoly`\n", + "We use the abstract base class `H3Shape` and its concrete child classes `LatLngPoly` and `LatLngMultiPoly`\n", "to represent these shapes. \n", - "Any references or function names that use \"H3Shape\" will apply to both `H3Poly` and `H3MultiPoly` objects.\n", + "Any references or function names that use \"H3Shape\" will apply to both `LatLngPoly` and `LatLngMultiPoly` objects.\n", "\n", "`h3-py` is also compatible with Python objects that implement `__geo_interface__` (https://gist.github.com/sgillies/2217756),\n", "making it easy to interface with other Python geospatial libraries.\n", "We'll refer to any such object as a \"geo\" or \"geo object\".\n", "\n", - "`H3Poly` and `H3MultiPoly` both implement `__geo_interface__` (making them geo objects themselves),\n", + "`LatLngPoly` and `LatLngMultiPoly` both implement `__geo_interface__` (making them geo objects themselves),\n", "and can be created from other geo objects, like Shapely's `Polygon` or `MultiPolygon` objects that occur\n", "when using `geopandas`.\n", "\n", @@ -79,9 +79,9 @@ "id": "c5a41e2b-0c9e-45f5-8005-51af2ef8af32", "metadata": {}, "source": [ - "# H3Poly\n", + "# LatLngPoly\n", "\n", - "We can create a simple `H3Poly` object by providing a list of the **latitude/longitude pairs** that describe its exterior.\n", + "We can create a simple `LatLngPoly` object by providing a list of the **latitude/longitude pairs** that describe its exterior.\n", "Optionally, holes can be added to the polygon by appending additional lat/lng lists do describe them." ] }, @@ -98,7 +98,7 @@ " (37.733, -122.501)\n", "]\n", "\n", - "poly = h3.H3Poly(outer)\n", + "poly = h3.LatLngPoly(outer)\n", "print(poly)\n", "plot_shape(poly)" ] @@ -116,7 +116,7 @@ " (37.788, -122.454),\n", "]\n", "\n", - "poly = h3.H3Poly(outer, hole1)\n", + "poly = h3.LatLngPoly(outer, hole1)\n", "print(poly)\n", "plot_shape(poly)" ] @@ -135,7 +135,7 @@ " (37.769, -122.496),\n", "]\n", "\n", - "poly = h3.H3Poly(outer, hole1, hole2)\n", + "poly = h3.LatLngPoly(outer, hole1, hole2)\n", "print(poly)\n", "plot_shape(poly)" ] @@ -147,13 +147,13 @@ "source": [ "## String representation and attributes\n", "\n", - "The `H3Poly` string representation given by its `__repr__` shows the number of vertices in the outer loop of the polygon, followed\n", + "The `LatLngPoly` string representation given by its `__repr__` shows the number of vertices in the outer loop of the polygon, followed\n", "by the number of vertices in each hole.\n", "\n", "A representation like\n", "\n", "```\n", - "\n", + "\n", "```\n", "\n", "denotes a polygon whose outer boundary consists of 3 vertices and which has 2 holes,\n", @@ -161,8 +161,8 @@ "\n", "We can access the coordinates describing the polygon through the attributes:\n", "\n", - "- `H3Poly.outer` gives the list of lat/lng points making up the outer loop of the polygon.\n", - "- `H3Poly.holes` gives each of the lists of lat/lng points making up the holes of the polygon." + "- `LatLngPoly.outer` gives the list of lat/lng points making up the outer loop of the polygon.\n", + "- `LatLngPoly.holes` gives each of the lists of lat/lng points making up the holes of the polygon." ] }, { @@ -172,7 +172,7 @@ "metadata": {}, "outputs": [], "source": [ - "poly = h3.H3Poly(outer, hole1, hole2)\n", + "poly = h3.LatLngPoly(outer, hole1, hole2)\n", "poly" ] }, @@ -203,9 +203,9 @@ "source": [ "## `__geo_interface__`\n", "\n", - "`H3Poly.__geo_interface__` gives a GeoJSON representation of the polygon as described in https://gist.github.com/sgillies/2217756\n", + "`LatLngPoly.__geo_interface__` gives a GeoJSON representation of the polygon as described in https://gist.github.com/sgillies/2217756\n", "\n", - "**Note the differences in this representation**: Points are given in **lng/lat** order (but the `H3Poly` constructor expects **lat/lng** order), and the last vertex repeats the first." + "**Note the differences in this representation**: Points are given in **lng/lat** order (but the `LatLngPoly` constructor expects **lat/lng** order), and the last vertex repeats the first." ] }, { @@ -235,7 +235,7 @@ "id": "8f567fae-9f4e-472f-afcd-bd6f7bb32cba", "metadata": {}, "source": [ - "We can create an `H3Poly` object from a GeoJSON-like dictionary or an object that implements `__geo_interface__` using `h3.geo_to_h3shape()`." + "We can create an `LatLngPoly` object from a GeoJSON-like dictionary or an object that implements `__geo_interface__` using `h3.geo_to_h3shape()`." ] }, { @@ -272,7 +272,7 @@ "id": "0ab82119-9d9e-465d-94b5-61083e9d9df3", "metadata": {}, "source": [ - "Also note that `H3Poly.__geo_interface__` is equivalent to calling `h3.h3shape_to_geo()` on an `H3Poly` object." + "Also note that `LatLngPoly.__geo_interface__` is equivalent to calling `h3.h3shape_to_geo()` on an `LatLngPoly` object." ] }, { @@ -292,7 +292,7 @@ "source": [ "## Polygon to cells\n", "\n", - "We can get all the H3 cells whose centroids fall within an `H3Poly` by using `h3.h3shape_to_cells()` and specifying the resolution." + "We can get all the H3 cells whose centroids fall within an `LatLngPoly` by using `h3.h3shape_to_cells()` and specifying the resolution." ] }, { @@ -350,15 +350,15 @@ "source": [ "## H3 Polygons don't need to follow the right-hand rule\n", "\n", - "`H3Poly` objects do not need to follow the \"right-hand rule\", unlike GeoJSON Polygons. \n", + "`LatLngPoly` objects do not need to follow the \"right-hand rule\", unlike GeoJSON Polygons. \n", "The right-hand rule requires that vertices in outer loops are listed in counterclockwise\n", "order and holes are listed in clockwise order.\n", "`h3-py` accepts loops in any order and will usually interpret them as the user intended, for example,\n", "converting to sets of cells. However, `h3-py` won't re-order your loops to\n", "conform to the right-hand rule, so be careful if you're using `__geo_interface__` to plot them.\n", "\n", - "Obeying the right-hand rule is only a concern when creating `H3Poly` objects from external input; `H3Poly` or `H3MultiPoly`\n", - "objects created through `h3.cells_to_shape()` **will respect the right-hand rule**.\n", + "Obeying the right-hand rule is only a concern when creating `LatLngPoly` objects from external input; `LatLngPoly` or `LatLngMultiPoly`\n", + "objects created through `h3.cells_to_h3shape()` **will respect the right-hand rule**.\n", "\n", "For example, if we reverse the order of one of the holes in our example polygon above,\n", "the hole won't be rendered correctly, but the conversion to cells will remain unchanged." @@ -372,7 +372,7 @@ "outputs": [], "source": [ "# Respects right-hand rule\n", - "poly = h3.H3Poly(outer, hole1, hole2)\n", + "poly = h3.LatLngPoly(outer, hole1, hole2)\n", "plot_shape_and_cells(poly, res=10)" ] }, @@ -385,7 +385,7 @@ "source": [ "# Does not respect right-hand-rule; second hole is reversed\n", "# Conversion to cells still works, tho!\n", - "poly = h3.H3Poly(outer, hole1[::-1], hole2)\n", + "poly = h3.LatLngPoly(outer, hole1[::-1], hole2)\n", "plot_shape_and_cells(poly, res=10)" ] }, @@ -398,7 +398,7 @@ "source": [ "# Does not respect right-hand-rule; outer loop and second hole are both reversed\n", "# Conversion to cells still works, tho!\n", - "poly = h3.H3Poly(outer[::-1], hole1[::-1], hole2)\n", + "poly = h3.LatLngPoly(outer[::-1], hole1[::-1], hole2)\n", "plot_shape_and_cells(poly, res=10)" ] }, @@ -407,13 +407,13 @@ "id": "b0b13d4a-a376-4a8f-b314-898d9cf94c59", "metadata": {}, "source": [ - "# H3MultiPoly\n", + "# LatLngMultiPoly\n", "\n", - "An `H3MultiPoly` can be created from `H3Poly` objects. The string representation of the `H3MultiPoly`\n", - "gives the number of vertices in the outer loop of each `H3Poly`, along with the number of vertices\n", + "An `LatLngMultiPoly` can be created from `LatLngPoly` objects. The string representation of the `LatLngMultiPoly`\n", + "gives the number of vertices in the outer loop of each `LatLngPoly`, along with the number of vertices\n", "in each hole (if there are any).\n", "\n", - "For example `` represents an `H3MultiPoly` consisting of two `H3Poly` polygons:\n", + "For example `` represents an `LatLngMultiPoly` consisting of two `LatLngPoly` polygons:\n", "\n", "- the first polygon has 3 outer vertices and no holes\n", "- the second polygon has 4 outer vertices and 1 hole with 5 vertices" @@ -426,12 +426,12 @@ "metadata": {}, "outputs": [], "source": [ - "poly1 = h3.H3Poly([(37.804, -122.412), (37.778, -122.507), (37.733, -122.501)])\n", - "poly2 = h3.H3Poly(\n", + "poly1 = h3.LatLngPoly([(37.804, -122.412), (37.778, -122.507), (37.733, -122.501)])\n", + "poly2 = h3.LatLngPoly(\n", " [(37.803, -122.408), (37.736, -122.491), (37.738, -122.380), (37.787, -122.39)],\n", " [(37.760, -122.441), (37.772, -122.427), (37.773, -122.404), (37.758, -122.401), (37.745, -122.428)]\n", ")\n", - "mpoly = h3.H3MultiPoly(poly1, poly2)\n", + "mpoly = h3.LatLngMultiPoly(poly1, poly2)\n", "\n", "print(poly1)\n", "print(poly2)\n", @@ -455,7 +455,7 @@ "source": [ "## MultiPolygon to cells\n", "\n", - "`h3.h3shape_to_cells()` works on both `H3MultiPoly` and `H3Poly` objects (both are subclasses of `H3Shape`)." + "`h3.h3shape_to_cells()` works on both `LatLngMultiPoly` and `LatLngPoly` objects (both are subclasses of `H3Shape`)." ] }, { @@ -474,10 +474,10 @@ "id": "f3712d99-cbe2-4f42-80e3-0acf3fcb8e25", "metadata": {}, "source": [ - "## H3MultiPoly affordances\n", + "## LatLngMultiPoly affordances\n", "\n", - "- Calling `len()` on an `H3MultiPoly` gives the number of polygons\n", - "- You can iterate through a `H3MultiPoly`, with the elements being the underlying `H3Poly`s" + "- Calling `len()` on an `LatLngMultiPoly` gives the number of polygons\n", + "- You can iterate through a `LatLngMultiPoly`, with the elements being the underlying `LatLngPoly`s" ] }, { @@ -518,7 +518,7 @@ "source": [ "## `__geo_interface__`\n", "\n", - "`H3MultiPoly` implements `__geo_interface__`, and `H3MultiPoly` objects can also be created through `h3.geo_to_h3shape()`." + "`LatLngMultiPoly` implements `__geo_interface__`, and `LatLngMultiPoly` objects can also be created through `h3.geo_to_h3shape()`." ] }, { @@ -548,9 +548,9 @@ "id": "a2b71ee2-deed-4336-8b2c-2ab740555188", "metadata": {}, "source": [ - "# Cells to H3Poly or H3MultiPoly\n", + "# Cells to LatLngPoly or LatLngMultiPoly\n", "\n", - "If you have a set of H3 cells that you would like to visualize, you may want to convert them to `H3Poly` or `H3MultiPoly` objects using `h3.cells_to_h3shape()` and then use `__geo_interface__` to get their GeoJSON representation. Or you could\n", + "If you have a set of H3 cells that you would like to visualize, you may want to convert them to `LatLngPoly` or `LatLngMultiPoly` objects using `h3.cells_to_h3shape()` and then use `__geo_interface__` to get their GeoJSON representation. Or you could\n", "use `h3.cells_to_geo()` to get the GeoJSON dictionary directly." ] }, @@ -610,7 +610,7 @@ "\"Geo objects\" are any Python object that implements `__geo_interface__`. This is a widely used\n", "standard in geospatial Python and is used by libraries like `geopandas` and Shapely.\n", "\n", - "`H3Shape` is an abstract class implemented by `H3Poly` and `H3MultiPoly`, each of which\n", + "`H3Shape` is an abstract class implemented by `LatLngPoly` and `LatLngMultiPoly`, each of which\n", "implement `__geo_interface__` and can be created from external \"Geo objects\":\n", "\n", "- `geo_to_h3shape()`\n", @@ -810,7 +810,7 @@ "If we assign `df.geometry = cell_column` we'll get an error because the `geometry` column of a `geopandas.GeoDataFrame` must contain valid geometry objects.\n", "We can obtain compatible objects by converting the cells to `H3Shape` by applying `h3.cells_to_h3shape()`.\n", "\n", - "(Note that, unfortunately, Pandas has some logic to identify iterable members of a series and then renders a tuple of the elements, rather than our preferred `H3MultiPoly.__repr__` representation.)" + "(Note that, unfortunately, Pandas has some logic to identify iterable members of a series and then renders a tuple of the elements, rather than our preferred `LatLngMultiPoly.__repr__` representation.)" ] }, { @@ -829,7 +829,7 @@ "id": "1965d53f-2bba-4840-a627-1bbf55405be3", "metadata": {}, "source": [ - "Note that the column now consists of `H3Poly` and `H3MultiPoly` objects." + "Note that the column now consists of `LatLngPoly` and `LatLngMultiPoly` objects." ] }, { diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py index 974a91a..a9f1ebb 100644 --- a/src/h3/_h3shape.py +++ b/src/h3/_h3shape.py @@ -3,7 +3,7 @@ from abc import ABCMeta, abstractmethod class H3Shape(metaclass=ABCMeta): """ - Abstract parent class of ``H3Poly`` and ``H3MultiPoly``. + Abstract parent class of ``LatLngPoly`` and ``LatLngMultiPoly``. """ @property @abstractmethod @@ -11,7 +11,7 @@ class H3Shape(metaclass=ABCMeta): """ https://github.com/pytest-dev/pytest-cov/issues/428 """ -class H3Poly(H3Shape): +class LatLngPoly(H3Shape): """ Container for loops of lat/lng points describing a polygon, possibly with holes. @@ -28,34 +28,34 @@ class H3Poly(H3Shape): A polygon with a single outer ring consisting of 4 points, having no holes: - >>> H3Poly( + >>> LatLngPoly( ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)], ... ) - + The same polygon, but with one hole consisting of 3 points: - >>> H3Poly( + >>> LatLngPoly( ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)], ... [(37.76, -122.51), (37.76, -122.44), (37.81, -122.51)], ... ) - + The same as above, but with one additional hole, made up of 5 points: - >>> H3Poly( + >>> LatLngPoly( ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)], ... [(37.76, -122.51), (37.76, -122.44), (37.81, -122.51)], ... [(37.71, -122.43), (37.71, -122.37), (37.73, -122.37), (37.75, -122.41), ... (37.73, -122.43)], ... ) - + """ def __init__(self, outer, *holes): loops = [outer] + list(holes) for loop in loops: if len(loop) in (1, 2): - raise ValueError('Non-empty H3Poly loops need at least 3 points.') + raise ValueError('Non-empty LatLngPoly loops need at least 3 points.') self.outer = tuple(_open_ring(outer)) self.holes = tuple( @@ -64,14 +64,14 @@ class H3Poly(H3Shape): ) def __repr__(self): - return ''.format(self.loopcode) + return ''.format(self.loopcode) def __len__(self): """ Should this be the number of points in the outer loop, the number of holes (or +1 for the outer loop)? """ - raise NotImplementedError('No clear definition of length for H3Poly.') + raise NotImplementedError('No clear definition of length for LatLngPoly.') @property def loopcode(self): @@ -102,26 +102,26 @@ class H3Poly(H3Shape): return gj_dict -class H3MultiPoly(H3Shape): +class LatLngMultiPoly(H3Shape): """ - Container for multiple ``H3Poly`` polygons. + Container for multiple ``LatLngPoly`` polygons. Attributes ---------- - polys : list[H3Poly] + polys : list[LatLngPoly] List of lat/lng points describing the outer loop of the polygon """ def __init__(self, *polys): self.polys = tuple(polys) for p in self.polys: - if not isinstance(p, H3Poly): - raise ValueError('H3MultiPoly requires each input to be an H3Poly object, instead got: ' + str(p)) # noqa + if not isinstance(p, LatLngPoly): + raise ValueError('LatLngMultiPoly requires each input to be an LatLngPoly object, instead got: ' + str(p)) # noqa def __repr__(self): out = [p.loopcode for p in self.polys] out = ', '.join(out) - out = ''.format(out) + out = ''.format(out) return out def __iter__(self): @@ -135,24 +135,25 @@ class H3MultiPoly(H3Shape): TODO: Pandas series or dataframe representation changes depending on if __len__ is defined. - I'd prefer the one that states `H3MultiPoly`. It seems like Pandas is assuming - an iterable is best-described by its elements when choosing the representation. + I'd prefer the one that states `LatLngMultiPoly`. + It seems like Pandas is assuming an iterable is best-described + by its elements when choosing the representation. when __len__ *IS NOT* defined: - 0 - 1 + 1 , , ) - 1 (, , , , , , <... + 0 (, , ) + 1 (, , , , , , <... """ return len(self.polys) @@ -203,13 +204,13 @@ def _LL3_to_mpoly(ll3): for ll2 in ll3 ] - mpoly = H3MultiPoly(*polys) + mpoly = LatLngMultiPoly(*polys) return mpoly -def _polygon_to_LL2(h3poly): - ll2 = [h3poly.outer] + list(h3poly.holes) +def _polygon_to_LL2(LatLngPoly): + ll2 = [LatLngPoly.outer] + list(LatLngPoly.holes) ll2 = tuple( _close_ring(_swap_latlng(ll1)) for ll1 in ll2 @@ -223,7 +224,7 @@ def _LL2_to_polygon(ll2): _swap_latlng(ll1) for ll1 in ll2 ] - h3poly = H3Poly(*ll2) + h3poly = LatLngPoly(*ll2) return h3poly @@ -284,7 +285,7 @@ def geo_to_h3shape(geo): H3Shape """ - # geo can be dict, a __geo_interface__, a string, H3Poly or H3MultiPoly + # geo can be dict, a __geo_interface__, a string, LatLngPoly or LatLngMultiPoly if isinstance(geo, H3Shape): return geo @@ -299,21 +300,21 @@ def geo_to_h3shape(geo): if t == 'Polygon': ll2 = coord - h3shape = _LL2_to_polygon(ll2) + shape = _LL2_to_polygon(ll2) elif t == 'MultiPolygon': ll3 = coord - h3shape = _LL3_to_mpoly(ll3) + shape = _LL3_to_mpoly(ll3) else: raise ValueError('Unrecognized type: ' + str(t)) - return h3shape + return shape def h3shape_to_geo(h3shape): """ Translate from an ``H3Shape`` to a ``__geo_interface__`` dict. - ``h3shape`` should be either ``H3Poly`` or ``H3MultiPoly`` + ``h3shape`` should be either ``LatLngPoly`` or ``LatLngMultiPoly`` Returns ------- diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index 4106f3b..d1122d8 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -3,8 +3,8 @@ from ... import _cy from ..._h3shape import ( H3Shape, - H3Poly, - H3MultiPoly, + LatLngPoly, + LatLngMultiPoly, geo_to_h3shape, h3shape_to_geo, ) @@ -398,11 +398,11 @@ def uncompact_cells(cells, res): def h3shape_to_cells(h3shape, res): """ Return the collection of H3 cells at a given resolution whose center points - are contained within an ``H3Poly`` or ``H3MultiPoly``. + are contained within an ``LatLngPoly`` or ``LatLngMultiPoly``. Parameters ---------- - h3shape : ``H3shape`` + h3shape : ``H3Shape`` res : int Resolution of the output cells @@ -413,7 +413,7 @@ def h3shape_to_cells(h3shape, res): Examples -------- - >>> poly = H3Poly( + >>> poly = LatLngPoly( ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), ... (37.82, -122.54)], ... ) @@ -432,10 +432,10 @@ def h3shape_to_cells(h3shape, res): """ # todo: not sure if i want this dispatch logic here. maybe in the objects? - if isinstance(h3shape, H3Poly): + if isinstance(h3shape, LatLngPoly): poly = h3shape mv = _cy.polygon_to_cells(poly.outer, res, holes=poly.holes) - elif isinstance(h3shape, H3MultiPoly): + elif isinstance(h3shape, LatLngMultiPoly): mpoly = h3shape mv = _cy.polygons_to_cells(mpoly.polys, res) elif isinstance(h3shape, H3Shape): @@ -446,35 +446,36 @@ def h3shape_to_cells(h3shape, res): return _out_collection(mv) -def cells_to_h3shape(cells, tight=True): +def cells_to_h3shape(cells, *, tight=True): """ Return an ``H3Shape`` describing the area covered by a collection of H3 cells. - Will return ``H3Poly`` or ``H3MultiPoly``. + Will return ``LatLngPoly`` or ``LatLngMultiPoly``. Parameters ---------- cells : iterable of H3 cells tight : bool - If True, return ``H3Poly`` if possible. If False, always return ``H3MultiPoly``. + If True, return ``LatLngPoly`` if possible. + If False, always return ``LatLngMultiPoly``. Returns ------- - H3Poly | H3MultiPoly + LatLngPoly | LatLngMultiPoly Examples -------- >>> cells = ['8428309ffffffff', '842830dffffffff'] >>> h3.cells_to_h3shape(cells, tight=True) - + >>> h3.cells_to_h3shape(cells, tight=False) - + """ cells = _in_collection(cells) mpoly = _cy.cells_to_multi_polygon(cells) - polys = [H3Poly(*poly) for poly in mpoly] - out = H3MultiPoly(*polys) + polys = [LatLngPoly(*poly) for poly in mpoly] + out = LatLngMultiPoly(*polys) if tight and len(out) == 1: out = out[0] @@ -488,7 +489,7 @@ def geo_to_cells(geo, res): Parameters ---------- geo : an object implementing ``__geo_interface__`` or a dictionary in that format. - Both ``H3Poly`` and ``H3MultiPoly`` implement the interface. + Both ``LatLngPoly`` and ``LatLngMultiPoly`` implement the interface. res : int Resolution of desired output cells. @@ -508,8 +509,8 @@ def cells_to_geo(cells, tight=True): ---------- cells : iterable of H3 Cells tight : bool - When ``True``, returns an ``H3Poly`` when possible. - When ``False``, always returns an ``H3MultiPoly``. + When ``True``, returns an ``LatLngPoly`` when possible. + When ``False``, always returns an ``LatLngMultiPoly``. Returns ------- diff --git a/tests/polyfill/test_h3.py b/tests/polyfill/test_h3.py index 78d3223..dbed67b 100644 --- a/tests/polyfill/test_h3.py +++ b/tests/polyfill/test_h3.py @@ -74,8 +74,8 @@ sf_hole2 = [ def test_geo_interface(): - poly = h3.H3Poly(sf_hole1) - mpoly = h3.H3MultiPoly(poly) + poly = h3.LatLngPoly(sf_hole1) + mpoly = h3.LatLngMultiPoly(poly) assert poly.__geo_interface__['type'] == 'Polygon' assert mpoly.__geo_interface__['type'] == 'MultiPolygon' @@ -88,18 +88,18 @@ def test_geo_interface(): def test_shape_repr(): - poly = h3.H3Poly(sf_hole1) - mpoly = h3.H3MultiPoly(poly) + poly = h3.LatLngPoly(sf_hole1) + mpoly = h3.LatLngMultiPoly(poly) assert ( - '' + '' == str(mpoly) == repr(mpoly) ) def test_polyfill(): - poly = h3.H3Poly(sf_7x7) + poly = h3.LatLngPoly(sf_7x7) out = h3.h3shape_to_cells(poly, res=9) assert len(out) == 1253 @@ -108,12 +108,12 @@ def test_polyfill(): def test_polyfill_with_hole(): - poly = h3.H3Poly(sf_7x7, sf_hole1) + poly = h3.LatLngPoly(sf_7x7, sf_hole1) out = h3.h3shape_to_cells(poly, res=9) assert len(out) == 1214 - foo = lambda x: set(h3.h3shape_to_cells(h3.H3Poly(x), 9)) + foo = lambda x: set(h3.h3shape_to_cells(h3.LatLngPoly(x), 9)) assert u.same_set( out, @@ -123,11 +123,11 @@ def test_polyfill_with_hole(): def test_polyfill_with_two_holes(): - poly = h3.H3Poly(sf_7x7, sf_hole1, sf_hole2) + poly = h3.LatLngPoly(sf_7x7, sf_hole1, sf_hole2) out = h3.h3shape_to_cells(poly, 9) assert len(out) == 1172 - foo = lambda x: set(h3.h3shape_to_cells(h3.H3Poly(x), 9)) + foo = lambda x: set(h3.h3shape_to_cells(h3.LatLngPoly(x), 9)) assert u.same_set( out, foo(sf_7x7) - (foo(sf_hole1) | foo(sf_hole2)) @@ -148,21 +148,21 @@ def test_polyfill_geo_interface_compliant(): def test_poly_opens_loop(): loop = lnglat_closed() - poly = h3.H3Poly(loop) + poly = h3.LatLngPoly(loop) assert loop[0] == loop[-1] assert len(poly.outer) == len(loop) - 1 def test_geo_to_h3shape(): - h3shapes = [ + shapes = [ h3.geo_to_h3shape(get_mocked(lnglat_open())), h3.geo_to_h3shape(get_mocked(lnglat_closed())), - h3.H3Poly(latlng_open()), - h3.H3Poly(latlng_closed()), + h3.LatLngPoly(latlng_open()), + h3.LatLngPoly(latlng_closed()), ] - for s in h3shapes: + for s in shapes: assert len(h3.h3shape_to_cells(s, 8)) == 48 expected = { @@ -175,10 +175,10 @@ def test_geo_to_h3shape(): ),) } - for shape in h3shapes: + for shape in shapes: assert shape.__geo_interface__ == expected - mpolys = map(h3.H3MultiPoly, h3shapes) + mpolys = map(h3.LatLngMultiPoly, shapes) multi_expected = { 'type': 'MultiPolygon', @@ -195,8 +195,8 @@ def test_geo_to_h3shape(): def test_geo_to_h3shape_passthrough(): - poly = h3.H3Poly(latlng_open()) - mpoly = h3.H3MultiPoly(poly) + poly = h3.LatLngPoly(latlng_open()) + mpoly = h3.LatLngMultiPoly(poly) for shape in [poly, mpoly]: assert h3.geo_to_h3shape(shape) is shape @@ -237,7 +237,7 @@ def test_polyfill_down_under(): (-33.8556, 151.1979), ] - poly = h3.H3Poly(sydney) + poly = h3.LatLngPoly(sydney) out = h3.h3shape_to_cells(poly, 9) assert len(out) == 92 assert '89be0e34207ffff' in out @@ -253,7 +253,7 @@ def test_polyfill_far_east(): (41.925781, 142.864838), ] - poly = h3.H3Poly(geo) + poly = h3.LatLngPoly(geo) out = h3.h3shape_to_cells(poly, 9) assert len(out) == 18507 assert '892e18d16c3ffff' in out @@ -269,7 +269,7 @@ def test_polyfill_southern_tip(): (-55.416544, -67.642822), ] - poly = h3.H3Poly(geo) + poly = h3.LatLngPoly(geo) out = h3.h3shape_to_cells(poly, 9) assert len(out) == 223247 assert '89df4000003ffff' in out @@ -285,7 +285,7 @@ def test_polyfill_null_island(): (-3, -3), ] - poly = h3.H3Poly(geo) + poly = h3.LatLngPoly(geo) out = h3.h3shape_to_cells(poly, 4) assert len(out) == 345 assert '847421bffffffff' in out @@ -306,7 +306,7 @@ def test_cells_to_h3shape_single(): poly = mpoly[0] vertices = h3.cell_to_boundary(h) - expected_poly = h3.H3Poly(vertices) + expected_poly = h3.LatLngPoly(vertices) assert set(poly.outer) == set(expected_poly.outer) assert poly.holes == expected_poly.holes == () @@ -378,10 +378,10 @@ def test_cells_to_h3shape_2grid_disk(): def test_multipoly_checks(): with pytest.raises(ValueError): - h3.H3MultiPoly('foo') + h3.LatLngMultiPoly('foo') with pytest.raises(ValueError): - h3.H3MultiPoly(1) + h3.LatLngMultiPoly(1) with pytest.raises(ValueError): - h3.H3MultiPoly([[(1, 2), (3, 4)]]) + h3.LatLngMultiPoly([[(1, 2), (3, 4)]]) diff --git a/tests/polyfill/test_polyfill.py b/tests/polyfill/test_polyfill.py index 541c453..b78e875 100644 --- a/tests/polyfill/test_polyfill.py +++ b/tests/polyfill/test_polyfill.py @@ -71,7 +71,7 @@ def test_h3shape_to_cells(): '832badfffffffff' } - poly = h3.H3Poly(maine) + poly = h3.LatLngPoly(maine) out = h3.h3shape_to_cells(poly, 3) assert u.same_set(out, expected) @@ -80,7 +80,7 @@ def test_h3shape_to_cells(): def test_h3shape_to_cells2(): lnglat, _, _ = get_us_box_coords() - poly = h3.H3Poly(lnglat) + poly = h3.LatLngPoly(lnglat) out = h3.h3shape_to_cells(poly, 5) assert len(out) == 7063 @@ -97,15 +97,16 @@ def test_h3shape_to_cells_holes(): outer, hole1, hole2 = get_us_box_coords() assert 7063 == len( - h3.h3shape_to_cells(h3.H3Poly(outer), 5) + h3.h3shape_to_cells(h3.LatLngPoly(outer), 5) ) for res in 1, 2, 3, 4, 5: - cells_all = h3.h3shape_to_cells(h3.H3Poly(outer), res) - cells_holes = set(h3.h3shape_to_cells(h3.H3Poly(outer, hole1, hole2), res=res)) + cells_all = h3.h3shape_to_cells(h3.LatLngPoly(outer), res) + poly = h3.LatLngPoly(outer, hole1, hole2) + cells_holes = set(h3.h3shape_to_cells(poly, res=res)) - cells_1 = set(h3.h3shape_to_cells(h3.H3Poly(hole1), res)) - cells_2 = set(h3.h3shape_to_cells(h3.H3Poly(hole2), res)) + cells_1 = set(h3.h3shape_to_cells(h3.LatLngPoly(hole1), res)) + cells_2 = set(h3.h3shape_to_cells(h3.LatLngPoly(hole2), res)) assert len(cells_all) == len(cells_holes) + len(cells_1) + len(cells_2) assert u.same_set( @@ -115,7 +116,7 @@ def test_h3shape_to_cells_holes(): def test_resolution(): - poly = h3.H3Poly([]) + poly = h3.LatLngPoly([]) assert h3.h3shape_to_cells(poly, 0) == [] assert h3.h3shape_to_cells(poly, 15) == [] @@ -134,11 +135,11 @@ def test_invalid_polygon(): some `cdef` functions. """ with pytest.raises(TypeError): - poly = h3.H3Poly([1, 2, 3]) + poly = h3.LatLngPoly([1, 2, 3]) h3.h3shape_to_cells(poly, 4) with pytest.raises(ValueError): - poly = h3.H3Poly([[1, 2, 3]]) + poly = h3.LatLngPoly([[1, 2, 3]]) h3.h3shape_to_cells(poly, 4) diff --git a/tests/polyfill/test_polyfill_ordering.py b/tests/polyfill/test_polyfill_ordering.py index 0206138..e0e43d8 100644 --- a/tests/polyfill/test_polyfill_ordering.py +++ b/tests/polyfill/test_polyfill_ordering.py @@ -44,7 +44,7 @@ def input_permutations(geo, res=5): g = chain_toggle_map(reverse, g) for p in g: - poly = h3.H3Poly(*p) + poly = h3.LatLngPoly(*p) cells = h3.h3shape_to_cells(poly, res=res) yield cells diff --git a/tests/polyfill/test_polygon_class.py b/tests/polyfill/test_polygon_class.py index 4ed7faa..c38505d 100644 --- a/tests/polyfill/test_polygon_class.py +++ b/tests/polyfill/test_polygon_class.py @@ -17,18 +17,18 @@ def test_repr(): mpoly2 = sorted(map(str, mpoly2)) assert mpoly1 == [ - '', - '', + '', + '', ] assert mpoly2 == [ - '', - '', - '', + '', + '', + '', ] -def test_h3poly_len(): +def test_LatLngPoly_len(): cells = {'8928308280fffff'} poly = h3.cells_to_h3shape(cells, tight=True) diff --git a/tests/polyfill/test_to_multipoly.py b/tests/polyfill/test_to_multipoly.py index 1207da2..61f77f6 100644 --- a/tests/polyfill/test_to_multipoly.py +++ b/tests/polyfill/test_to_multipoly.py @@ -11,7 +11,7 @@ def test_cells_to_h3shape(): mpoly = h3.cells_to_h3shape(cells, tight=False) poly = mpoly[0] - poly2 = h3.H3Poly(poly.outer, *poly.holes) + poly2 = h3.LatLngPoly(poly.outer, *poly.holes) out = h3.h3shape_to_cells(poly2, 9) assert u.same_set(out, cells) @@ -22,7 +22,7 @@ def test_cells_to_h3shape_tight(): cells = h3.grid_disk(h, 1) poly = h3.cells_to_h3shape(cells, tight=True) - poly2 = h3.H3Poly(poly.outer, *poly.holes) + poly2 = h3.LatLngPoly(poly.outer, *poly.holes) out = h3.h3shape_to_cells(poly2, 9) assert u.same_set(out, cells) diff --git a/tests/test_cells_and_edges.py b/tests/test_cells_and_edges.py index 1e4c5d7..d23ff4d 100644 --- a/tests/test_cells_and_edges.py +++ b/tests/test_cells_and_edges.py @@ -208,7 +208,7 @@ def test_distance_error(): def get_maine_cells(): # lat/lngs for State of Maine - poly = h3.H3Poly([ + poly = h3.LatLngPoly([ (45.137451890638886, -67.13734351262877), (44.8097, -66.96466), (44.3252, -68.03252), diff --git a/tests/test_h3.py b/tests/test_h3.py index a7fc415..186145f 100644 --- a/tests/test_h3.py +++ b/tests/test_h3.py @@ -201,7 +201,7 @@ def test_compact_and_uncompact_cells(): (37.8151571999998453, -122.4798767000009008), ] - poly = h3.H3Poly(sf_7x7) + poly = h3.LatLngPoly(sf_7x7) cells = h3.h3shape_to_cells(poly, 9) compact_cells = h3.compact_cells(cells) From d1f84f59e67169c41c889b7eb322bdc90c79bba1 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 19 May 2024 08:35:32 -0700 Subject: [PATCH 088/177] Handle polygons with z-coordinate (#371) * failing test * better test * lint * dah! lat/lng order *still* trips me up! * 3d poly test * names and notes * fix accidental replace from when we changed names to LatLngPoly --- .flake8 | 4 +++- src/h3/_h3shape.py | 19 +++++++++++++++++-- tests/polyfill/test_h3.py | 30 ++++++++++++++++++++++++++++++ 3 files changed, 50 insertions(+), 3 deletions(-) diff --git a/.flake8 b/.flake8 index 3f950dd..f77f556 100644 --- a/.flake8 +++ b/.flake8 @@ -15,4 +15,6 @@ ignore = # E731 do not assign a lambda expression, use a def E731, # https://stackoverflow.com/questions/67942075/w504-line-break-after-binary-operator - W503,W504 + W503,W504, + # E272 multiple spaces before keyword + E272 diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py index a9f1ebb..5c36295 100644 --- a/src/h3/_h3shape.py +++ b/src/h3/_h3shape.py @@ -57,6 +57,11 @@ class LatLngPoly(H3Shape): if len(loop) in (1, 2): raise ValueError('Non-empty LatLngPoly loops need at least 3 points.') + point_dimensions = set(map(len, loop)) + # empty set is possible for empty polygons, so we check if a subset + if not (point_dimensions <= {2}): + raise ValueError('LatLngPoly only accepts 2D points: lat/lng.') + self.outer = tuple(_open_ring(outer)) self.holes = tuple( _open_ring(hole) @@ -209,8 +214,8 @@ def _LL3_to_mpoly(ll3): return mpoly -def _polygon_to_LL2(LatLngPoly): - ll2 = [LatLngPoly.outer] + list(LatLngPoly.holes) +def _polygon_to_LL2(poly): + ll2 = [poly.outer] + list(poly.holes) ll2 = tuple( _close_ring(_swap_latlng(ll1)) for ll1 in ll2 @@ -219,7 +224,17 @@ def _polygon_to_LL2(LatLngPoly): return ll2 +def _remove_z(ll1): + ll1 = [(a, b) for a, b, *z in ll1] + return ll1 + + def _LL2_to_polygon(ll2): + ll2 = [ + _remove_z(ll1) + for ll1 in ll2 + ] + ll2 = [ _swap_latlng(ll1) for ll1 in ll2 diff --git a/tests/polyfill/test_h3.py b/tests/polyfill/test_h3.py index dbed67b..b6de101 100644 --- a/tests/polyfill/test_h3.py +++ b/tests/polyfill/test_h3.py @@ -385,3 +385,33 @@ def test_multipoly_checks(): with pytest.raises(ValueError): h3.LatLngMultiPoly([[(1, 2), (3, 4)]]) + + +def test_3d_geo(): + loop = lnglat_open() + + loop2d = [(lng, lat) for lng, lat in loop] + loop3d = [(lng, lat, 0.0) for lng, lat in loop] + + geo2d = get_mocked(loop2d) + geo3d = get_mocked(loop3d) + + shape2 = h3.geo_to_h3shape(geo2d) + shape3 = h3.geo_to_h3shape(geo3d) + + out2 = h3.h3shape_to_cells(shape2, 9) + out3 = h3.h3shape_to_cells(shape3, 9) + + assert len(out2) == 344 + assert set(out2) == set(out3) + + +def test_against_3d_polygons(): + # LatLngPoly still expects just a lat/lng. it won't handle 3d coords + loop3d = [ + (lat, lng, 0.0) + for lat, lng in latlng_open() + ] + + with pytest.raises(ValueError): + h3.LatLngPoly(loop3d) From d3f6c1d27d28ea29f1946f4622b4f451b136f400 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 19 May 2024 09:51:59 -0700 Subject: [PATCH 089/177] prep for v4b5 release (#372) --- CHANGELOG.md | 6 +++++- src/h3/_version.py | 2 +- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 011db49..37cf91c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,11 @@ avoid adding features or APIs which do not map onto the - None +## [4.0.0b5] - 2024-05-19 + +- Rename `H3Poly` and `H3MultiPoly` to `LatLngPoly` and `LatLngMultiPoly` (#364) +- Add ability to convert from `__geo_interface__` objects with Z-coordinate (#371) + ## [4.0.0b4] - 2024-04-14 No changes, just testing: #360 @@ -29,7 +34,6 @@ No changes, just testing: #360 - Use functions instead of methods for the interface functions (#334) - Use `list` instead of `set` for unordered Python outputs (#339) - ## [4.0.0b2] - 2022-11-23 - Build Python 3.11 wheels (#297) diff --git a/src/h3/_version.py b/src/h3/_version.py index fd4db08..d1d952c 100644 --- a/src/h3/_version.py +++ b/src/h3/_version.py @@ -1,4 +1,4 @@ -__version__ = '4.0.0b4' +__version__ = '4.0.0b5' __description__ = 'Hierarchical hexagonal geospatial indexing system' __url__ = 'https://github.com/uber/h3-py' __license__ = 'Apache 2.0 License' From e0e269d52489c0ae53a359aececb5de142f13444 Mon Sep 17 00:00:00 2001 From: Pieter Provoost Date: Sun, 25 Aug 2024 19:35:08 +0200 Subject: [PATCH 090/177] fix api reference link (#385) --- readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/readme.md b/readme.md index d4142be..fafc529 100644 --- a/readme.md +++ b/readme.md @@ -63,12 +63,12 @@ conda install h3-py ## APIs [api_comparison]: https://uber.github.io/h3-py/api_comparison -[api_reference]: https://uber.github.io/h3-py/api_reference +[api_quick]: https://uber.github.io/h3-py/api_quick We provide [multiple APIs][api_comparison] in `h3-py`. - All APIs have the same set of functions; - see the [API reference][api_reference]. + see the [API reference][api_quick]. - The APIs differ only in their input/output formats; see the [API comparison page][api_comparison]. From 46a7181b3f03b49b8539d7eb9aa6a6eb29ee38c0 Mon Sep 17 00:00:00 2001 From: Shiran Yuan Date: Tue, 27 Aug 2024 08:05:20 -0700 Subject: [PATCH 091/177] Added Bindings for Vertex-Related Functions (#388) * Update CHANGELOG.md * Update h3lib.pxd * Update latlng.pxd * Update latlng.pyx * Update util.pxd * Update util.pyx * Update _version.py * Update __init__.py * Update __init__.py * Update test_h3.py * Update __init__.py * Update test_h3.py * Update CHANGELOG.md * Update __init__.py * Update test_h3.py * Update _version.py * Update test_h3.py * Update __init__.py * Update CMakeLists.txt * Update latlng.pxd * Update latlng.pyx * Create vertex.pxd * Create vertex.pyx * Update __init__.py * Update test_h3.py * Update __init__.py * Update api_quick.md --- CHANGELOG.md | 4 +- docs/api_quick.md | 12 ++++++ src/h3/_cy/CMakeLists.txt | 3 ++ src/h3/_cy/__init__.py | 7 ++++ src/h3/_cy/h3lib.pxd | 5 +++ src/h3/_cy/latlng.pyx | 2 +- src/h3/_cy/util.pxd | 1 + src/h3/_cy/util.pyx | 7 +++- src/h3/_cy/vertex.pxd | 6 +++ src/h3/_cy/vertex.pyx | 54 +++++++++++++++++++++++++ src/h3/api/basic_int/__init__.py | 67 ++++++++++++++++++++++++++++++++ tests/test_h3.py | 55 ++++++++++++++++++++++++++ 12 files changed, 219 insertions(+), 4 deletions(-) create mode 100644 src/h3/_cy/vertex.pxd create mode 100644 src/h3/_cy/vertex.pyx diff --git a/CHANGELOG.md b/CHANGELOG.md index 37cf91c..268c744 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,9 +14,9 @@ Because H3-Py is versioned in lockstep with the H3 core library, please avoid adding features or APIs which do not map onto the [H3 core API](https://uber.github.io/h3/#/documentation/api-reference/). -## Unreleased +## Unreleased - 2024-08-23 -- None +- Added bindings for `cellToVertex`, `cellToVertexes`, `vertexToLatLng`, and `isValidVertex` (#323) ## [4.0.0b5] - 2024-05-19 diff --git a/docs/api_quick.md b/docs/api_quick.md index d73f114..0753ddb 100644 --- a/docs/api_quick.md +++ b/docs/api_quick.md @@ -24,6 +24,7 @@ and should be generally aligned with the is_pentagon is_res_class_III is_valid_directed_edge + is_valid_vertex ``` ## Index representation @@ -108,6 +109,17 @@ Functions relating H3 objects to geographic (lat/lng) coordinates. get_directed_edge_origin ``` +## Vertexes + +```{eval-rst} +.. 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. diff --git a/src/h3/_cy/CMakeLists.txt b/src/h3/_cy/CMakeLists.txt index 5d392d2..52e0156 100644 --- a/src/h3/_cy/CMakeLists.txt +++ b/src/h3/_cy/CMakeLists.txt @@ -24,6 +24,7 @@ add_cython_file(edges) add_cython_file(to_multipoly) add_cython_file(error_system) add_cython_file(memory) +add_cython_file(vertex) # Include pyx and pxd files in distribution for use by Cython API @@ -41,6 +42,8 @@ install( error_system.pyx memory.pxd memory.pyx + vertex.pxd + vertex.pyx DESTINATION src/h3/_cy ) diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index c208711..c739bc0 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -60,6 +60,13 @@ from .latlng import ( great_circle_distance, ) +from .vertex import ( + cell_to_vertex, + cell_to_vertexes, + vertex_to_latlng, + is_valid_vertex, +) + from .to_multipoly import ( cells_to_multi_polygon ) diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index 00fff60..eae1b85 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -69,6 +69,7 @@ cdef extern from 'h3api.h': int isPentagon(H3int h) nogil int isResClassIII(H3int h) nogil int isValidDirectedEdge(H3int edge) nogil + int isValidVertex(H3int v) nogil double degsToRads(double degrees) nogil double radsToDegs(double radians) nogil @@ -80,6 +81,10 @@ cdef extern from 'h3api.h': H3Error cellToLatLng(H3int h, LatLng *) nogil H3Error gridDistance(H3int h1, H3int h2, int64_t *distance) nogil + H3Error cellToVertex(H3int cell, int vertexNum, H3int *out) nogil + H3Error cellToVertexes(H3int cell, H3int *vertexes) nogil + H3Error vertexToLatLng(H3int vertex, LatLng *coord) nogil + H3Error maxGridDiskSize(int k, int64_t *out) nogil # num/out/N? H3Error gridDisk(H3int h, int k, H3int *out) nogil diff --git a/src/h3/_cy/latlng.pyx b/src/h3/_cy/latlng.pyx index 520b950..c3e0cdb 100644 --- a/src/h3/_cy/latlng.pyx +++ b/src/h3/_cy/latlng.pyx @@ -8,7 +8,7 @@ from .util cimport ( check_edge, check_res, deg2coord, - coord2deg, + coord2deg ) from .error_system cimport check_for_error diff --git a/src/h3/_cy/util.pxd b/src/h3/_cy/util.pxd index 15e97ad..4d7d962 100644 --- a/src/h3/_cy/util.pxd +++ b/src/h3/_cy/util.pxd @@ -9,4 +9,5 @@ cpdef H3str int_to_str(H3int x) cdef check_cell(H3int h) cdef check_edge(H3int e) cdef check_res(int res) +cdef check_vertex(H3int v) cdef check_distance(int k) diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index 8bc061d..7b8a9f2 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -1,4 +1,4 @@ -from .h3lib cimport H3int, H3str, isValidCell, isValidDirectedEdge +from .h3lib cimport H3int, H3str, isValidCell, isValidDirectedEdge, isValidVertex cimport h3lib @@ -7,6 +7,7 @@ from .error_system import ( H3DomainError, H3DirEdgeInvalidError, H3CellInvalidError, + H3VertexInvalidError ) cdef h3lib.LatLng deg2coord(double lat, double lng) nogil: @@ -73,6 +74,10 @@ cdef check_edge(H3int e): if isValidDirectedEdge(e) == 0: raise H3DirEdgeInvalidError('Integer is not a valid H3 edge: {}'.format(hex(e))) +cdef check_vertex(H3int v): + if isValidVertex(v) == 0: + raise H3VertexInvalidError('Integer is not a valid H3 vertex: {}'.format(hex(v))) + cdef check_res(int res): if (res < 0) or (res > 15): raise H3ResDomainError(res) diff --git a/src/h3/_cy/vertex.pxd b/src/h3/_cy/vertex.pxd new file mode 100644 index 0000000..98d890c --- /dev/null +++ b/src/h3/_cy/vertex.pxd @@ -0,0 +1,6 @@ +from .h3lib cimport bool, H3int + +cpdef H3int cell_to_vertex(H3int h, int vertex_num) except 1 +cpdef H3int[:] cell_to_vertexes(H3int h) +cpdef (double, double) vertex_to_latlng(H3int v) except * +cpdef bool is_valid_vertex(H3int v) diff --git a/src/h3/_cy/vertex.pyx b/src/h3/_cy/vertex.pyx new file mode 100644 index 0000000..26a674a --- /dev/null +++ b/src/h3/_cy/vertex.pyx @@ -0,0 +1,54 @@ +cimport h3lib +from h3lib cimport bool, H3int + +from .util cimport ( + check_cell, + check_vertex, + coord2deg +) + +from .error_system cimport check_for_error + +from .memory cimport H3MemoryManager + + +cpdef H3int cell_to_vertex(H3int h, int vertex_num) except 1: + cdef: + H3int out + + check_cell(h) + + check_for_error( + h3lib.cellToVertex(h, vertex_num, &out) + ) + + return out + +cpdef H3int[:] cell_to_vertexes(H3int h): + cdef: + H3int out + + check_cell(h) + + hmm = H3MemoryManager(6) + check_for_error( + h3lib.cellToVertexes(h, hmm.ptr) + ) + mv = hmm.to_mv() + + return mv + +cpdef (double, double) vertex_to_latlng(H3int v) except *: + cdef: + h3lib.LatLng c + + check_vertex(v) + + check_for_error( + h3lib.vertexToLatLng(v, &c) + ) + + return coord2deg(c) + +cpdef bool is_valid_vertex(H3int v): + return h3lib.isValidVertex(v) == 1 diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index d1122d8..8186189 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -996,3 +996,70 @@ def great_circle_distance(latlng1, latlng2, unit='km'): lat2, lng2, unit = unit ) + + +def cell_to_vertex(h, vertex_num): + """ + Return a (specified) vertex of an H3 cell. + + Parameters + ---------- + h : H3Cell + vertex_num : int + Vertex number (0-5) + + Returns + ------- + The vertex + """ + h = _in_scalar(h) + h = _cy.cell_to_vertex(h, vertex_num) + return _out_scalar(h) + + +def cell_to_vertexes(h): + """ + Return a list of vertexes of an H3 cell. + The list will be of length 5 for pentagons and 6 for hexagons. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + A list of vertexes + """ + h = _in_scalar(h) + mv = _cy.cell_to_vertexes(h) + return _out_collection(mv) + + +def vertex_to_latlng(v): + """ + Return latitude and longitude of a vertex. + + Returns + ------- + lat : float + Latitude + lng : float + Longitude + """ + v = _in_scalar(v) + return _cy.vertex_to_latlng(v) + + +def is_valid_vertex(v): + """ + Validates an H3 vertex. + + Returns + ------- + bool + """ + try: + v = _in_scalar(v) + return _cy.is_valid_vertex(v) + except (ValueError, TypeError): + return False diff --git a/tests/test_h3.py b/tests/test_h3.py index 186145f..567ba1f 100644 --- a/tests/test_h3.py +++ b/tests/test_h3.py @@ -387,3 +387,58 @@ def test_grid_path_cells(): with pytest.raises(h3.H3ResMismatchError): h3.grid_path_cells(h1, '8001fffffffffff') + + +def test_cell_to_vertex(): + # pentagon + assert h3.cell_to_vertex('814c3ffffffffff', 0) == '2014c3ffffffffff' + assert h3.cell_to_vertex('814c3ffffffffff', 1) == '2114c3ffffffffff' + assert h3.cell_to_vertex('814c3ffffffffff', 2) == '2214c3ffffffffff' + assert h3.cell_to_vertex('814c3ffffffffff', 3) == '2314c3ffffffffff' + assert h3.cell_to_vertex('814c3ffffffffff', 4) == '2414c3ffffffffff' + try: + h3.cell_to_vertex('814c3ffffffffff', 5) + except h3._cy.error_system.H3DomainError: + pass + else: + assert False + + # hexagon + assert h3.cell_to_vertex('814d7ffffffffff', 0) == '2014d7ffffffffff' + assert h3.cell_to_vertex('814d7ffffffffff', 1) == '2213abffffffffff' + assert h3.cell_to_vertex('814d7ffffffffff', 2) == '2113abffffffffff' + assert h3.cell_to_vertex('814d7ffffffffff', 3) == '2414c3ffffffffff' + assert h3.cell_to_vertex('814d7ffffffffff', 4) == '2314c3ffffffffff' + assert h3.cell_to_vertex('814d7ffffffffff', 5) == '2414cfffffffffff' + + +def test_cell_to_vertexes(): + # pentagon + assert h3.cell_to_vertexes('814c3ffffffffff') == [ + '2014c3ffffffffff', + '2114c3ffffffffff', + '2214c3ffffffffff', + '2314c3ffffffffff', + '2414c3ffffffffff', + ] + + # hexagon + assert h3.cell_to_vertexes('814d7ffffffffff') == [ + '2014d7ffffffffff', + '2213abffffffffff', + '2113abffffffffff', + '2414c3ffffffffff', + '2314c3ffffffffff', + '2414cfffffffffff', + ] + + +def test_vertex_to_latlng(): + latlng = h3.vertex_to_latlng('2114c3ffffffffff') + assert latlng == approx((24.945215618732814, -70.33904370008679)) + + +def test_is_valid_vertex(): + assert h3.is_valid_vertex('2114c3ffffffffff') + assert not h3.is_valid_vertex(2455495337847029759) + assert not h3.is_valid_vertex('foobar') From 4ced53da821827940531f0bfd5df323a726514aa Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 3 Sep 2024 16:12:49 -0700 Subject: [PATCH 092/177] Bump actions/download-artifact from 4.1.4 to 4.1.7 in /.github/workflows (#392) Bumps [actions/download-artifact](https://github.com/actions/download-artifact) from 4.1.4 to 4.1.7. - [Release notes](https://github.com/actions/download-artifact/releases) - [Commits](https://github.com/actions/download-artifact/compare/v4.1.4...v4.1.7) --- updated-dependencies: - dependency-name: actions/download-artifact dependency-type: direct:production ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/wheels.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 8df9ed8..91a9e44 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -177,7 +177,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/download-artifact@v4.1.4 + - uses: actions/download-artifact@v4.1.7 with: name: wheels_and_sdist path: dist From cec946a879eb7706e41a0526752dd688c6e56fd5 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Tue, 3 Sep 2024 17:13:21 -0700 Subject: [PATCH 093/177] prep for v4.0.0b6 release (#394) --- CHANGELOG.md | 6 +++++- src/h3/_version.py | 2 +- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 268c744..81e800c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,11 @@ Because H3-Py is versioned in lockstep with the H3 core library, please avoid adding features or APIs which do not map onto the [H3 core API](https://uber.github.io/h3/#/documentation/api-reference/). -## Unreleased - 2024-08-23 +## Unreleased + +None. + +## [4.0.0b6] - 2024-09-03 - Added bindings for `cellToVertex`, `cellToVertexes`, `vertexToLatLng`, and `isValidVertex` (#323) diff --git a/src/h3/_version.py b/src/h3/_version.py index d1d952c..41bf4d0 100644 --- a/src/h3/_version.py +++ b/src/h3/_version.py @@ -1,4 +1,4 @@ -__version__ = '4.0.0b5' +__version__ = '4.0.0b6' __description__ = 'Hierarchical hexagonal geospatial indexing system' __url__ = 'https://github.com/uber/h3-py' __license__ = 'Apache 2.0 License' From 65c3d9e105f49d3ec028a38a5a6d6b44126a7f5a Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Wed, 4 Sep 2024 15:02:35 -0700 Subject: [PATCH 094/177] Trying pyproject.toml and scikit-build-core (#378) * trying a scikit-build-core setup * trying things * vendor FindCython * fix build * remove unused * cython tests working * fix lint action * coverage fix * drop annotation stuff for now, because i can't get it working * book building * all target * try again * don't install all * numpy! * pip install h3.tar.gz[test] * drop wheel builds for 3.6 and 3.7 * move coverage config to pyproject.toml * remove requirements-dev.txt * remove cmake from the build system requirements * single sourcing the version number in _version.py * i think scikitbuild-core doesn't work with dynamic = ['version']. try something else * uber's * alphabetical files in cmakelists.txt * tidy up files in the sdist * move pytest config to pyproject.toml * CIBW_TEST_COMMAND: pytest * CIBW_TEST_COMMAND: pytest {project}/tests * CIBW_TEST_REQUIRES: pytest pytest-cov numpy * get better coverage on the testing code * fix api reference link (#385) * Added Bindings for Vertex-Related Functions (#388) * Update CHANGELOG.md * Update h3lib.pxd * Update latlng.pxd * Update latlng.pyx * Update util.pxd * Update util.pyx * Update _version.py * Update __init__.py * Update __init__.py * Update test_h3.py * Update __init__.py * Update test_h3.py * Update CHANGELOG.md * Update __init__.py * Update test_h3.py * Update _version.py * Update test_h3.py * Update __init__.py * Update CMakeLists.txt * Update latlng.pxd * Update latlng.pyx * Create vertex.pxd * Create vertex.pyx * Update __init__.py * Update test_h3.py * Update __init__.py * Update api_quick.md * Bump actions/download-artifact from 4.1.4 to 4.1.7 in /.github/workflows (#392) Bumps [actions/download-artifact](https://github.com/actions/download-artifact) from 4.1.4 to 4.1.7. - [Release notes](https://github.com/actions/download-artifact/releases) - [Commits](https://github.com/actions/download-artifact/compare/v4.1.4...v4.1.7) --- updated-dependencies: - dependency-name: actions/download-artifact dependency-type: direct:production ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * prep for v4.0.0b6 release (#394) * alphabetical files in cmakelists.txt * single * test with numpy>=2 * drop lower bound on numpy version --------- Signed-off-by: dependabot[bot] Co-authored-by: Isaac Brodsky Co-authored-by: Pieter Provoost Co-authored-by: Shiran Yuan Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .coveragerc | 5 -- .github/workflows/build_docs.yml | 2 - .github/workflows/coverage-lint.yml | 21 ++---- .github/workflows/tests.yml | 8 +-- .github/workflows/wheels.yml | 19 +----- CMakeLists.txt | 11 +++- MANIFEST.in | 24 ------- makefile | 24 +++---- pyproject.toml | 95 ++++++++++++++++++++++++++-- requirements-dev.txt | 8 --- requirements.in | 15 ----- setup.py | 44 ------------- src/h3/_cy/CMakeLists.txt | 40 ++++++------ src/h3/_version.py | 27 +------- tests/polyfill/test_polyfill.py | 6 +- tests/polyfill/test_polygon_class.py | 8 ++- tests/test_cython/test_cython.py | 4 +- tests/test_h3.py | 4 ++ 18 files changed, 159 insertions(+), 206 deletions(-) delete mode 100644 .coveragerc delete mode 100644 MANIFEST.in delete mode 100644 requirements-dev.txt delete mode 100644 requirements.in delete mode 100644 setup.py diff --git a/.coveragerc b/.coveragerc deleted file mode 100644 index 662935d..0000000 --- a/.coveragerc +++ /dev/null @@ -1,5 +0,0 @@ -[run] -omit = - */h3/api/basic_int/__init__.py - */h3/api/memview_int/__init__.py - */h3/api/numpy_int/__init__.py diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index 0ad48ba..328dc44 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -22,8 +22,6 @@ jobs: - name: Install dependencies run: | pip install --upgrade pip setuptools wheel - pip install -r requirements.in - pip install -r requirements-dev.txt pip install .[all] - name: Build the book diff --git a/.github/workflows/coverage-lint.yml b/.github/workflows/coverage-lint.yml index 24ec82e..0802169 100644 --- a/.github/workflows/coverage-lint.yml +++ b/.github/workflows/coverage-lint.yml @@ -23,10 +23,10 @@ jobs: - name: Install from source run: | pip install --upgrade pip setuptools wheel - pip install .[all] + pip install .[test] - name: Lint - run: flake8 src/h3 setup.py tests + run: flake8 src/h3 tests - name: Pylint # As a test for visibility of API bindings, we want to ensure that pylint has no @@ -35,9 +35,9 @@ jobs: - name: Coverage run: | - pip install Cython - cythonize -i tests/test_cython/cython_example.pyx - pytest --cov=h3 --full-trace --cov-report=xml + pip install cython + cythonize tests/test_cython/cython_example.pyx + pytest --cov-report=xml - name: Upload coverage to Codecov uses: codecov/codecov-action@v4.3.0 @@ -45,14 +45,3 @@ jobs: file: ./coverage.xml fail_ci_if_error: true token: ${{ secrets.CODECOV_TOKEN }} - - - name: Copy Cython annotations to project dir - run: | - mkdir annotations - cp _skbuild/*/cmake-build/src/h3/_cy/*.html ./annotations - - - name: Upload artifacts to GitHub - uses: actions/upload-artifact@v4.3.1 - with: - name: annotations - path: ./annotations diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index ee17503..8075b01 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -39,10 +39,10 @@ jobs: - name: Install from source run: | pip install --upgrade pip setuptools wheel - pip install .[all] + pip install .[test] - name: Tests run: | - pip install Cython - cythonize -i tests/test_cython/cython_example.pyx - pytest tests --cov=h3 --full-trace + pip install cython + cythonize tests/test_cython/cython_example.pyx + pytest diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 91a9e44..659a193 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -41,12 +41,11 @@ jobs: - name: Install from sdist run: | pip install --upgrade pip setuptools wheel - pip install pytest cp dist/h3-*.tar.gz h3.tar.gz - pip install h3.tar.gz[all] + pip install h3.tar.gz[test] - name: Test sdist - run: pytest --cov=h3 --full-trace + run: pytest - name: Upload artifacts to GitHub uses: actions/upload-artifact@v4.3.1 @@ -76,12 +75,6 @@ jobs: build: 'cp*-manylinux_x86_64' name: Linux Intel glibc 64-bit - - os: ubuntu-22.04 - build: 'cp36-musllinux_x86_64' - name: Linux Intel musl 64-bit 3.6 - - os: ubuntu-22.04 - build: 'cp37-musllinux_x86_64' - name: Linux Intel musl 64-bit 3.7 - os: ubuntu-22.04 build: 'cp38-musllinux_x86_64' name: Linux Intel musl 64-bit 3.8 @@ -98,12 +91,6 @@ jobs: build: 'cp312-musllinux_x86_64' name: Linux Intel musl 64-bit 3.12 - - os: ubuntu-22.04 - build: 'cp36-manylinux_aarch64' - name: Linux Aarch64 3.6 - - os: ubuntu-22.04 - build: 'cp37-manylinux_aarch64' - name: Linux Aarch64 3.7 - os: ubuntu-22.04 build: 'cp38-manylinux_aarch64' name: Linux Aarch64 3.8 @@ -143,7 +130,7 @@ jobs: - uses: pypa/cibuildwheel@v2.17.0 env: - CIBW_TEST_REQUIRES: pytest numpy + CIBW_TEST_REQUIRES: pytest pytest-cov numpy CIBW_TEST_COMMAND: pytest {project}/tests CIBW_ARCHS_LINUX: auto aarch64 CIBW_BUILD: ${{ matrix.build }} diff --git a/CMakeLists.txt b/CMakeLists.txt index 85ea71c..40ce38e 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,11 +1,16 @@ -cmake_minimum_required(VERSION 3.7.2) +cmake_minimum_required(VERSION 3.15...3.26) -project(h3) +project(${SKBUILD_PROJECT_NAME} LANGUAGES C) set(CMAKE_POSITION_INDEPENDENT_CODE ON) # Always make a release build set(CMAKE_BUILD_TYPE Release) +find_package( + Python + COMPONENTS Interpreter Development.Module + REQUIRED) + # Avoid building tooling we won't need for release # See all options with `cmake -LA` in an `h3/build` directory, # or at https://h3geo.org/docs/next/core-library/compilation-options/ @@ -37,4 +42,4 @@ install( FILES "${CMAKE_CURRENT_BINARY_DIR}/src/h3lib/src/h3lib/include/h3api.h" DESTINATION - src/h3/_cy) + ${SKBUILD_PROJECT_NAME}/_cy) diff --git a/MANIFEST.in b/MANIFEST.in deleted file mode 100644 index 6ccde1f..0000000 --- a/MANIFEST.in +++ /dev/null @@ -1,24 +0,0 @@ -# MANIFEST.in commands specified here: -# https://packaging.python.org/en/latest/guides/using-manifest-in/#manifest-in-commands - -include CHANGELOG.md -include CMakeLists.txt -include LICENSE -include makefile -include pyproject.toml -include readme.md -include requirements.in -include setup.py - -graft src/h3/ - -prune src/h3lib/ - -include src/h3lib/LICENSE -include src/h3lib/README.md -include src/h3lib/VERSION -include src/h3lib/CMakeLists.txt - -graft src/h3lib/cmake -graft src/h3lib/src/h3lib -exclude MANIFEST.in diff --git a/makefile b/makefile index 629caa7..a838caa 100644 --- a/makefile +++ b/makefile @@ -4,7 +4,7 @@ PYTHON=$(shell command -v python || command -v python3) build-docs: - ./env/bin/pip install -r requirements-dev.txt + ./env/bin/pip install .[all] ./env/bin/jupyter-book build docs/ --warningiserror --keep-going --all open: @@ -14,39 +14,35 @@ init: purge git submodule update --init $(PYTHON) -m venv env ./env/bin/pip install --upgrade pip wheel setuptools - ./env/bin/pip install .[all] - ./env/bin/pip install -r requirements.in + ./env/bin/pip install .[test] clear: -./env/bin/pip uninstall -y h3 -@rm -rf MANIFEST - -@rm -rf annotations - -@rm -rf .pytest_cache _skbuild dist .coverage build docs/_build + -@rm -rf .pytest_cache _skbuild dist .coverage build docs/_build .ruff_cache -@find . -type d -name '__pycache__' | xargs rm -r -@find . -type d -name '*.egg-info' | xargs rm -r -@find . -type f -name '*.pyc' | xargs rm -r -@find . -type f -name '*.so' | xargs rm -r -@find . -type d -name '*.ipynb_checkpoints' | xargs rm -r -@find ./tests -type f -name '*.c' | xargs rm -r + -@find ./tests -type f -name '*.html' | xargs rm -r rebuild: clear - ./env/bin/pip install .[all] + ./env/bin/pip install .[test] purge: clear -@rm -rf env -annotations: rebuild - mkdir -p annotations - cp _skbuild/*/cmake-build/src/h3/_cy/*.html ./annotations - test: - ./env/bin/cythonize -i tests/test_cython/cython_example.pyx - ./env/bin/pytest tests --cov=h3 --cov-report term-missing --durations=10 + ./env/bin/pip install cython + ./env/bin/cythonize tests/test_cython/cython_example.pyx + ./env/bin/pytest lint: - ./env/bin/flake8 src/h3 setup.py tests + ./env/bin/flake8 src/h3 tests ./env/bin/pylint --disable=all --enable=import-error tests/ lab: - ./env/bin/pip install -r requirements-dev.txt + ./env/bin/pip install .[all] ./env/bin/jupyter lab diff --git a/pyproject.toml b/pyproject.toml index ce6867f..c6a6ddb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,93 @@ [build-system] -requires = [ - 'scikit-build', - 'cython', - 'cmake', +requires = ['scikit-build-core', 'cython'] +build-backend = 'scikit_build_core.build' + +[project] +name = 'h3' +version = '4.0.0b6' +description = "Uber's hierarchical hexagonal geospatial indexing system" +readme = 'readme.md' +license = {file = 'LICENSE'} +authors = [ + { name = 'Uber Technologies', email = 'ajfriend@gmail.com' }, +] +maintainers = [ + { name = 'AJ Friend', email = 'ajfriend@gmail.com' }, +] +requires-python = '>=3.8' + +dependencies = [] + +classifiers = [ + 'Development Status :: 5 - Production/Stable', + 'Intended Audience :: Developers', + 'Intended Audience :: Science/Research', + 'License :: OSI Approved :: Apache Software License', + 'Programming Language :: C', + 'Programming Language :: Cython', + 'Programming Language :: Python :: 3.8', + 'Programming Language :: Python :: 3.9', + 'Programming Language :: Python :: 3.10', + 'Programming Language :: Python :: 3.11', + 'Programming Language :: Python :: 3.12', + 'Operating System :: MacOS :: MacOS X', + 'Operating System :: POSIX :: Linux', + 'Operating System :: Microsoft :: Windows', + 'Topic :: Scientific/Engineering :: GIS', +] + +[project.urls] +Homepage = 'https://github.com/organization/package' +Documentation = 'https://package.readthedocs.io/' +'Bug Tracker' = 'https://github.com/organization/package/issues' +Discussions = 'https://github.com/organization/package/discussions' +Changelog = 'https://package.readthedocs.io/en/latest/changelog.html' + + +[project.optional-dependencies] +numpy = ['numpy'] +test = ['pytest', 'pytest-cov', 'flake8', 'pylint', 'numpy'] +all = [ + 'jupyter-book', + 'flake8', + 'sphinx>=7.3.3', # https://github.com/sphinx-doc/sphinx/issues/12290 + 'jupyterlab', + 'jupyterlab-geojson', + 'geopandas', + 'geodatasets', + 'matplotlib', + 'contextily', + 'cartopy', + 'geoviews', + 'numpy', + 'pytest', + 'pytest-cov', + 'pylint', +] + +[tool.pytest.ini_options] +addopts = "--cov=h3 --cov=tests --cov-report=term-missing --durations=10" + +[tool.coverage.run] +omit = [ + '*/h3/api/basic_int/__init__.py', + '*/h3/api/memview_int/__init__.py', + '*/h3/api/numpy_int/__init__.py' +] + + +[tool.scikit-build] +sdist.exclude = [ + 'src/h3lib', + 'docs', + 'dev_notes.md', + 'makefile', +] +sdist.include = [ + 'src/h3lib/LICENSE', + 'src/h3lib/README.md', + 'src/h3lib/VERSION', + 'src/h3lib/CMakeLists.txt', + 'src/h3lib/cmake/*', + 'src/h3lib/src/h3lib/*' ] diff --git a/requirements-dev.txt b/requirements-dev.txt deleted file mode 100644 index c6ffe77..0000000 --- a/requirements-dev.txt +++ /dev/null @@ -1,8 +0,0 @@ -jupyterlab -jupyterlab-geojson -geopandas -geodatasets -matplotlib -contextily -cartopy -geoviews diff --git a/requirements.in b/requirements.in deleted file mode 100644 index dc355b9..0000000 --- a/requirements.in +++ /dev/null @@ -1,15 +0,0 @@ -# Required for pip-compile until -# https://github.com/jazzband/pip-tools/issues/1047 is resolved. -# -# In the meantime, this information is duplicated from -# pyproject.toml - -scikit-build -cython -cmake - -# for docs - -jupyter-book -flake8 -sphinx>=7.3.3 # https://github.com/sphinx-doc/sphinx/issues/12290 diff --git a/setup.py b/setup.py deleted file mode 100644 index 23353b1..0000000 --- a/setup.py +++ /dev/null @@ -1,44 +0,0 @@ -import os -from setuptools import find_packages -from skbuild import setup - -here = os.path.abspath(os.path.dirname(__file__)) - -about = {} -with open(os.path.join(here, 'src', 'h3', '_version.py')) as f: - exec(f.read(), about) - - -def long_desc(): - here = os.path.abspath(os.path.dirname(__file__)) - fname = os.path.join(here, 'readme.md') - with open(fname) as f: - long_description = f.read() - - return long_description - - -setup( - name = 'h3', - version = about['__version__'], - description = about['__description__'], - long_description = long_desc(), - long_description_content_type = 'text/markdown', - license = about['__license__'], - author = about['__author__'], - author_email = about['__author_email__'], - url = about['__url__'], - classifiers = about['__classifiers__'], - include_package_data=True, - packages = find_packages( - 'src', - exclude = ["*.tests", "*.tests.*", "tests.*", "tests"], - ), - package_dir = {'': 'src'}, - cmake_languages = ('C'), - extras_require={ - 'numpy': ['numpy'], - 'test': ['pytest', 'pytest-cov', 'flake8', 'pylint'], - 'all': ['numpy', 'pytest', 'pytest-cov', 'flake8', 'pylint'], - }, -) diff --git a/src/h3/_cy/CMakeLists.txt b/src/h3/_cy/CMakeLists.txt index 52e0156..2cb2b6f 100644 --- a/src/h3/_cy/CMakeLists.txt +++ b/src/h3/_cy/CMakeLists.txt @@ -1,31 +1,35 @@ -find_package(Cython MODULE REQUIRED) -find_package(PythonExtensions MODULE REQUIRED) +list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}) include_directories(${CMAKE_CURRENT_SOURCE_DIR}) -# Build Cython annotations -set(CYTHON_ANNOTATE TRUE) - macro(add_cython_file filename) - add_cython_target(${filename} C PY3) - add_library(${filename} MODULE ${filename} ${LIB_SOURCE_FILES} ${CONFIGURED_API_HEADER}) - python_extension_module(${filename}) + add_custom_command( + OUTPUT "${filename}.c" + COMMENT + "Making ${CMAKE_CURRENT_BINARY_DIR}/${filename}.c from ${CMAKE_CURRENT_SOURCE_DIR}/${filename}.pyx" + COMMAND Python::Interpreter -m cython + "${CMAKE_CURRENT_SOURCE_DIR}/${filename}.pyx" --output-file "${filename}.c" -I ${CMAKE_CURRENT_SOURCE_DIR} + DEPENDS "${filename}.pyx" + VERBATIM) + + python_add_library(${filename} MODULE "${filename}.c" WITH_SOABI) + set_property(TARGET ${filename} PROPERTY C_STANDARD 99) - target_link_libraries(${filename} h3) - install(TARGETS ${filename} LIBRARY DESTINATION src/h3/_cy) + target_link_libraries(${filename} PRIVATE h3) + install(TARGETS ${filename} LIBRARY DESTINATION ${SKBUILD_PROJECT_NAME}/_cy) endmacro() # GLOB pattern is recommended against # https://cmake.org/cmake/help/v3.14/command/file.html?highlight=file#filesystem -add_cython_file(util) -add_cython_file(latlng) add_cython_file(cells) add_cython_file(edges) -add_cython_file(to_multipoly) add_cython_file(error_system) +add_cython_file(latlng) add_cython_file(memory) add_cython_file(vertex) +add_cython_file(to_multipoly) +add_cython_file(util) # Include pyx and pxd files in distribution for use by Cython API install( @@ -34,16 +38,16 @@ install( cells.pyx edges.pxd edges.pyx + error_system.pyx + h3lib.pxd latlng.pxd latlng.pyx - h3lib.pxd - util.pxd - util.pyx - error_system.pyx memory.pxd memory.pyx + util.pxd + util.pyx vertex.pxd vertex.pyx DESTINATION - src/h3/_cy + ${SKBUILD_PROJECT_NAME}/_cy ) diff --git a/src/h3/_version.py b/src/h3/_version.py index 41bf4d0..712565a 100644 --- a/src/h3/_version.py +++ b/src/h3/_version.py @@ -1,24 +1,3 @@ -__version__ = '4.0.0b6' -__description__ = 'Hierarchical hexagonal geospatial indexing system' -__url__ = 'https://github.com/uber/h3-py' -__license__ = 'Apache 2.0 License' -__author__ = 'Uber Technologies' -__author_email__ = 'AJ Friend ' -__classifiers__ = [ - 'Development Status :: 5 - Production/Stable', - 'Intended Audience :: Developers', - 'Intended Audience :: Science/Research', - 'License :: OSI Approved :: Apache Software License', - 'Programming Language :: C', - 'Programming Language :: Cython', - 'Programming Language :: Python :: 3.7', - 'Programming Language :: Python :: 3.8', - 'Programming Language :: Python :: 3.9', - 'Programming Language :: Python :: 3.10', - 'Programming Language :: Python :: 3.11', - 'Programming Language :: Python :: 3.12', - 'Operating System :: MacOS :: MacOS X', - 'Operating System :: POSIX :: Linux', - 'Operating System :: Microsoft :: Windows', - 'Topic :: Scientific/Engineering :: GIS', -] +from importlib import metadata + +__version__ = metadata.version(__package__ or __name__) diff --git a/tests/polyfill/test_polyfill.py b/tests/polyfill/test_polyfill.py index b78e875..1431b87 100644 --- a/tests/polyfill/test_polyfill.py +++ b/tests/polyfill/test_polyfill.py @@ -135,12 +135,10 @@ def test_invalid_polygon(): some `cdef` functions. """ with pytest.raises(TypeError): - poly = h3.LatLngPoly([1, 2, 3]) - h3.h3shape_to_cells(poly, 4) + h3.LatLngPoly([1, 2, 3]) with pytest.raises(ValueError): - poly = h3.LatLngPoly([[1, 2, 3]]) - h3.h3shape_to_cells(poly, 4) + h3.LatLngPoly([[1, 2, 3]]) def test_bad_geo_input(): diff --git a/tests/polyfill/test_polygon_class.py b/tests/polyfill/test_polygon_class.py index c38505d..3996d30 100644 --- a/tests/polyfill/test_polygon_class.py +++ b/tests/polyfill/test_polygon_class.py @@ -39,8 +39,10 @@ def test_LatLngPoly_len(): def test_bad_subclass(): class H3Shoop(h3.H3Shape): - def __geo_interface__(): - pass + def __geo_interface__(self): + return 'foo' + shoop = H3Shoop() + shoop.__geo_interface__() with pytest.raises(ValueError): - h3.h3shape_to_cells(H3Shoop(), res=9) + h3.h3shape_to_cells(shoop, res=9) diff --git a/tests/test_cython/test_cython.py b/tests/test_cython/test_cython.py index 89aa064..1833de3 100644 --- a/tests/test_cython/test_cython.py +++ b/tests/test_cython/test_cython.py @@ -12,7 +12,7 @@ np.random.seed(0) def test_cython_api(): if latlng_to_cell_vect is None: - print("Not running Cython test because cython example was not compiled") + print('Not running Cython test because cython example was not compiled') return N = 100000 @@ -22,7 +22,7 @@ def test_cython_api(): lats = np.array(lats, dtype=np.float64) lngs = np.array(lngs, dtype=np.float64) - out = np.zeros(len(lats), dtype="uint64") + out = np.zeros(len(lats), dtype='uint64') latlng_to_cell_vect(lats, lngs, res, out) assert out[0] == 617284541015654399 diff --git a/tests/test_h3.py b/tests/test_h3.py index 567ba1f..051480a 100644 --- a/tests/test_h3.py +++ b/tests/test_h3.py @@ -6,6 +6,10 @@ import h3 from . import util as u +def test_approx_helper(): + assert not u.approx2('abc', 'abdc') + + def test_is_valid_cell(): assert h3.is_valid_cell('85283473fffffff') assert h3.is_valid_cell('850dab63fffffff') From 5c8e100fdc34de4bfffb92396a1c125476d63c1a Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Wed, 4 Sep 2024 15:24:32 -0700 Subject: [PATCH 095/177] prep for beta 7 release (#397) --- CHANGELOG.md | 4 ++++ pyproject.toml | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 81e800c..4324261 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ avoid adding features or APIs which do not map onto the None. +## [4.0.0b7] - 2024-09-04 + +- Use `pyproject.toml` and `scikit-build-core` (#378) + ## [4.0.0b6] - 2024-09-03 - Added bindings for `cellToVertex`, `cellToVertexes`, `vertexToLatLng`, and `isValidVertex` (#323) diff --git a/pyproject.toml b/pyproject.toml index c6a6ddb..7507a6c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.0.0b6' +version = '4.0.0b7' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} From 6c4ae92b240af658a6d23eb8d93fa2246dca8b73 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 26 Sep 2024 12:44:01 -0700 Subject: [PATCH 096/177] i like this order better (#400) --- docs/api_quick.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api_quick.md b/docs/api_quick.md index 0753ddb..a8c585c 100644 --- a/docs/api_quick.md +++ b/docs/api_quick.md @@ -103,10 +103,10 @@ Functions relating H3 objects to geographic (lat/lng) coordinates. .. autosummary:: cells_to_directed_edge - get_directed_edge_destination directed_edge_to_cells - origin_to_directed_edges get_directed_edge_origin + get_directed_edge_destination + origin_to_directed_edges ``` ## Vertexes From 919aad8b5d6e346797bacfc8abbeea9e60f7ebf4 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 26 Sep 2024 14:51:27 -0700 Subject: [PATCH 097/177] polygon_to_cells alias (#399) --- src/h3/api/basic_int/__init__.py | 7 +++++++ tests/polyfill/test_h3.py | 10 ++++++++++ 2 files changed, 17 insertions(+) diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index 8186189..d292ed6 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -446,6 +446,13 @@ def h3shape_to_cells(h3shape, res): return _out_collection(mv) +def polygon_to_cells(h3shape, res): + """ + Alias for ``h3shape_to_cells``. + """ + return h3shape_to_cells(h3shape, res) + + def cells_to_h3shape(cells, *, tight=True): """ Return an ``H3Shape`` describing the area covered by a collection of H3 cells. diff --git a/tests/polyfill/test_h3.py b/tests/polyfill/test_h3.py index b6de101..8d9d948 100644 --- a/tests/polyfill/test_h3.py +++ b/tests/polyfill/test_h3.py @@ -107,6 +107,16 @@ def test_polyfill(): assert '89283095edbffff' in out +def test_polygon_to_cells(): + poly = h3.LatLngPoly(sf_7x7) + # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` + out = h3.polygon_to_cells(poly, res=9) + + assert len(out) == 1253 + assert '89283080527ffff' in out + assert '89283095edbffff' in out + + def test_polyfill_with_hole(): poly = h3.LatLngPoly(sf_7x7, sf_hole1) From 7cea748f5a1138b5bd06a68b330d0c4625a9135b Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 26 Sep 2024 18:50:06 -0700 Subject: [PATCH 098/177] bump h3lib to v4.1.0 (#402) * bump h3lib to v4.1.0 * passing tests --- pyproject.toml | 2 +- src/h3/_cy/latlng.pyx | 4 ++++ src/h3lib | 2 +- 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 7507a6c..02219b0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.0.0b7' +version = '4.1.0b1' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} diff --git a/src/h3/_cy/latlng.pyx b/src/h3/_cy/latlng.pyx index c3e0cdb..493b85a 100644 --- a/src/h3/_cy/latlng.pyx +++ b/src/h3/_cy/latlng.pyx @@ -157,6 +157,10 @@ def polygon_to_cells(outer, int res, holes=None): uint64_t n check_res(res) + + if not outer: + return H3MemoryManager(0).to_mv() + gp = GeoPolygon(outer, holes=holes) check_for_error( diff --git a/src/h3lib b/src/h3lib index 46a581c..5c91149 160000 --- a/src/h3lib +++ b/src/h3lib @@ -1 +1 @@ -Subproject commit 46a581c905b2747c861aa1683125276501f68a3b +Subproject commit 5c91149104ac02c4f06faa4fc557e69cf6b131ef From b168018dae1aeabfaa72520813aa0d50236fd2c9 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 26 Sep 2024 19:08:35 -0700 Subject: [PATCH 099/177] Prep for v4.1.0b1 release (#403) --- CHANGELOG.md | 4 ++++ dev_notes.md | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4324261..51cbf64 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ avoid adding features or APIs which do not map onto the None. +## [4.1.0b1] - 2024-09-26 + +- Bump h3lib to v4.1.0 (#402) + ## [4.0.0b7] - 2024-09-04 - Use `pyproject.toml` and `scikit-build-core` (#378) diff --git a/dev_notes.md b/dev_notes.md index f1b3d53..71d514d 100644 --- a/dev_notes.md +++ b/dev_notes.md @@ -48,7 +48,7 @@ git submodule update --init ## Releasing a new version - update `CHANGELOG.md` to reflect any changes since the last release -- update the `h3-py` version in `src/h3/_version.py` +- update the `h3-py` version in `pyproject.toml` - create PR, get reviews, and merge with these changes - go to https://github.com/uber/h3-py/releases and "Draft a new release" - set the tag version and the release to the version. e.g., `v3.7.2` From 259f31b6c861b06c8e843525c0a8b7df9f009bab Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Fri, 27 Sep 2024 15:25:56 -0700 Subject: [PATCH 100/177] cell_to_child_pos, child_pos_to_cell, cell_to_children_size (#405) * cell_to_child_pos and child_pos_to_cell * start exposing cell_to_children_size * checking resolutions * cell_to_children_size python function * adding tests from https://github.com/uber/h3-py/pull/404 * fiddling * fix test_cell_to_vertex; helps coverage by removing untouched branch * more tests * lint * exhaustive test for a few resolution pairs * lint * doc strings * error messages * stricter test * playing with argument order. example code in tests looks nicer * use parent_res instead of res * Use `res_*` instead of `*_res` * fix up changelog --- CHANGELOG.md | 5 +- docs/api_quick.md | 3 ++ src/h3/_cy/__init__.py | 3 ++ src/h3/_cy/cells.pxd | 3 ++ src/h3/_cy/cells.pyx | 48 +++++++++++++++--- src/h3/_cy/h3lib.pxd | 2 + src/h3/api/basic_int/__init__.py | 84 +++++++++++++++++++++++++++++--- tests/test_h3.py | 73 +++++++++++++++++++++++++-- 8 files changed, 202 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 51cbf64..69d7487 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,11 +16,12 @@ avoid adding features or APIs which do not map onto the ## Unreleased -None. +- Add `cell_to_child_pos`, `child_pos_to_cell`, `cell_to_children_size` (#405) ## [4.1.0b1] - 2024-09-26 - Bump h3lib to v4.1.0 (#402) +- Add `polygon_to_cells` alias (#399) ## [4.0.0b7] - 2024-09-04 @@ -28,7 +29,7 @@ None. ## [4.0.0b6] - 2024-09-03 -- Added bindings for `cellToVertex`, `cellToVertexes`, `vertexToLatLng`, and `isValidVertex` (#323) +- Added bindings for `cellToVertex`, `cellToVertexes`, `vertexToLatLng`, and `isValidVertex` (#388) ## [4.0.0b5] - 2024-05-19 diff --git a/docs/api_quick.md b/docs/api_quick.md index a8c585c..5503bae 100644 --- a/docs/api_quick.md +++ b/docs/api_quick.md @@ -79,6 +79,9 @@ Functions relating H3 objects to geographic (lat/lng) coordinates. 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 ``` diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index c739bc0..804b6b0 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -22,7 +22,10 @@ from .cells import ( grid_distance, grid_disk, grid_ring, + cell_to_children_size, cell_to_children, + cell_to_child_pos, + child_pos_to_cell, compact_cells, uncompact_cells, get_num_cells, diff --git a/src/h3/_cy/cells.pxd b/src/h3/_cy/cells.pxd index b6a36d1..06b35ee 100644 --- a/src/h3/_cy/cells.pxd +++ b/src/h3/_cy/cells.pxd @@ -8,8 +8,11 @@ cpdef int grid_distance(H3int h1, H3int h2) except -1 cpdef H3int[:] grid_disk(H3int h, int k) cpdef H3int[:] grid_ring(H3int h, int k) cpdef H3int cell_to_parent(H3int h, res=*) except 0 +cpdef int64_t cell_to_children_size(H3int h, res=*) except -1 cpdef H3int[:] cell_to_children(H3int h, res=*) cpdef H3int cell_to_center_child(H3int h, res=*) except 0 +cpdef int64_t cell_to_child_pos(H3int child, int parent_res) except -1 +cpdef H3int child_pos_to_cell(H3int parent, int child_res, int64_t child_pos) except 0 cpdef H3int[:] compact_cells(const H3int[:] hu) cpdef H3int[:] uncompact_cells(const H3int[:] hc, int res) cpdef int64_t get_num_cells(int resolution) except -1 diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 64be807..2b57af2 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -3,7 +3,7 @@ from .h3lib cimport bool, int64_t, H3int, H3ErrorCodes from .util cimport ( check_cell, - check_res, + check_res, # we don't use? check_distance, ) @@ -139,12 +139,12 @@ cpdef H3int[:] grid_ring(H3int h, int k): return mv + cpdef H3int cell_to_parent(H3int h, res=None) except 0: cdef: H3int parent - check_cell(h) # todo: do we want to check for validity here? or leave correctness to the user? - + check_cell(h) if res is None: res = get_resolution(h) - 1 @@ -157,12 +157,11 @@ cpdef H3int cell_to_parent(H3int h, res=None) except 0: return parent -cpdef H3int[:] cell_to_children(H3int h, res=None): +cpdef int64_t cell_to_children_size(H3int h, res=None) except -1: cdef: int64_t n check_cell(h) - if res is None: res = get_resolution(h) + 1 @@ -172,6 +171,16 @@ cpdef H3int[:] cell_to_children(H3int h, res=None): msg = msg.format(res, hex(h)) check_for_error_msg(err, msg) + return n + + +cpdef H3int[:] cell_to_children(H3int h, res=None): + check_cell(h) + if res is None: + res = get_resolution(h) + 1 + + n = cell_to_children_size(h, res) + hmm = H3MemoryManager(n) check_for_error( h3lib.cellToChildren(h, res, hmm.ptr) @@ -181,12 +190,12 @@ cpdef H3int[:] cell_to_children(H3int h, res=None): return mv + cpdef H3int cell_to_center_child(H3int h, res=None) except 0: cdef: H3int child check_cell(h) - if res is None: res = get_resolution(h) + 1 @@ -199,6 +208,33 @@ cpdef H3int cell_to_center_child(H3int h, res=None) except 0: return child +cpdef int64_t cell_to_child_pos(H3int child, int parent_res) except -1: + cdef: + int64_t child_pos + + check_cell(child) + err = h3lib.cellToChildPos(child, parent_res, &child_pos) + if err: + msg = "Couldn't find child pos of cell {} at res {}." + msg = msg.format(hex(child), parent_res) + check_for_error_msg(err, msg) + + return child_pos + + +cpdef H3int child_pos_to_cell(H3int parent, int child_res, int64_t child_pos) except 0: + cdef: + H3int child + + check_cell(parent) + err = h3lib.childPosToCell(child_pos, parent, child_res, &child) + if err: + msg = "Couldn't find child with pos {} at res {} from parent {}." + msg = msg.format(child_pos, child_res, hex(parent)) + check_for_error_msg(err, msg) + + return child + cpdef H3int[:] compact_cells(const H3int[:] hu): # todo: fix this with my own Cython object "wrapper" class? diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index eae1b85..a578a8f 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -90,6 +90,8 @@ cdef extern from 'h3api.h': H3Error cellToParent( H3int h, int parentRes, H3int *parent) nogil H3Error cellToCenterChild(H3int h, int childRes, H3int *child) nogil + H3Error cellToChildPos(H3int child, int parentRes, int64_t *out) nogil + H3Error childPosToCell(int64_t childPos, H3int parent, int childRes, H3int *child) nogil H3Error cellToChildrenSize(H3int h, int childRes, int64_t *num) nogil # num/out/N? H3Error cellToChildren( H3int h, int childRes, H3int *children) nogil diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index d292ed6..6035966 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -185,7 +185,8 @@ def cell_to_latlng(h): lng : float Longitude """ - return _cy.cell_to_latlng(_in_scalar(h)) + h = _in_scalar(h) + return _cy.cell_to_latlng(h) def get_resolution(h): @@ -201,7 +202,8 @@ def get_resolution(h): int """ # todo: could also work for edges - return _cy.get_resolution(_in_scalar(h)) + h = _in_scalar(h) + return _cy.get_resolution(h) def cell_to_parent(h, res=None): @@ -266,7 +268,8 @@ def cell_to_boundary(h): ------- tuple of (lat, lng) tuples """ - return _cy.cell_to_boundary(_in_scalar(h)) + h = _in_scalar(h) + return _cy.cell_to_boundary(h) def grid_disk(h, k=1): @@ -288,7 +291,8 @@ def grid_disk(h, k=1): ----- There is currently no guaranteed order of the output cells. """ - mv = _cy.grid_disk(_in_scalar(h), k) + h = _in_scalar(h) + mv = _cy.grid_disk(h, k) return _out_collection(mv) @@ -312,11 +316,32 @@ def grid_ring(h, k=1): ----- There is currently no guaranteed order of the output cells. """ - mv = _cy.grid_ring(_in_scalar(h), k) + h = _in_scalar(h) + mv = _cy.grid_ring(h, k) return _out_collection(mv) +def cell_to_children_size(h, res=None): + """ + Number of children at resolution ``res`` of given cell. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the children. + If ``None``, then ``res = resolution(h) + 1`` + + Returns + ------- + int + Count of children + """ + h = _in_scalar(h) + return _cy.cell_to_children_size(h, res) + + def cell_to_children(h, res=None): """ Children of a cell as an unordered collection. @@ -336,11 +361,58 @@ def cell_to_children(h, res=None): ----- There is currently no guaranteed order of the output cells. """ - mv = _cy.cell_to_children(_in_scalar(h), res) + h = _in_scalar(h) + mv = _cy.cell_to_children(h, res) return _out_collection(mv) +def cell_to_child_pos(child, res_parent): + """ + Child position index of given cell, with respect to its parent at ``res_parent``. + + The reverse operation can be done with ``child_pos_to_cell``. + + Parameters + ---------- + child : H3Cell + res_parent : int + + Returns + ------- + int + Integer index of the child with respect to parent cell. + """ + child = _in_scalar(child) + return _cy.cell_to_child_pos(child, res_parent) + + +def child_pos_to_cell(parent, res_child, child_pos): + """ + Get child H3 cell from a parent cell, child resolution, and child position index. + + The reverse operation can be done with ``cell_to_child_pos``. + + Parameters + ---------- + parent : H3Cell + res_child : int + Child cell resolution + child_pos : int + Integer position of child cell, releative to parent. + + + Returns + ------- + H3Cell + """ + parent = _in_scalar(parent) + child = _cy.child_pos_to_cell(parent, res_child, child_pos) + child = _out_scalar(child) + + return child + + # todo: nogil for expensive C operation? def compact_cells(cells): """ diff --git a/tests/test_h3.py b/tests/test_h3.py index 051480a..760c3fa 100644 --- a/tests/test_h3.py +++ b/tests/test_h3.py @@ -400,12 +400,9 @@ def test_cell_to_vertex(): assert h3.cell_to_vertex('814c3ffffffffff', 2) == '2214c3ffffffffff' assert h3.cell_to_vertex('814c3ffffffffff', 3) == '2314c3ffffffffff' assert h3.cell_to_vertex('814c3ffffffffff', 4) == '2414c3ffffffffff' - try: + + with pytest.raises(h3.H3DomainError): h3.cell_to_vertex('814c3ffffffffff', 5) - except h3._cy.error_system.H3DomainError: - pass - else: - assert False # hexagon assert h3.cell_to_vertex('814d7ffffffffff', 0) == '2014d7ffffffffff' @@ -446,3 +443,69 @@ def test_is_valid_vertex(): assert h3.is_valid_vertex('2114c3ffffffffff') assert not h3.is_valid_vertex(2455495337847029759) assert not h3.is_valid_vertex('foobar') + + +def test_child_pos(): + h = '88283080ddfffff' + + assert h3.cell_to_child_pos(h, 8) == 0 + assert h3.cell_to_child_pos(h, 7) == 6 + assert h3.cell_to_child_pos(h, 6) == 41 + + with pytest.raises(h3.H3BaseException): + h3.cell_to_child_pos(h, 9) + + with pytest.raises(h3.H3BaseException): + h3.child_pos_to_cell(h, 9, -1) + + with pytest.raises(h3.H3BaseException): + h3.child_pos_to_cell(h, 9, 10000) + + +def test_child_pos2(): + h = '88283080ddfffff' + assert h == h3.child_pos_to_cell(h, 8, 0) + assert h == h3.child_pos_to_cell(h3.cell_to_parent(h, 7), 8, 6) + assert h == h3.child_pos_to_cell(h3.cell_to_parent(h, 6), 8, 41) + + +def test_cell_to_children_size(): + h = '8053fffffffffff' # hexagon + for r in range(16): + assert h3.cell_to_children_size(h, r) == 7**r + + +def test_cell_to_children_size2(): + cells = h3.get_res0_cells() + + for r in range(16): + total_cells = 120 * (7**r) + 2 + + assert total_cells == sum( + h3.cell_to_children_size(h, r) + for h in cells + ) + + +def test_child_pos3(): + def cells_at_res(res): + cells = h3.get_res0_cells() + for parent in cells: + yield from h3.cell_to_children(parent, res) + + def roundtrip(child, res_parent): + res_child = h3.get_resolution(child) + parent = h3.cell_to_parent(child, res_parent) + pos = h3.cell_to_child_pos(child, res_parent) + return h3.child_pos_to_cell(parent, res_child, pos) + + res_pairs = [ + (res_parent, res_child) + for res_parent in [0, 1] + for res_child in [0, 1, 2, 3] + if res_parent <= res_child + ] + + for res_parent, res_child in res_pairs: + for child in cells_at_res(res_child): + assert child == roundtrip(child, res_parent) From 5d9acb06e04dc1218e965f56ace1f9dea39f46c7 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Fri, 27 Sep 2024 15:39:09 -0700 Subject: [PATCH 101/177] Prep for v4.1.0b2 (#406) --- CHANGELOG.md | 4 ++++ pyproject.toml | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 69d7487..ee38256 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,10 @@ avoid adding features or APIs which do not map onto the ## Unreleased +None. + +## [4.1.0b2] - 2024-09-27 + - Add `cell_to_child_pos`, `child_pos_to_cell`, `cell_to_children_size` (#405) ## [4.1.0b1] - 2024-09-26 diff --git a/pyproject.toml b/pyproject.toml index 02219b0..e448802 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.1.0b1' +version = '4.1.0b2' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} From 98bf22a9da8b46c8128f0b3d858313fe15a5dca8 Mon Sep 17 00:00:00 2001 From: Jongbin Jung Date: Sat, 5 Oct 2024 10:43:40 -0700 Subject: [PATCH 102/177] Support `str`-like values for str_to_int (#408) * Add failing test * Explicitly convert to str before calling _cy.str_to_int --- src/h3/api/basic_int/__init__.py | 2 +- tests/test_apis/test_numpy_int.py | 21 ++++++++++++++++++++- 2 files changed, 21 insertions(+), 2 deletions(-) diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index 6035966..992fce7 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -53,7 +53,7 @@ def str_to_int(h): int Unsigned 64-bit integer """ - return _cy.str_to_int(h) + return _cy.str_to_int(str(h)) def int_to_str(x): diff --git a/tests/test_apis/test_numpy_int.py b/tests/test_apis/test_numpy_int.py index 2ffa43f..c341b55 100644 --- a/tests/test_apis/test_numpy_int.py +++ b/tests/test_apis/test_numpy_int.py @@ -5,7 +5,10 @@ from .. import util as u def test1(): - lat, lng = 37.7752702151959, -122.418307270836, + lat, lng = ( + 37.7752702151959, + -122.418307270836, + ) assert h3.latlng_to_cell(lat, lng, 9) == 617700169958293503 @@ -31,3 +34,19 @@ def test_compact_cells(): assert isinstance(cells, np.ndarray) assert h3.compact_cells(cells) == [h] + + +def test_numpy_str(): + expected = [ + 617700169957507071, + 617700169957769215, + 617700169958031359, + 617700169958293503, + 617700169961177087, + 617700169964847103, + 617700169965109247, + ] + cells = np.array([h3.int_to_str(h) for h in expected]) + got = [h3.str_to_int(c) for c in cells] + + assert expected == got From 91ab2bf3ea9ee7ef455fd9062f1895c900ea00f6 Mon Sep 17 00:00:00 2001 From: Jongbin Jung Date: Sat, 5 Oct 2024 14:00:48 -0700 Subject: [PATCH 103/177] Use local lcov for PRs and codecov for push to master (#413) --- .github/workflows/coverage-lint-pr.yml | 45 ++++++++++++++++++++++++++ .github/workflows/coverage-lint.yml | 2 -- .gitignore | 1 + 3 files changed, 46 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/coverage-lint-pr.yml diff --git a/.github/workflows/coverage-lint-pr.yml b/.github/workflows/coverage-lint-pr.yml new file mode 100644 index 0000000..eb689e3 --- /dev/null +++ b/.github/workflows/coverage-lint-pr.yml @@ -0,0 +1,45 @@ +name: pr-coverage-lint + +on: + pull_request: + branches: ['*'] + +jobs: + tests: + name: Coverage and Lint + runs-on: ubuntu-22.04 + + steps: + - uses: actions/checkout@v4.1.1 + with: + submodules: recursive + + - uses: actions/setup-python@v5.0.0 + with: + python-version: 3.11 + + - name: Install from source + run: | + pip install --upgrade pip setuptools wheel + pip install .[test] + + - name: Lint + run: flake8 src/h3 tests + + - name: Pylint + # As a test for visibility of API bindings, we want to ensure that pylint has no + # `import-error` warnings for h3 imports. + run: pylint --disable=all --enable=import-error tests/ + + - name: Coverage + run: | + pip install cython + cythonize tests/test_cython/cython_example.pyx + pytest --cov-report=lcov + + - name: Report coverage + uses: romeovs/lcov-reporter-action@v0.3.1 + with: + filter-changed-files: true + github-token: ${{ secrets.GITHUB_TOKEN }} + lcov-file: ./coverage.lcov diff --git a/.github/workflows/coverage-lint.yml b/.github/workflows/coverage-lint.yml index 0802169..72ef8ea 100644 --- a/.github/workflows/coverage-lint.yml +++ b/.github/workflows/coverage-lint.yml @@ -3,8 +3,6 @@ name: coverage-lint on: push: branches: [master] - pull_request: - branches: ['*'] jobs: tests: diff --git a/.gitignore b/.gitignore index 8b6903b..2f65873 100644 --- a/.gitignore +++ b/.gitignore @@ -30,6 +30,7 @@ pip-log.txt # Unit test / coverage reports .coverage coverage.xml +coverage.lcov .tox nosetests.xml .noseids From 24074aeb1518f5e57b679644403c9736b602c2ad Mon Sep 17 00:00:00 2001 From: Jongbin Jung Date: Sat, 5 Oct 2024 18:53:55 -0700 Subject: [PATCH 104/177] Allow string subtypes as H3str (#411) * Add test for string subtypes * Allow string subtypes as H3str --- src/h3/_cy/h3lib.pxd | 3 ++- src/h3/api/basic_int/__init__.py | 2 +- tests/test_apis/test_basic_str.py | 19 +++++++++++++++++++ 3 files changed, 22 insertions(+), 2 deletions(-) diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index a578a8f..e91cc2d 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -1,7 +1,8 @@ +# cython: c_string_type=unicode, c_string_encoding=utf8 from cpython cimport bool from libc.stdint cimport uint32_t, uint64_t, int64_t -ctypedef basestring H3str +ctypedef object H3str cdef extern from 'h3api.h': cdef int H3_VERSION_MAJOR diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index 992fce7..6035966 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -53,7 +53,7 @@ def str_to_int(h): int Unsigned 64-bit integer """ - return _cy.str_to_int(str(h)) + return _cy.str_to_int(h) def int_to_str(x): diff --git a/tests/test_apis/test_basic_str.py b/tests/test_apis/test_basic_str.py index 0c65a82..fccc164 100644 --- a/tests/test_apis/test_basic_str.py +++ b/tests/test_apis/test_basic_str.py @@ -22,3 +22,22 @@ def test5(): out = h3.grid_disk('8928308280fffff', 1) assert u.same_set(out, expected) + + +def test_string_subtypes(): + + class my_str(str): + pass + + expected = [ + '89283082873ffff', + '89283082877ffff', + '8928308283bffff', + '89283082807ffff', + '8928308280bffff', + '8928308280fffff', + '89283082803ffff' + ] + + out = h3.grid_disk(my_str('8928308280fffff'), 1) + assert u.same_set(out, expected) From 6d9a5fccd6b7b450179fa10b1db90ccc91ec21ed Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 5 Oct 2024 22:07:36 -0700 Subject: [PATCH 105/177] Prep for v4.1.0b3 release (#414) --- CHANGELOG.md | 4 ++++ pyproject.toml | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ee38256..69997d1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ avoid adding features or APIs which do not map onto the None. +## [4.1.0b3] - 2024-10-05 + +- Allow for `str` subtypes, like `numpy.str_` (#408) + ## [4.1.0b2] - 2024-09-27 - Add `cell_to_child_pos`, `child_pos_to_cell`, `cell_to_children_size` (#405) diff --git a/pyproject.toml b/pyproject.toml index e448802..9e24b7d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.1.0b2' +version = '4.1.0b3' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} From a8f9a085fd037ad6fee1b237bbb9efdb937e0d45 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 13 Oct 2024 17:06:08 -0700 Subject: [PATCH 106/177] prep for final v4.1.0 release (#407) --- CHANGELOG.md | 4 ++++ pyproject.toml | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 69997d1..1fef407 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ avoid adding features or APIs which do not map onto the None. +## [4.1.0] - TBD + +- Final v4.1 release inculdes all v4.x changes below. + ## [4.1.0b3] - 2024-10-05 - Allow for `str` subtypes, like `numpy.str_` (#408) diff --git a/pyproject.toml b/pyproject.toml index 9e24b7d..05fd5ec 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.1.0b3' +version = '4.1.0' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} From a4515def0d911c72bd5b8458601be81adaa22519 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 13 Oct 2024 17:33:40 -0700 Subject: [PATCH 107/177] post release notes (#418) --- CHANGELOG.md | 2 +- readme.md | 6 ++---- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1fef407..4211153 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,7 +18,7 @@ avoid adding features or APIs which do not map onto the None. -## [4.1.0] - TBD +## [4.1.0] - 2024-10-13 - Final v4.1 release inculdes all v4.x changes below. diff --git a/readme.md b/readme.md index fafc529..929e881 100644 --- a/readme.md +++ b/readme.md @@ -15,10 +15,8 @@ ---- -## ANNOUNCEMENT: v4.0.0 beta released! -Install the latest beta version with `pip install h3 --pre` -or with -`pip install 'h3==4.0.0b3'`.
+## ANNOUNCEMENT: v4.1.0 final released on 2024-10-13! + Feedback is welcome via [Issues](https://github.com/uber/h3-py/issues/new), [Discussions](https://github.com/uber/h3/discussions), From 3c1d235ac7cf9ec7ebdde1edc427a1f3b20c92ea Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 13 Oct 2024 17:53:39 -0700 Subject: [PATCH 108/177] Make sure docs and PyPI page are up-to-date. (#419) --- CHANGELOG.md | 4 ++++ pyproject.toml | 2 +- readme.md | 4 ++-- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4211153..449d14c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ avoid adding features or APIs which do not map onto the None. +## [4.1.1] - 2024-10-13 + +- Make sure docs and PyPI page are up-to-date. + ## [4.1.0] - 2024-10-13 - Final v4.1 release inculdes all v4.x changes below. diff --git a/pyproject.toml b/pyproject.toml index 05fd5ec..a07440f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.1.0' +version = '4.1.1' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} diff --git a/readme.md b/readme.md index 929e881..8680a8c 100644 --- a/readme.md +++ b/readme.md @@ -15,7 +15,7 @@ ---- -## ANNOUNCEMENT: v4.1.0 final released on 2024-10-13! +## ANNOUNCEMENT: v4.1 final released on 2024-10-13! Feedback is welcome via [Issues](https://github.com/uber/h3-py/issues/new), @@ -105,5 +105,5 @@ Use `h3.versions()` to see the version numbers for both ```python >>> import h3 >>> h3.versions() -{'c': '3.6.3', 'python': '3.6.1'} +{'c': '4.1.0', 'python': '4.1.1'} ``` From 4ccb2a25506862264a632c84f747ad6312492c2c Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Mon, 14 Oct 2024 12:10:57 -0700 Subject: [PATCH 109/177] Update readme.md to show bound H3 version (#421) --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 8680a8c..cb36c71 100644 --- a/readme.md +++ b/readme.md @@ -7,7 +7,7 @@ [![PyPI version](https://badge.fury.io/py/h3.svg)](https://badge.fury.io/py/h3) [![PyPI downloads](https://img.shields.io/pypi/dm/h3.svg)](https://pypistats.org/packages/h3) [![conda](https://img.shields.io/conda/vn/conda-forge/h3-py.svg)](https://anaconda.org/conda-forge/h3-py) -[![version](https://img.shields.io/badge/h3-v3.7.1-blue.svg)](https://github.com/uber/h3/releases/tag/v3.7.1) +[![version](https://img.shields.io/badge/h3-v4.1.0-blue.svg)](https://github.com/uber/h3/releases/tag/v4.1.0) [![version](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/uber/h3-py/blob/master/LICENSE) [![Tests](https://github.com/uber/h3-py/workflows/tests/badge.svg)](https://github.com/uber/h3-py/actions) From d061d810c6c64cf5b2e9b1851619ac1f0734c55b Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 26 Oct 2024 20:16:13 -0700 Subject: [PATCH 110/177] Build 3.13 wheels (#425) * Build 3.13 wheels * bump to pypa/cibuildwheel@v2.21.3 * a few more 3.13s * uses: actions/setup-python@v5.3.0 * actions/checkout@v4.2.2 * docker/setup-qemu-action@v3.2.0 * actions/upload-artifact@v4.4.3 * actions/download-artifact@v4.1.8 * pypa/gh-action-pypi-publish@v1.10.3 * Steal from #416 * note PR --- .github/workflows/build_docs.yml | 6 +++--- .github/workflows/coverage-lint-pr.yml | 4 ++-- .github/workflows/coverage-lint.yml | 4 ++-- .github/workflows/tests.yml | 6 +++--- .github/workflows/wheels.yml | 26 ++++++++++++++++---------- CHANGELOG.md | 4 ++++ pyproject.toml | 9 +++------ 7 files changed, 33 insertions(+), 26 deletions(-) diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index 328dc44..f6c950c 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -11,11 +11,11 @@ jobs: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v4.1.1 + - uses: actions/checkout@v4.2.2 with: submodules: recursive - - uses: actions/setup-python@v5.0.0 + - uses: actions/setup-python@v5.3.0 with: python-version: 3.11 @@ -28,7 +28,7 @@ jobs: run: jupyter-book build docs/ --warningiserror --keep-going --all - name: Upload artifacts - uses: actions/upload-artifact@v4.3.1 + uses: actions/upload-artifact@v4.4.3 with: name: html path: docs/_build/html diff --git a/.github/workflows/coverage-lint-pr.yml b/.github/workflows/coverage-lint-pr.yml index eb689e3..653f466 100644 --- a/.github/workflows/coverage-lint-pr.yml +++ b/.github/workflows/coverage-lint-pr.yml @@ -10,11 +10,11 @@ jobs: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v4.1.1 + - uses: actions/checkout@v4.2.2 with: submodules: recursive - - uses: actions/setup-python@v5.0.0 + - uses: actions/setup-python@v5.3.0 with: python-version: 3.11 diff --git a/.github/workflows/coverage-lint.yml b/.github/workflows/coverage-lint.yml index 72ef8ea..281b3bb 100644 --- a/.github/workflows/coverage-lint.yml +++ b/.github/workflows/coverage-lint.yml @@ -10,11 +10,11 @@ jobs: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v4.1.1 + - uses: actions/checkout@v4.2.2 with: submodules: recursive - - uses: actions/setup-python@v5.0.0 + - uses: actions/setup-python@v5.3.0 with: python-version: 3.11 diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 8075b01..cd4153d 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -14,14 +14,14 @@ jobs: strategy: matrix: os: [macos-latest, windows-latest, ubuntu-22.04] - python-version: ['3.8', '3.9', '3.10', '3.11', '3.12'] + python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13'] steps: - - uses: actions/checkout@v4.1.1 + - uses: actions/checkout@v4.2.2 with: submodules: recursive - - uses: actions/setup-python@v5.0.0 + - uses: actions/setup-python@v5.3.0 with: python-version: '${{ matrix.python-version }}' diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 659a193..c70b891 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -23,12 +23,12 @@ jobs: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v4.1.1 + - uses: actions/checkout@v4.2.2 with: submodules: recursive - name: Setup Python - uses: actions/setup-python@v5.0.0 + uses: actions/setup-python@v5.3.0 with: python-version: 3.11 @@ -48,7 +48,7 @@ jobs: run: pytest - name: Upload artifacts to GitHub - uses: actions/upload-artifact@v4.3.1 + uses: actions/upload-artifact@v4.4.3 with: name: temp_result_sdist path: ./dist @@ -90,6 +90,9 @@ jobs: - os: ubuntu-22.04 build: 'cp312-musllinux_x86_64' name: Linux Intel musl 64-bit 3.12 + - os: ubuntu-22.04 + build: 'cp313-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.13 - os: ubuntu-22.04 build: 'cp38-manylinux_aarch64' @@ -106,9 +109,12 @@ jobs: - os: ubuntu-22.04 build: 'cp312-manylinux_aarch64' name: Linux Aarch64 3.12 + - os: ubuntu-22.04 + build: 'cp313-manylinux_aarch64' + name: Linux Aarch64 3.13 steps: - - uses: actions/checkout@v4.1.1 + - uses: actions/checkout@v4.2.2 with: submodules: recursive @@ -124,11 +130,11 @@ jobs: - name: Set up QEMU if: runner.os == 'Linux' - uses: docker/setup-qemu-action@v3.0.0 + uses: docker/setup-qemu-action@v3.2.0 with: platforms: aarch64 - - uses: pypa/cibuildwheel@v2.17.0 + - uses: pypa/cibuildwheel@v2.21.3 env: CIBW_TEST_REQUIRES: pytest pytest-cov numpy CIBW_TEST_COMMAND: pytest {project}/tests @@ -140,7 +146,7 @@ jobs: pipx run twine check wheelhouse/* - name: Upload artifacts to GitHub - uses: actions/upload-artifact@v4.3.1 + uses: actions/upload-artifact@v4.4.3 with: name: temp_result_${{ matrix.os }}-${{ strategy.job-index }} path: wheelhouse/*.whl @@ -150,7 +156,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Merge Artifacts - uses: actions/upload-artifact/merge@v4 + uses: actions/upload-artifact/merge@v4.4.3 with: name: wheels_and_sdist pattern: temp_result_* @@ -164,11 +170,11 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/download-artifact@v4.1.7 + - uses: actions/download-artifact@v4.1.8 with: name: wheels_and_sdist path: dist - - uses: pypa/gh-action-pypi-publish@v1.8.14 + - uses: pypa/gh-action-pypi-publish@v1.10.3 with: password: ${{ secrets.pypi_password }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 449d14c..8ec7396 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ avoid adding features or APIs which do not map onto the None. +## [4.1.2] - 2024-10-26 + +- Build Python 3.13 wheels (#425) + ## [4.1.1] - 2024-10-13 - Make sure docs and PyPI page are up-to-date. diff --git a/pyproject.toml b/pyproject.toml index a07440f..4f5f94e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.1.1' +version = '4.1.2' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} @@ -30,6 +30,7 @@ classifiers = [ 'Programming Language :: Python :: 3.10', 'Programming Language :: Python :: 3.11', 'Programming Language :: Python :: 3.12', + 'Programming Language :: Python :: 3.13', 'Operating System :: MacOS :: MacOS X', 'Operating System :: POSIX :: Linux', 'Operating System :: Microsoft :: Windows', @@ -48,8 +49,8 @@ Changelog = 'https://package.readthedocs.io/en/latest/changelog.html' numpy = ['numpy'] test = ['pytest', 'pytest-cov', 'flake8', 'pylint', 'numpy'] all = [ + 'h3[test]', 'jupyter-book', - 'flake8', 'sphinx>=7.3.3', # https://github.com/sphinx-doc/sphinx/issues/12290 'jupyterlab', 'jupyterlab-geojson', @@ -59,10 +60,6 @@ all = [ 'contextily', 'cartopy', 'geoviews', - 'numpy', - 'pytest', - 'pytest-cov', - 'pylint', ] [tool.pytest.ini_options] From e9506ffa6d9fdbfc5329ab1e0099079a7613c01c Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Mon, 28 Oct 2024 13:31:38 -0700 Subject: [PATCH 111/177] 2nd attempt at ruff (#428) * starting * ruff config * fix notebook * more rules * F rules * sort rules * Q rules * remove F401 * sort * don't ignore F841 * being ridiculous * some todo rules * try gh action * a few more ideas to try * gitignore * clean up toml --- .flake8 | 20 ------------ .github/workflows/coverage-lint-pr.yml | 9 ++---- .github/workflows/coverage-lint.yml | 9 ++---- .gitignore | 1 + docs/polygon_tutorial.ipynb | 25 +++++++------- makefile | 6 ++-- pyproject.toml | 45 +++++++++++++++++++++++++- 7 files changed, 64 insertions(+), 51 deletions(-) delete mode 100644 .flake8 diff --git a/.flake8 b/.flake8 deleted file mode 100644 index f77f556..0000000 --- a/.flake8 +++ /dev/null @@ -1,20 +0,0 @@ -# https://lintlyci.github.io/Flake8Rules/ -[flake8] -max-line-length = 88 -include = - #W292 No newline at end of file - W292, -ignore = - # E251 unexpected spaces around keyword / parameter equals - E251, - # sometimes I just want to line up decimal points... - # E201 whitespace after '[' - E201, - # E241 multiple spaces after ',' - E241, - # E731 do not assign a lambda expression, use a def - E731, - # https://stackoverflow.com/questions/67942075/w504-line-break-after-binary-operator - W503,W504, - # E272 multiple spaces before keyword - E272 diff --git a/.github/workflows/coverage-lint-pr.yml b/.github/workflows/coverage-lint-pr.yml index 653f466..5db848c 100644 --- a/.github/workflows/coverage-lint-pr.yml +++ b/.github/workflows/coverage-lint-pr.yml @@ -23,13 +23,8 @@ jobs: pip install --upgrade pip setuptools wheel pip install .[test] - - name: Lint - run: flake8 src/h3 tests - - - name: Pylint - # As a test for visibility of API bindings, we want to ensure that pylint has no - # `import-error` warnings for h3 imports. - run: pylint --disable=all --enable=import-error tests/ + - name: Run Linting + uses: astral-sh/ruff-action@v1.1.1 - name: Coverage run: | diff --git a/.github/workflows/coverage-lint.yml b/.github/workflows/coverage-lint.yml index 281b3bb..ab0d52b 100644 --- a/.github/workflows/coverage-lint.yml +++ b/.github/workflows/coverage-lint.yml @@ -23,13 +23,8 @@ jobs: pip install --upgrade pip setuptools wheel pip install .[test] - - name: Lint - run: flake8 src/h3 tests - - - name: Pylint - # As a test for visibility of API bindings, we want to ensure that pylint has no - # `import-error` warnings for h3 imports. - run: pylint --disable=all --enable=import-error tests/ + - name: Run Linting + uses: astral-sh/ruff-action@v1.1.1 - name: Coverage run: | diff --git a/.gitignore b/.gitignore index 2f65873..ad8e4f3 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ h3c/ *.py[cod] .cache/ h3/out/ +.ruff_cache/ # Generated C code from Cython test tests/**/*.c diff --git a/docs/polygon_tutorial.ipynb b/docs/polygon_tutorial.ipynb index 7e0a1e9..e8df06a 100644 --- a/docs/polygon_tutorial.ipynb +++ b/docs/polygon_tutorial.ipynb @@ -41,32 +41,36 @@ "import contextily as cx\n", "import matplotlib.pyplot as plt\n", "\n", + "\n", "def plot_df(df, column=None, ax=None):\n", - " 'Plot based on the `geometry` column of a GeoPandas dataframe'\n", + " \"Plot based on the `geometry` column of a GeoPandas dataframe\"\n", " df = df.copy()\n", - " df = df.to_crs(epsg=3857) # web mercator\n", + " df = df.to_crs(epsg=3857) # web mercator\n", "\n", " if ax is None:\n", - " fig, ax = plt.subplots(figsize=(8,8))\n", + " _, ax = plt.subplots(figsize=(8,8))\n", " ax.get_xaxis().set_visible(False)\n", " ax.get_yaxis().set_visible(False)\n", - " \n", + "\n", " df.plot(\n", " ax=ax,\n", " alpha=0.5, edgecolor='k',\n", " column=column, categorical=True,\n", - " legend=True, legend_kwds={'loc': 'upper left'}, \n", + " legend=True, legend_kwds={'loc': 'upper left'},\n", " )\n", " cx.add_basemap(ax, crs=df.crs, source=cx.providers.CartoDB.Positron)\n", "\n", + "\n", "def plot_shape(shape, ax=None):\n", " df = geopandas.GeoDataFrame({'geometry': [shape]}, crs='EPSG:4326')\n", " plot_df(df, ax=ax)\n", "\n", + "\n", "def plot_cells(cells, ax=None):\n", " shape = h3.cells_to_h3shape(cells)\n", " plot_shape(shape, ax=ax)\n", "\n", + "\n", "def plot_shape_and_cells(shape, res=9):\n", " fig, axs = plt.subplots(1,2, figsize=(10,5), sharex=True, sharey=True)\n", " plot_shape(shape, ax=axs[0])\n", @@ -263,6 +267,7 @@ " def __geo_interface__(self):\n", " return self.d\n", "\n", + "\n", "geo = MockGeo(d)\n", "h3.geo_to_h3shape(geo)" ] @@ -902,14 +907,6 @@ "source": [ "plot_df(df, column='BoroName')" ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "cd012d79-a653-4d5d-bb30-408031301015", - "metadata": {}, - "outputs": [], - "source": [] } ], "metadata": { @@ -928,7 +925,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.2" + "version": "3.11.8" } }, "nbformat": 4, diff --git a/makefile b/makefile index a838caa..6c06e63 100644 --- a/makefile +++ b/makefile @@ -40,8 +40,10 @@ test: ./env/bin/pytest lint: - ./env/bin/flake8 src/h3 tests - ./env/bin/pylint --disable=all --enable=import-error tests/ + ./env/bin/ruff check + +fix: + ./env/bin/ruff check --fix lab: ./env/bin/pip install .[all] diff --git a/pyproject.toml b/pyproject.toml index 4f5f94e..50b5dc6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -47,7 +47,7 @@ Changelog = 'https://package.readthedocs.io/en/latest/changelog.html' [project.optional-dependencies] numpy = ['numpy'] -test = ['pytest', 'pytest-cov', 'flake8', 'pylint', 'numpy'] +test = ['pytest', 'pytest-cov', 'ruff', 'numpy'] all = [ 'h3[test]', 'jupyter-book', @@ -88,3 +88,46 @@ sdist.include = [ 'src/h3lib/cmake/*', 'src/h3lib/src/h3lib/*' ] + + +[tool.ruff] +src = [ + 'src', + 'tests', +] +line-length = 88 + +[tool.ruff.lint] +flake8-quotes.inline-quotes = 'single' + +# https://docs.astral.sh/ruff/rules/ +preview = true # https://docs.astral.sh/ruff/preview/#selecting-single-preview-rules +select = [ + 'A', + # 'B', # todo + # 'COM', # todo + 'E', + 'F', + 'Q', + 'W', + # 'D', # todo. this is nice! + # 'PL', # todo. some interesting ideas + # 'DOC', # todo: interesting +] +ignore = [ + 'E221', # Multiple spaces before operator + 'E231', # Missing whitespace after ',' + 'E241', # Multiple spaces after ',' + 'E251', # Unexpected spaces around keyword / parameter equals + 'E272', # Multiple spaces before keyword + 'E731', # Do not assign a `lambda` expression, use a `def` + # 'PLR2004', +] + +[tool.ruff.lint.per-file-ignores] +'*.ipynb' = [ + 'E501', # Line too long (104 > 88) +] +'test*.py' = [ + # 'D', # maybe just the need for docstring +] From ef6e8977316ae14eedb6fb17e8c9193dcc9d13c2 Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Sat, 28 Dec 2024 19:14:29 -0800 Subject: [PATCH 112/177] upgrade to h3 v4.2.0 (#432) * upgrade to h3 v4.2.0 * fix lint * pr number * split out experimental function to new function * docs --- CHANGELOG.md | 2 +- pyproject.toml | 2 +- src/h3/_cy/__init__.py | 2 + src/h3/_cy/h3lib.pxd | 3 ++ src/h3/_cy/latlng.pyx | 74 ++++++++++++++++++++++++++++ src/h3/_h3shape.py | 11 +++++ src/h3/api/basic_int/__init__.py | 82 +++++++++++++++++++++++++++++++- src/h3lib | 2 +- tests/polyfill/test_h3.py | 62 ++++++++++++++++++++++++ tests/test_cells_and_edges.py | 10 ++-- 10 files changed, 240 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8ec7396..4c60e19 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,7 @@ avoid adding features or APIs which do not map onto the ## Unreleased -None. +- Update to v4.2.0. (#432) ## [4.1.2] - 2024-10-26 diff --git a/pyproject.toml b/pyproject.toml index 50b5dc6..93cb37d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.1.2' +version = '4.2.0' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index 804b6b0..627f3b9 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -58,6 +58,8 @@ from .latlng import ( cell_to_latlng, polygon_to_cells, polygons_to_cells, + polygon_to_cells_experimental, + polygons_to_cells_experimental, cell_to_boundary, directed_edge_to_boundary, great_circle_distance, diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index e91cc2d..4a483b2 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -168,6 +168,9 @@ cdef extern from 'h3api.h': H3Error maxPolygonToCellsSize(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t *count) H3Error polygonToCells(const GeoPolygon *geoPolygon, int res, uint32_t flags, H3int *out) + H3Error maxPolygonToCellsSizeExperimental(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t *count) + H3Error polygonToCellsExperimental(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t sz, H3int *out) + # ctypedef struct GeoMultiPolygon: # int numPolygons # GeoPolygon *polygons diff --git a/src/h3/_cy/latlng.pyx b/src/h3/_cy/latlng.pyx index 493b85a..60b9053 100644 --- a/src/h3/_cy/latlng.pyx +++ b/src/h3/_cy/latlng.pyx @@ -196,6 +196,80 @@ def polygons_to_cells(polygons, int res): return hmm.to_mv() +def polygon_to_cells_experimental(outer, int res, int flags, holes=None): + """ Get the set of cells whose center is contained in a polygon. + + The polygon is defined similarity to the GeoJson standard, with an exterior + `outer` ring of lat/lng points, and a list of `holes`, each of which are also + rings of lat/lng points. + + Each ring may be in clockwise or counter-clockwise order + (right-hand rule or not), and may or may not be a closed loop (where the last + element is equal to the first). + The GeoJSON spec requires the right-hand rule and a closed loop, but + this function relaxes those constraints. + + Unlike the GeoJson standard, the elements of the lat/lng pairs of each + ring are in lat/lng order, instead of lng/lat order. + + We'll handle translation to different formats in the Python code, + rather than the Cython code. + + Parameters + ---------- + outer : list or tuple + A ring given by a sequence of lat/lng pairs. + res : int + The resolution of the output hexagons + flags : int + Polygon to cells flags, such as containment mode. + holes : list or tuple + A collection of rings, each given by a sequence of lat/lng pairs. + These describe any the "holes" in the polygon. + """ + cdef: + uint64_t n + + check_res(res) + + if not outer: + return H3MemoryManager(0).to_mv() + + gp = GeoPolygon(outer, holes=holes) + + check_for_error( + h3lib.maxPolygonToCellsSizeExperimental(&gp.gp, res, flags, &n) + ) + + hmm = H3MemoryManager(n) + check_for_error( + h3lib.polygonToCellsExperimental(&gp.gp, res, flags, n, hmm.ptr) + ) + mv = hmm.to_mv() + + return mv + + +def polygons_to_cells_experimental(polygons, int res, int flags): + mvs = [ + polygon_to_cells_experimental(outer=poly.outer, res=res, holes=poly.holes, flags=flags) + for poly in polygons + ] + + n = sum(map(len, mvs)) + hmm = H3MemoryManager(n) + + # probably super inefficient, but it is working! + # tood: move this to C + k = 0 + for mv in mvs: + for v in mv: + hmm.ptr[k] = v + k += 1 + + return hmm.to_mv() + + def cell_to_boundary(H3int h): """Compose an array of geo-coordinates that outlines a hexagonal cell""" cdef: diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py index 5c36295..261dfa9 100644 --- a/src/h3/_h3shape.py +++ b/src/h3/_h3shape.py @@ -1,4 +1,15 @@ from abc import ABCMeta, abstractmethod +from enum import Enum + + +class ContainmentMode(int, Enum): + """ + Containment modes for use with ``polygon_to_cells_experimental``. + """ + containment_center = 0 + containment_full = 1 + containment_overlapping = 2 + containment_overlapping_bbox = 3 class H3Shape(metaclass=ABCMeta): diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index 6035966..cf450c8 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -2,6 +2,7 @@ from ... import _cy from ..._h3shape import ( + ContainmentMode, H3Shape, LatLngPoly, LatLngMultiPoly, @@ -506,10 +507,10 @@ def h3shape_to_cells(h3shape, res): # todo: not sure if i want this dispatch logic here. maybe in the objects? if isinstance(h3shape, LatLngPoly): poly = h3shape - mv = _cy.polygon_to_cells(poly.outer, res, holes=poly.holes) + mv = _cy.polygon_to_cells(poly.outer, res=res, holes=poly.holes) elif isinstance(h3shape, LatLngMultiPoly): mpoly = h3shape - mv = _cy.polygons_to_cells(mpoly.polys, res) + mv = _cy.polygons_to_cells(mpoly.polys, res=res) elif isinstance(h3shape, H3Shape): raise ValueError('Unrecognized H3Shape: ' + str(h3shape)) else: @@ -525,6 +526,83 @@ def polygon_to_cells(h3shape, res): return h3shape_to_cells(h3shape, res) +def h3shape_to_cells_experimental(h3shape, res, flags=0): + """ + Return the collection of H3 cells at a given resolution whose center points + are contained within an ``LatLngPoly`` or ``LatLngMultiPoly``. + + Parameters + ---------- + h3shape : ``H3Shape`` + res : int + Resolution of the output cells + flags : ``ContainmentMode``, int, or string + Containment mode flags + + Returns + ------- + list of H3Cell + + Examples + -------- + + >>> poly = LatLngPoly( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), + ... (37.82, -122.54)], + ... ) + >>> h3.h3shape_to_cells_experimental(poly, 6, h3.ContainmentMode.containment_center) + ['862830807ffffff', + '862830827ffffff', + '86283082fffffff', + '862830877ffffff', + '862830947ffffff', + '862830957ffffff', + '86283095fffffff'] + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + + if isinstance(flags, str): + try: + flags = ContainmentMode[flags] + except KeyError as e: + raise ValueError('Unrecognized flags: ' + flags) from e + if isinstance(flags, ContainmentMode): + flags = int(flags) + if not isinstance(flags, int): + raise ValueError( + 'Flags should be ContainmentMode, str, or int, but got: ' + str(type(flags)) + ) + + # todo: not sure if i want this dispatch logic here. maybe in the objects? + if isinstance(h3shape, LatLngPoly): + poly = h3shape + mv = _cy.polygon_to_cells_experimental( + poly.outer, + res=res, + holes=poly.holes, + flags=flags + ) + elif isinstance(h3shape, LatLngMultiPoly): + mpoly = h3shape + mv = _cy.polygons_to_cells_experimental(mpoly.polys, res=res, flags=flags) + elif isinstance(h3shape, H3Shape): + raise ValueError('Unrecognized H3Shape: ' + str(h3shape)) + else: + raise ValueError('Unrecognized type: ' + str(type(h3shape))) + + return _out_collection(mv) + + +def polygon_to_cells_experimental(h3shape, res, flags=0): + """ + Alias for ``h3shape_to_cells_experimental``. + """ + return h3shape_to_cells_experimental(h3shape, res, flags=flags) + + def cells_to_h3shape(cells, *, tight=True): """ Return an ``H3Shape`` describing the area covered by a collection of H3 cells. diff --git a/src/h3lib b/src/h3lib index 5c91149..2d8a62d 160000 --- a/src/h3lib +++ b/src/h3lib @@ -1 +1 @@ -Subproject commit 5c91149104ac02c4f06faa4fc557e69cf6b131ef +Subproject commit 2d8a62d5fe456bba2af7ca0be7efe9754f1dd25b diff --git a/tests/polyfill/test_h3.py b/tests/polyfill/test_h3.py index 8d9d948..50728d3 100644 --- a/tests/polyfill/test_h3.py +++ b/tests/polyfill/test_h3.py @@ -117,6 +117,68 @@ def test_polygon_to_cells(): assert '89283095edbffff' in out +def test_polygon_to_cells_experimental(): + poly = h3.LatLngPoly(sf_7x7) + for flags in [0, 'containment_center', h3.ContainmentMode.containment_center]: + # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` + out = h3.polygon_to_cells_experimental(poly, res=9, flags=flags) + + assert len(out) == 1253 + assert '89283080527ffff' in out + assert '89283095edbffff' in out + + +def test_polygon_to_cells_experimental_full(): + poly = h3.LatLngPoly(sf_7x7) + for flags in [1, 'containment_full', h3.ContainmentMode.containment_full]: + # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` + out = h3.polygon_to_cells_experimental(poly, res=9, flags=flags) + + assert len(out) == 1175 + assert '89283082a1bffff' in out + assert '89283080527ffff' not in out + assert '89283095edbffff' in out + + +def test_polygon_to_cells_experimental_overlapping(): + poly = h3.LatLngPoly(sf_7x7) + for flags in [ + 2, + 'containment_overlapping', + h3.ContainmentMode.containment_overlapping + ]: + # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` + out = h3.polygon_to_cells_experimental(poly, res=9, flags=flags) + + assert len(out) == 1334 + assert '89283080527ffff' in out + assert '89283095edbffff' in out + + +def test_polygon_to_cells_experimental_overlapping_bbox(): + poly = h3.LatLngPoly(sf_7x7) + for flags in [ + 3, + 'containment_overlapping_bbox', + h3.ContainmentMode.containment_overlapping_bbox + ]: + # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` + out = h3.polygon_to_cells_experimental(poly, res=9, flags=flags) + + assert len(out) == 1416 + assert '89283080527ffff' in out + assert '89283095edbffff' in out + + +def test_polygon_to_cells_experimental_invalid_mode(): + poly = h3.LatLngPoly(sf_7x7) + for flags in [1.0, 'containment_overlapping_bbox_abc', None]: + with pytest.raises(ValueError): + print(flags) + # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` + h3.polygon_to_cells_experimental(poly, res=9, flags=flags) + + def test_polyfill_with_hole(): poly = h3.LatLngPoly(sf_7x7, sf_hole1) diff --git a/tests/test_cells_and_edges.py b/tests/test_cells_and_edges.py index d23ff4d..f918019 100644 --- a/tests/test_cells_and_edges.py +++ b/tests/test_cells_and_edges.py @@ -289,11 +289,11 @@ def test_average_hexagon_area(): def test_average_hexagon_edge_length(): expected_in_km = { - 0: 1107.712591000, - 1: 418.676005500, - 2: 158.244655800, - 9: 0.174375668, - 15: 0.000509713, + 0: 1281.256011, + 1: 483.0568391, + 2: 182.5129565, + 9: 0.200786148, + 15: 0.000584169, } out = { From 3d5b12a37071a09248389cafe8f45032c9a9a549 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 29 Dec 2024 11:15:46 -0800 Subject: [PATCH 113/177] Simplify coverage and lint actions v2 (#435) * simplify coverage and lint actions * move around the testing for coverage * try 3.11 * clean up a bit * separate tests * run tests twice * no coverage target for cython tests * full tests for polygon_to_cells_experimental * i think that gets the actions how we want --- .github/workflows/coverage-lint-pr.yml | 40 ------------------- .github/workflows/coverage-lint.yml | 40 ------------------- .github/workflows/lint_and_coverage.yml | 37 +++++++++++++++++ makefile | 4 +- pyproject.toml | 2 +- tests/readme.md | 18 +++++++++ tests/{ => test_lib}/__init__.py | 0 tests/{ => test_lib}/polyfill/__init__.py | 0 tests/{ => test_lib}/polyfill/test_h3.py | 30 +++++++++++++- .../{ => test_lib}/polyfill/test_polyfill.py | 3 ++ .../polyfill/test_polyfill_ordering.py | 0 .../polyfill/test_polygon_class.py | 4 ++ .../polyfill/test_to_multipoly.py | 0 tests/{ => test_lib}/test_apis/__init__.py | 0 .../test_apis/test_api_bindings_match.py | 0 .../test_apis/test_basic_int.py | 0 .../test_apis/test_basic_str.py | 0 .../test_apis/test_collection_inputs.py | 0 .../test_apis/test_ico_faces.py | 0 .../test_apis/test_memview_int.py | 0 .../test_apis/test_numpy_int.py | 0 tests/{ => test_lib}/test_cells_and_edges.py | 0 tests/{ => test_lib}/test_error_codes.py | 0 tests/{ => test_lib}/test_h3.py | 0 tests/{ => test_lib}/test_length_area.py | 0 tests/{ => test_lib}/util.py | 0 26 files changed, 95 insertions(+), 83 deletions(-) delete mode 100644 .github/workflows/coverage-lint-pr.yml delete mode 100644 .github/workflows/coverage-lint.yml create mode 100644 .github/workflows/lint_and_coverage.yml create mode 100644 tests/readme.md rename tests/{ => test_lib}/__init__.py (100%) rename tests/{ => test_lib}/polyfill/__init__.py (100%) rename tests/{ => test_lib}/polyfill/test_h3.py (94%) rename tests/{ => test_lib}/polyfill/test_polyfill.py (97%) rename tests/{ => test_lib}/polyfill/test_polyfill_ordering.py (100%) rename tests/{ => test_lib}/polyfill/test_polygon_class.py (91%) rename tests/{ => test_lib}/polyfill/test_to_multipoly.py (100%) rename tests/{ => test_lib}/test_apis/__init__.py (100%) rename tests/{ => test_lib}/test_apis/test_api_bindings_match.py (100%) rename tests/{ => test_lib}/test_apis/test_basic_int.py (100%) rename tests/{ => test_lib}/test_apis/test_basic_str.py (100%) rename tests/{ => test_lib}/test_apis/test_collection_inputs.py (100%) rename tests/{ => test_lib}/test_apis/test_ico_faces.py (100%) rename tests/{ => test_lib}/test_apis/test_memview_int.py (100%) rename tests/{ => test_lib}/test_apis/test_numpy_int.py (100%) rename tests/{ => test_lib}/test_cells_and_edges.py (100%) rename tests/{ => test_lib}/test_error_codes.py (100%) rename tests/{ => test_lib}/test_h3.py (100%) rename tests/{ => test_lib}/test_length_area.py (100%) rename tests/{ => test_lib}/util.py (100%) diff --git a/.github/workflows/coverage-lint-pr.yml b/.github/workflows/coverage-lint-pr.yml deleted file mode 100644 index 5db848c..0000000 --- a/.github/workflows/coverage-lint-pr.yml +++ /dev/null @@ -1,40 +0,0 @@ -name: pr-coverage-lint - -on: - pull_request: - branches: ['*'] - -jobs: - tests: - name: Coverage and Lint - runs-on: ubuntu-22.04 - - steps: - - uses: actions/checkout@v4.2.2 - with: - submodules: recursive - - - uses: actions/setup-python@v5.3.0 - with: - python-version: 3.11 - - - name: Install from source - run: | - pip install --upgrade pip setuptools wheel - pip install .[test] - - - name: Run Linting - uses: astral-sh/ruff-action@v1.1.1 - - - name: Coverage - run: | - pip install cython - cythonize tests/test_cython/cython_example.pyx - pytest --cov-report=lcov - - - name: Report coverage - uses: romeovs/lcov-reporter-action@v0.3.1 - with: - filter-changed-files: true - github-token: ${{ secrets.GITHUB_TOKEN }} - lcov-file: ./coverage.lcov diff --git a/.github/workflows/coverage-lint.yml b/.github/workflows/coverage-lint.yml deleted file mode 100644 index ab0d52b..0000000 --- a/.github/workflows/coverage-lint.yml +++ /dev/null @@ -1,40 +0,0 @@ -name: coverage-lint - -on: - push: - branches: [master] - -jobs: - tests: - name: Coverage and Lint - runs-on: ubuntu-22.04 - - steps: - - uses: actions/checkout@v4.2.2 - with: - submodules: recursive - - - uses: actions/setup-python@v5.3.0 - with: - python-version: 3.11 - - - name: Install from source - run: | - pip install --upgrade pip setuptools wheel - pip install .[test] - - - name: Run Linting - uses: astral-sh/ruff-action@v1.1.1 - - - name: Coverage - run: | - pip install cython - cythonize tests/test_cython/cython_example.pyx - pytest --cov-report=xml - - - name: Upload coverage to Codecov - uses: codecov/codecov-action@v4.3.0 - with: - file: ./coverage.xml - fail_ci_if_error: true - token: ${{ secrets.CODECOV_TOKEN }} diff --git a/.github/workflows/lint_and_coverage.yml b/.github/workflows/lint_and_coverage.yml new file mode 100644 index 0000000..ab23b27 --- /dev/null +++ b/.github/workflows/lint_and_coverage.yml @@ -0,0 +1,37 @@ +name: lint_and_coverage + +on: + push: + branches: [master] + pull_request: + branches: ['*'] + +jobs: + linting: + name: Lint and Coverage + runs-on: ubuntu-24.04 + + steps: + - uses: actions/checkout@v4 + with: + submodules: recursive + + - uses: actions/setup-python@v5 + with: + python-version: 3.11 + + - name: Install from source + run: pip install .[test] + + - name: Run Linting + uses: astral-sh/ruff-action@v3 + + - name: Coverage Requirement - Library + run: | + pytest --cov=tests/test_lib --cov-fail-under=100 + + - name: Coverage - Cython + run: | + pip install cython + cythonize tests/test_cython/cython_example.pyx + pytest --cov=tests/test_cython diff --git a/makefile b/makefile index 6c06e63..e6b0283 100644 --- a/makefile +++ b/makefile @@ -35,9 +35,11 @@ purge: clear -@rm -rf env test: + ./env/bin/pytest --cov=tests/test_lib --cov-fail-under=100 + ./env/bin/pip install cython ./env/bin/cythonize tests/test_cython/cython_example.pyx - ./env/bin/pytest + ./env/bin/pytest --cov=tests/test_cython lint: ./env/bin/ruff check diff --git a/pyproject.toml b/pyproject.toml index 93cb37d..e1cc0ba 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -63,7 +63,7 @@ all = [ ] [tool.pytest.ini_options] -addopts = "--cov=h3 --cov=tests --cov-report=term-missing --durations=10" +addopts = "--cov=h3 --cov-report=term-missing --durations=10" [tool.coverage.run] omit = [ diff --git a/tests/readme.md b/tests/readme.md new file mode 100644 index 0000000..0aba346 --- /dev/null +++ b/tests/readme.md @@ -0,0 +1,18 @@ +We separate the `h3-py` tests into two groups, organized by subfolder. + +We do this because we expect 100% coverage on the library tests, but are +still working through getting full coverage on the Cython tests. + + +## `test_lib` + +The tests in this folder are for the main `h3-py` Python API for folks +who are using the pure-Python library functionality. + +## `test_cython` + +The tests in this folder are for the advanced Cython API, that allows +for other *Cython* packages or scripts to use the Cython code provided +by the `h3-py` internals. + +Note that the "Cython API" of `h3-py` is not currently externally supported. diff --git a/tests/__init__.py b/tests/test_lib/__init__.py similarity index 100% rename from tests/__init__.py rename to tests/test_lib/__init__.py diff --git a/tests/polyfill/__init__.py b/tests/test_lib/polyfill/__init__.py similarity index 100% rename from tests/polyfill/__init__.py rename to tests/test_lib/polyfill/__init__.py diff --git a/tests/polyfill/test_h3.py b/tests/test_lib/polyfill/test_h3.py similarity index 94% rename from tests/polyfill/test_h3.py rename to tests/test_lib/polyfill/test_h3.py index 50728d3..933f404 100644 --- a/tests/polyfill/test_h3.py +++ b/tests/test_lib/polyfill/test_h3.py @@ -174,11 +174,39 @@ def test_polygon_to_cells_experimental_invalid_mode(): poly = h3.LatLngPoly(sf_7x7) for flags in [1.0, 'containment_overlapping_bbox_abc', None]: with pytest.raises(ValueError): - print(flags) # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` h3.polygon_to_cells_experimental(poly, res=9, flags=flags) +def test_poly_to_cells_experimental_mpoly(): + mpoly = h3.LatLngMultiPoly( + h3.LatLngPoly(sf_hole1), + h3.LatLngPoly(sf_hole2), + ) + + assert ( + set(h3.polygon_to_cells_experimental(mpoly, res=9)) + == + set(h3.polygon_to_cells_experimental(mpoly, res=9, flags='containment_center')) + ) + + assert ( + set(h3.polygon_to_cells_experimental(mpoly, res=9)) + < + set(h3.polygon_to_cells_experimental( + mpoly, + res=9, + flags='containment_overlapping' + )) + ) + + assert 120 == len(h3.polygon_to_cells_experimental( + mpoly, + res=9, + flags='containment_overlapping' + )) + + def test_polyfill_with_hole(): poly = h3.LatLngPoly(sf_7x7, sf_hole1) diff --git a/tests/polyfill/test_polyfill.py b/tests/test_lib/polyfill/test_polyfill.py similarity index 97% rename from tests/polyfill/test_polyfill.py rename to tests/test_lib/polyfill/test_polyfill.py index 1431b87..9bdd9af 100644 --- a/tests/polyfill/test_polyfill.py +++ b/tests/test_lib/polyfill/test_polyfill.py @@ -145,6 +145,9 @@ def test_bad_geo_input(): with pytest.raises(ValueError): h3.h3shape_to_cells('not a shape', 9) + with pytest.raises(ValueError): + h3.h3shape_to_cells_experimental('not a shape', res=9) + with pytest.raises(ValueError): h3.geo_to_cells({'type': 'not a shape', 'coordinates': None}, 9) diff --git a/tests/polyfill/test_polyfill_ordering.py b/tests/test_lib/polyfill/test_polyfill_ordering.py similarity index 100% rename from tests/polyfill/test_polyfill_ordering.py rename to tests/test_lib/polyfill/test_polyfill_ordering.py diff --git a/tests/polyfill/test_polygon_class.py b/tests/test_lib/polyfill/test_polygon_class.py similarity index 91% rename from tests/polyfill/test_polygon_class.py rename to tests/test_lib/polyfill/test_polygon_class.py index 3996d30..59e8da2 100644 --- a/tests/polyfill/test_polygon_class.py +++ b/tests/test_lib/polyfill/test_polygon_class.py @@ -44,5 +44,9 @@ def test_bad_subclass(): shoop = H3Shoop() shoop.__geo_interface__() + with pytest.raises(ValueError): h3.h3shape_to_cells(shoop, res=9) + + with pytest.raises(ValueError): + h3.h3shape_to_cells_experimental(shoop, res=9) diff --git a/tests/polyfill/test_to_multipoly.py b/tests/test_lib/polyfill/test_to_multipoly.py similarity index 100% rename from tests/polyfill/test_to_multipoly.py rename to tests/test_lib/polyfill/test_to_multipoly.py diff --git a/tests/test_apis/__init__.py b/tests/test_lib/test_apis/__init__.py similarity index 100% rename from tests/test_apis/__init__.py rename to tests/test_lib/test_apis/__init__.py diff --git a/tests/test_apis/test_api_bindings_match.py b/tests/test_lib/test_apis/test_api_bindings_match.py similarity index 100% rename from tests/test_apis/test_api_bindings_match.py rename to tests/test_lib/test_apis/test_api_bindings_match.py diff --git a/tests/test_apis/test_basic_int.py b/tests/test_lib/test_apis/test_basic_int.py similarity index 100% rename from tests/test_apis/test_basic_int.py rename to tests/test_lib/test_apis/test_basic_int.py diff --git a/tests/test_apis/test_basic_str.py b/tests/test_lib/test_apis/test_basic_str.py similarity index 100% rename from tests/test_apis/test_basic_str.py rename to tests/test_lib/test_apis/test_basic_str.py diff --git a/tests/test_apis/test_collection_inputs.py b/tests/test_lib/test_apis/test_collection_inputs.py similarity index 100% rename from tests/test_apis/test_collection_inputs.py rename to tests/test_lib/test_apis/test_collection_inputs.py diff --git a/tests/test_apis/test_ico_faces.py b/tests/test_lib/test_apis/test_ico_faces.py similarity index 100% rename from tests/test_apis/test_ico_faces.py rename to tests/test_lib/test_apis/test_ico_faces.py diff --git a/tests/test_apis/test_memview_int.py b/tests/test_lib/test_apis/test_memview_int.py similarity index 100% rename from tests/test_apis/test_memview_int.py rename to tests/test_lib/test_apis/test_memview_int.py diff --git a/tests/test_apis/test_numpy_int.py b/tests/test_lib/test_apis/test_numpy_int.py similarity index 100% rename from tests/test_apis/test_numpy_int.py rename to tests/test_lib/test_apis/test_numpy_int.py diff --git a/tests/test_cells_and_edges.py b/tests/test_lib/test_cells_and_edges.py similarity index 100% rename from tests/test_cells_and_edges.py rename to tests/test_lib/test_cells_and_edges.py diff --git a/tests/test_error_codes.py b/tests/test_lib/test_error_codes.py similarity index 100% rename from tests/test_error_codes.py rename to tests/test_lib/test_error_codes.py diff --git a/tests/test_h3.py b/tests/test_lib/test_h3.py similarity index 100% rename from tests/test_h3.py rename to tests/test_lib/test_h3.py diff --git a/tests/test_length_area.py b/tests/test_lib/test_length_area.py similarity index 100% rename from tests/test_length_area.py rename to tests/test_lib/test_length_area.py diff --git a/tests/util.py b/tests/test_lib/util.py similarity index 100% rename from tests/util.py rename to tests/test_lib/util.py From 1dc5e5174064981d112434a9348b3ee2b1ebbdb6 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Wed, 1 Jan 2025 16:07:44 -0800 Subject: [PATCH 114/177] drop v4 announcement from readme (#437) * drop v4 announcement from readme * drop a todo that never got todone * codecov todo --- readme.md | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/readme.md b/readme.md index cb36c71..4a8a4b5 100644 --- a/readme.md +++ b/readme.md @@ -2,8 +2,6 @@ # **h3-py**: Uber's H3 Hexagonal Hierarchical Geospatial Indexing System in Python - - [![PyPI version](https://badge.fury.io/py/h3.svg)](https://badge.fury.io/py/h3) [![PyPI downloads](https://img.shields.io/pypi/dm/h3.svg)](https://pypistats.org/packages/h3) [![conda](https://img.shields.io/conda/vn/conda-forge/h3-py.svg)](https://anaconda.org/conda-forge/h3-py) @@ -11,19 +9,7 @@ [![version](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/uber/h3-py/blob/master/LICENSE) [![Tests](https://github.com/uber/h3-py/workflows/tests/badge.svg)](https://github.com/uber/h3-py/actions) -[![codecov](https://codecov.io/gh/uber/h3-py/branch/master/graph/badge.svg)](https://codecov.io/gh/uber/h3-py) - - ----- -## ANNOUNCEMENT: v4.1 final released on 2024-10-13! - -Feedback is welcome via -[Issues](https://github.com/uber/h3-py/issues/new), -[Discussions](https://github.com/uber/h3/discussions), -and -[Slack](https://join.slack.com/t/h3-core/shared_invite/zt-g6u5r1hf-W_~uVJmfeiWtMQuBGc1NNg). - ----- +[![codecov](https://codecov.io/gh/uber/h3-py/branch/master/graph/badge.svg)](https://codecov.io/gh/uber/h3-py) Python bindings for the [H3 core library](https://h3geo.org/). From 1ac484a8db1dcab37de80c3b4e73422c6bf90fc8 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 26 Jan 2025 16:57:31 -0800 Subject: [PATCH 115/177] `h3shape_to_cells_experimental` takes string containment modes (#436) * polygon to cells just takes string arguments * don't need enum * docstrings * have tests use h3shape_to_cells_experimental * clean up tests * don't repeat tests * experimental warning * Being experimental, try `contain` instead of `containment` in params * try typing with literal * add polygon_to_cells_experimental. Contains coverage and lint errors -- just checking that they raise in CI * ruff fix * docs and changelog * add test_polygon_to_cells_experimental for full coverage * test notes --- .github/workflows/lint_and_coverage.yml | 4 +- CHANGELOG.md | 2 + docs/api_quick.md | 11 +++ makefile | 4 +- pyproject.toml | 2 +- src/h3/_cy/latlng.pyx | 14 ++-- src/h3/_h3shape.py | 11 --- src/h3/api/basic_int/__init__.py | 82 +++++++++++-------- tests/test_lib/polyfill/test_h3.py | 100 ++++++++++++------------ 9 files changed, 125 insertions(+), 105 deletions(-) diff --git a/.github/workflows/lint_and_coverage.yml b/.github/workflows/lint_and_coverage.yml index ab23b27..723677c 100644 --- a/.github/workflows/lint_and_coverage.yml +++ b/.github/workflows/lint_and_coverage.yml @@ -28,10 +28,10 @@ jobs: - name: Coverage Requirement - Library run: | - pytest --cov=tests/test_lib --cov-fail-under=100 + pytest tests/test_lib --cov=h3 --cov=tests/test_lib --cov-fail-under=100 - name: Coverage - Cython run: | pip install cython cythonize tests/test_cython/cython_example.pyx - pytest --cov=tests/test_cython + pytest tests/test_cython --cov=tests/test_cython diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c60e19..6833583 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,8 @@ avoid adding features or APIs which do not map onto the ## Unreleased - Update to v4.2.0. (#432) +- Add `h3shape_to_cells_experimental` (#436) + - Add `polygon_to_cells_experimental` alias ## [4.1.2] - 2024-10-26 diff --git a/docs/api_quick.md b/docs/api_quick.md index 5503bae..7b29638 100644 --- a/docs/api_quick.md +++ b/docs/api_quick.md @@ -161,6 +161,17 @@ Note that this is reversed from [``__geo_interface__``](https://gist.github.com/ cells_to_geo ``` +#### Additional functions + +```{eval-rst} +.. currentmodule:: h3 + +.. autosummary:: + polygon_to_cells + polygon_to_cells_experimental + h3shape_to_cells_experimental +``` + ## Specialized functions diff --git a/makefile b/makefile index e6b0283..df39c8f 100644 --- a/makefile +++ b/makefile @@ -35,11 +35,11 @@ purge: clear -@rm -rf env test: - ./env/bin/pytest --cov=tests/test_lib --cov-fail-under=100 + ./env/bin/pytest tests/test_lib --cov=h3 --cov=tests/test_lib --cov-fail-under=100 ./env/bin/pip install cython ./env/bin/cythonize tests/test_cython/cython_example.pyx - ./env/bin/pytest --cov=tests/test_cython + ./env/bin/pytest tests/test_cython --cov=tests/test_cython lint: ./env/bin/ruff check diff --git a/pyproject.toml b/pyproject.toml index e1cc0ba..06ce0e3 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -63,7 +63,7 @@ all = [ ] [tool.pytest.ini_options] -addopts = "--cov=h3 --cov-report=term-missing --durations=10" +addopts = "--cov-report=term-missing --durations=10" [tool.coverage.run] omit = [ diff --git a/src/h3/_cy/latlng.pyx b/src/h3/_cy/latlng.pyx index 60b9053..d83a9d3 100644 --- a/src/h3/_cy/latlng.pyx +++ b/src/h3/_cy/latlng.pyx @@ -196,7 +196,7 @@ def polygons_to_cells(polygons, int res): return hmm.to_mv() -def polygon_to_cells_experimental(outer, int res, int flags, holes=None): +def polygon_to_cells_experimental(outer, int res, int flag, holes=None): """ Get the set of cells whose center is contained in a polygon. The polygon is defined similarity to the GeoJson standard, with an exterior @@ -221,8 +221,8 @@ def polygon_to_cells_experimental(outer, int res, int flags, holes=None): A ring given by a sequence of lat/lng pairs. res : int The resolution of the output hexagons - flags : int - Polygon to cells flags, such as containment mode. + flag : int + Polygon to cells flag, such as containment mode. holes : list or tuple A collection of rings, each given by a sequence of lat/lng pairs. These describe any the "holes" in the polygon. @@ -238,21 +238,21 @@ def polygon_to_cells_experimental(outer, int res, int flags, holes=None): gp = GeoPolygon(outer, holes=holes) check_for_error( - h3lib.maxPolygonToCellsSizeExperimental(&gp.gp, res, flags, &n) + h3lib.maxPolygonToCellsSizeExperimental(&gp.gp, res, flag, &n) ) hmm = H3MemoryManager(n) check_for_error( - h3lib.polygonToCellsExperimental(&gp.gp, res, flags, n, hmm.ptr) + h3lib.polygonToCellsExperimental(&gp.gp, res, flag, n, hmm.ptr) ) mv = hmm.to_mv() return mv -def polygons_to_cells_experimental(polygons, int res, int flags): +def polygons_to_cells_experimental(polygons, int res, int flag): mvs = [ - polygon_to_cells_experimental(outer=poly.outer, res=res, holes=poly.holes, flags=flags) + polygon_to_cells_experimental(outer=poly.outer, res=res, holes=poly.holes, flag=flag) for poly in polygons ] diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py index 261dfa9..5c36295 100644 --- a/src/h3/_h3shape.py +++ b/src/h3/_h3shape.py @@ -1,15 +1,4 @@ from abc import ABCMeta, abstractmethod -from enum import Enum - - -class ContainmentMode(int, Enum): - """ - Containment modes for use with ``polygon_to_cells_experimental``. - """ - containment_center = 0 - containment_full = 1 - containment_overlapping = 2 - containment_overlapping_bbox = 3 class H3Shape(metaclass=ABCMeta): diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index cf450c8..09f7deb 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -1,8 +1,8 @@ # This file is **symlinked** across the APIs to ensure they are exactly the same. +from typing import Literal from ... import _cy from ..._h3shape import ( - ContainmentMode, H3Shape, LatLngPoly, LatLngMultiPoly, @@ -468,6 +468,13 @@ def uncompact_cells(cells, res): return _out_collection(hu) +def polygon_to_cells(h3shape, res): + """ + Alias for ``h3shape_to_cells``. + """ + return h3shape_to_cells(h3shape, res) + + def h3shape_to_cells(h3shape, res): """ Return the collection of H3 cells at a given resolution whose center points @@ -519,25 +526,46 @@ def h3shape_to_cells(h3shape, res): return _out_collection(mv) -def polygon_to_cells(h3shape, res): +def polygon_to_cells_experimental( + h3shape: H3Shape, + res: int, + contain: Literal['center', 'full', 'overlap', 'bbox_overlap'] = 'center', +): """ - Alias for ``h3shape_to_cells``. + Alias for ``h3shape_to_cells_experimental``. """ - return h3shape_to_cells(h3shape, res) + return h3shape_to_cells_experimental(h3shape, res, contain) -def h3shape_to_cells_experimental(h3shape, res, flags=0): +def h3shape_to_cells_experimental( + h3shape: H3Shape, + res: int, + contain: Literal['center', 'full', 'overlap', 'bbox_overlap'] = 'center', +): """ - Return the collection of H3 cells at a given resolution whose center points - are contained within an ``LatLngPoly`` or ``LatLngMultiPoly``. + Experimental function similar to ``h3shape_to_cells``, but with support for + multiple cell containment modes. + + Using ``contain='center'`` should give identical behavior as + ``h3shape_to_cells``. + + Note that this function is **experimental** and has no API stability gaurantees + across versions, so it may change in the future. + Parameters ---------- h3shape : ``H3Shape`` res : int Resolution of the output cells - flags : ``ContainmentMode``, int, or string - Containment mode flags + contain : {'center', 'full', 'overlap', 'bbox_overlap'}, optional + Specifies the containment condition. + - 'center': Cell center is contained in shape + - 'full': Cell is fully contained in shape + - 'overlap': Cell is partially contained in shape + - 'bbox_overlap': Cell bounding box is partially contained in shape + + Default is 'center'. Returns ------- @@ -550,7 +578,7 @@ def h3shape_to_cells_experimental(h3shape, res, flags=0): ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), ... (37.82, -122.54)], ... ) - >>> h3.h3shape_to_cells_experimental(poly, 6, h3.ContainmentMode.containment_center) + >>> h3.h3shape_to_cells_experimental(poly, 6, 'center') ['862830807ffffff', '862830827ffffff', '86283082fffffff', @@ -564,30 +592,27 @@ def h3shape_to_cells_experimental(h3shape, res, flags=0): There is currently no guaranteed order of the output cells. """ - if isinstance(flags, str): - try: - flags = ContainmentMode[flags] - except KeyError as e: - raise ValueError('Unrecognized flags: ' + flags) from e - if isinstance(flags, ContainmentMode): - flags = int(flags) - if not isinstance(flags, int): - raise ValueError( - 'Flags should be ContainmentMode, str, or int, but got: ' + str(type(flags)) - ) + contain_modes = { + 'center': 0, + 'full': 1, + 'overlap': 2, + 'bbox_overlap': 3, + } + + flag = contain_modes[contain] # todo: not sure if i want this dispatch logic here. maybe in the objects? if isinstance(h3shape, LatLngPoly): poly = h3shape mv = _cy.polygon_to_cells_experimental( poly.outer, - res=res, - holes=poly.holes, - flags=flags + res = res, + holes = poly.holes, + flag = flag, ) elif isinstance(h3shape, LatLngMultiPoly): mpoly = h3shape - mv = _cy.polygons_to_cells_experimental(mpoly.polys, res=res, flags=flags) + mv = _cy.polygons_to_cells_experimental(mpoly.polys, res=res, flag=flag) elif isinstance(h3shape, H3Shape): raise ValueError('Unrecognized H3Shape: ' + str(h3shape)) else: @@ -596,13 +621,6 @@ def h3shape_to_cells_experimental(h3shape, res, flags=0): return _out_collection(mv) -def polygon_to_cells_experimental(h3shape, res, flags=0): - """ - Alias for ``h3shape_to_cells_experimental``. - """ - return h3shape_to_cells_experimental(h3shape, res, flags=flags) - - def cells_to_h3shape(cells, *, tight=True): """ Return an ``H3Shape`` describing the area covered by a collection of H3 cells. diff --git a/tests/test_lib/polyfill/test_h3.py b/tests/test_lib/polyfill/test_h3.py index 933f404..72ddd58 100644 --- a/tests/test_lib/polyfill/test_h3.py +++ b/tests/test_lib/polyfill/test_h3.py @@ -119,63 +119,63 @@ def test_polygon_to_cells(): def test_polygon_to_cells_experimental(): poly = h3.LatLngPoly(sf_7x7) - for flags in [0, 'containment_center', h3.ContainmentMode.containment_center]: - # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` - out = h3.polygon_to_cells_experimental(poly, res=9, flags=flags) + # Note that `polygon_to_cells_experimental` is an alias for + # `h3shape_to_cells_experimental` + out = h3.polygon_to_cells_experimental(poly, res=9, contain='center') - assert len(out) == 1253 - assert '89283080527ffff' in out - assert '89283095edbffff' in out + assert len(out) == 1253 + assert '89283080527ffff' in out + assert '89283095edbffff' in out -def test_polygon_to_cells_experimental_full(): +def test_h3shape_to_cells_experimental(): poly = h3.LatLngPoly(sf_7x7) - for flags in [1, 'containment_full', h3.ContainmentMode.containment_full]: - # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` - out = h3.polygon_to_cells_experimental(poly, res=9, flags=flags) - assert len(out) == 1175 - assert '89283082a1bffff' in out - assert '89283080527ffff' not in out - assert '89283095edbffff' in out + out = h3.h3shape_to_cells_experimental(poly, res=9, contain='center') + + assert len(out) == 1253 + assert '89283080527ffff' in out + assert '89283095edbffff' in out -def test_polygon_to_cells_experimental_overlapping(): +def test_h3shape_to_cells_experimental_full(): poly = h3.LatLngPoly(sf_7x7) - for flags in [ - 2, - 'containment_overlapping', - h3.ContainmentMode.containment_overlapping - ]: - # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` - out = h3.polygon_to_cells_experimental(poly, res=9, flags=flags) - assert len(out) == 1334 - assert '89283080527ffff' in out - assert '89283095edbffff' in out + out = h3.h3shape_to_cells_experimental(poly, res=9, contain='full') + + assert len(out) == 1175 + assert '89283082a1bffff' in out + assert '89283080527ffff' not in out + assert '89283095edbffff' in out -def test_polygon_to_cells_experimental_overlapping_bbox(): +def test_h3shape_to_cells_experimental_overlapping(): poly = h3.LatLngPoly(sf_7x7) - for flags in [ - 3, - 'containment_overlapping_bbox', - h3.ContainmentMode.containment_overlapping_bbox - ]: - # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` - out = h3.polygon_to_cells_experimental(poly, res=9, flags=flags) - assert len(out) == 1416 - assert '89283080527ffff' in out - assert '89283095edbffff' in out + out = h3.h3shape_to_cells_experimental(poly, res=9, contain='overlap') + + assert len(out) == 1334 + assert '89283080527ffff' in out + assert '89283095edbffff' in out -def test_polygon_to_cells_experimental_invalid_mode(): +def test_h3shape_to_cells_experimental_overlapping_bbox(): poly = h3.LatLngPoly(sf_7x7) - for flags in [1.0, 'containment_overlapping_bbox_abc', None]: - with pytest.raises(ValueError): - # Note that `polygon_to_cells` is an alias for `h3shape_to_cells` - h3.polygon_to_cells_experimental(poly, res=9, flags=flags) + out = h3.h3shape_to_cells_experimental(poly, res=9, contain='bbox_overlap') + + assert len(out) == 1416 + assert '89283080527ffff' in out + assert '89283095edbffff' in out + + +def test_h3shape_to_cells_experimental_invalid_mode(): + poly = h3.LatLngPoly(sf_7x7) + with pytest.raises(KeyError): + h3.h3shape_to_cells_experimental( + poly, + res = 9, + contain = 'contain_overlapping_bbox_abc', + ) def test_poly_to_cells_experimental_mpoly(): @@ -185,25 +185,25 @@ def test_poly_to_cells_experimental_mpoly(): ) assert ( - set(h3.polygon_to_cells_experimental(mpoly, res=9)) + set(h3.h3shape_to_cells_experimental(mpoly, res=9)) == - set(h3.polygon_to_cells_experimental(mpoly, res=9, flags='containment_center')) + set(h3.h3shape_to_cells_experimental(mpoly, res=9, contain='center')) ) assert ( - set(h3.polygon_to_cells_experimental(mpoly, res=9)) + set(h3.h3shape_to_cells_experimental(mpoly, res=9)) < - set(h3.polygon_to_cells_experimental( + set(h3.h3shape_to_cells_experimental( mpoly, - res=9, - flags='containment_overlapping' + res = 9, + contain = 'overlap' )) ) - assert 120 == len(h3.polygon_to_cells_experimental( + assert 120 == len(h3.h3shape_to_cells_experimental( mpoly, - res=9, - flags='containment_overlapping' + res = 9, + contain = 'overlap' )) From e054120e1b314289526b8a42e04b9658f2e19123 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Mon, 27 Jan 2025 11:38:18 -0800 Subject: [PATCH 116/177] Prep for v4.2.0 release (#438) * prep for v4.2.0 release * ensure you update the badge on the readme --- CHANGELOG.md | 6 +++++- dev_notes.md | 1 + readme.md | 2 +- 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6833583..9e66c98 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,11 @@ avoid adding features or APIs which do not map onto the ## Unreleased -- Update to v4.2.0. (#432) +None. + +## [4.2.0] - 2025-01-26 + +- Update h3lib to v4.2.0. (#432) - Add `h3shape_to_cells_experimental` (#436) - Add `polygon_to_cells_experimental` alias diff --git a/dev_notes.md b/dev_notes.md index 71d514d..300ee42 100644 --- a/dev_notes.md +++ b/dev_notes.md @@ -49,6 +49,7 @@ git submodule update --init - update `CHANGELOG.md` to reflect any changes since the last release - update the `h3-py` version in `pyproject.toml` +- if updating the C `h3lib` version, update the version badge on the readme - create PR, get reviews, and merge with these changes - go to https://github.com/uber/h3-py/releases and "Draft a new release" - set the tag version and the release to the version. e.g., `v3.7.2` diff --git a/readme.md b/readme.md index 4a8a4b5..d37f1a4 100644 --- a/readme.md +++ b/readme.md @@ -5,7 +5,7 @@ [![PyPI version](https://badge.fury.io/py/h3.svg)](https://badge.fury.io/py/h3) [![PyPI downloads](https://img.shields.io/pypi/dm/h3.svg)](https://pypistats.org/packages/h3) [![conda](https://img.shields.io/conda/vn/conda-forge/h3-py.svg)](https://anaconda.org/conda-forge/h3-py) -[![version](https://img.shields.io/badge/h3-v4.1.0-blue.svg)](https://github.com/uber/h3/releases/tag/v4.1.0) +[![version](https://img.shields.io/badge/h3-v4.2.0-blue.svg)](https://github.com/uber/h3/releases/tag/v4.2.0) [![version](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/uber/h3-py/blob/master/LICENSE) [![Tests](https://github.com/uber/h3-py/workflows/tests/badge.svg)](https://github.com/uber/h3-py/actions) From ea05321c1d732527e64d9887b5e28fdfc2f4b3bb Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Thu, 30 Jan 2025 13:41:06 -0800 Subject: [PATCH 117/177] Fix pyproject.toml links --- pyproject.toml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 06ce0e3..8415a41 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -38,11 +38,11 @@ classifiers = [ ] [project.urls] -Homepage = 'https://github.com/organization/package' -Documentation = 'https://package.readthedocs.io/' -'Bug Tracker' = 'https://github.com/organization/package/issues' -Discussions = 'https://github.com/organization/package/discussions' -Changelog = 'https://package.readthedocs.io/en/latest/changelog.html' +Homepage = 'https://github.com/uber/h3-py' +Documentation = 'https://uber.github.io/h3-py/' +'Bug Tracker' = 'https://github.com/uber/h3-py/issues' +Discussions = 'https://github.com/uber/h3-py/discussions' +Changelog = 'https://uber.github.io/h3-py/_changelog.html' [project.optional-dependencies] From e02cd4f4f96c0dde35083de206a6d41db82596c0 Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Thu, 30 Jan 2025 20:49:51 -0800 Subject: [PATCH 118/177] Update coverage badge in readme.md Fixes #439 --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index d37f1a4..e50dbfa 100644 --- a/readme.md +++ b/readme.md @@ -9,7 +9,7 @@ [![version](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/uber/h3-py/blob/master/LICENSE) [![Tests](https://github.com/uber/h3-py/workflows/tests/badge.svg)](https://github.com/uber/h3-py/actions) -[![codecov](https://codecov.io/gh/uber/h3-py/branch/master/graph/badge.svg)](https://codecov.io/gh/uber/h3-py) +[![Coverage 100%](https://img.shields.io/badge/coverage-100%25-green.svg)](https://github.com/uber/h3-py/blob/master/.github/workflows/lint_and_coverage.yml#L31) Python bindings for the [H3 core library](https://h3geo.org/). From ae375a987c107b5bc2b4315db7d8957ede9ea026 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Fri, 31 Jan 2025 14:32:21 -0800 Subject: [PATCH 119/177] fix links (#444) --- CHANGELOG.md | 5 +++++ pyproject.toml | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9e66c98..e9a29bd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,11 @@ avoid adding features or APIs which do not map onto the None. +## [4.2.1] - 2025-01-31 + +- Correct pyproject.toml links for PyPI (#441) +- Update coverage badge (#443) + ## [4.2.0] - 2025-01-26 - Update h3lib to v4.2.0. (#432) diff --git a/pyproject.toml b/pyproject.toml index 8415a41..eee5951 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.2.0' +version = '4.2.1' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} From b40bc47f779bf6e0759b926dba783be2a340b6c6 Mon Sep 17 00:00:00 2001 From: Sukhdeep Gill Date: Sat, 22 Feb 2025 22:46:42 +0530 Subject: [PATCH 120/177] reducing width for the H3 Logo so that it comes before the horizontal line (#447) --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index e50dbfa..9a84445 100644 --- a/readme.md +++ b/readme.md @@ -1,4 +1,4 @@ -H3 Logo +H3 Logo # **h3-py**: Uber's H3 Hexagonal Hierarchical Geospatial Indexing System in Python From 5b6382d12071fae93db19eeec888ff9742a9d33d Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Mon, 10 Mar 2025 09:27:55 -0700 Subject: [PATCH 121/177] bump to h3 4.2.1 (#450) --- readme.md | 2 +- src/h3lib | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/readme.md b/readme.md index 9a84445..c6cabd6 100644 --- a/readme.md +++ b/readme.md @@ -5,7 +5,7 @@ [![PyPI version](https://badge.fury.io/py/h3.svg)](https://badge.fury.io/py/h3) [![PyPI downloads](https://img.shields.io/pypi/dm/h3.svg)](https://pypistats.org/packages/h3) [![conda](https://img.shields.io/conda/vn/conda-forge/h3-py.svg)](https://anaconda.org/conda-forge/h3-py) -[![version](https://img.shields.io/badge/h3-v4.2.0-blue.svg)](https://github.com/uber/h3/releases/tag/v4.2.0) +[![version](https://img.shields.io/badge/h3-v4.2.1-blue.svg)](https://github.com/uber/h3/releases/tag/v4.2.1) [![version](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/uber/h3-py/blob/master/LICENSE) [![Tests](https://github.com/uber/h3-py/workflows/tests/badge.svg)](https://github.com/uber/h3-py/actions) diff --git a/src/h3lib b/src/h3lib index 2d8a62d..067d9c7 160000 --- a/src/h3lib +++ b/src/h3lib @@ -1 +1 @@ -Subproject commit 2d8a62d5fe456bba2af7ca0be7efe9754f1dd25b +Subproject commit 067d9c7d80061118e953fa682e56e49f571fa7a1 From 856d481de31c54aaa6076020ade6b88ed4d316cc Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Mon, 10 Mar 2025 11:30:25 -0700 Subject: [PATCH 122/177] prep for v4.2.2 release (#451) --- CHANGELOG.md | 4 ++++ pyproject.toml | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e9a29bd..4f57f92 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ avoid adding features or APIs which do not map onto the None. +## [4.2.2] - 2025-03-10 + +- Update h3lib to v4.2.1. (#450) + ## [4.2.1] - 2025-01-31 - Correct pyproject.toml links for PyPI (#441) diff --git a/pyproject.toml b/pyproject.toml index eee5951..38e4c91 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.2.1' +version = '4.2.2' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} From e2744ccbcf25d4d93cab9d858a5bcb3edb03db21 Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Tue, 17 Jun 2025 16:57:21 -0500 Subject: [PATCH 123/177] update for h3 4.3.0 --- CHANGELOG.md | 2 +- src/h3/_cy/cells.pyx | 44 ++++---------------------------------------- src/h3lib | 2 +- 3 files changed, 6 insertions(+), 42 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4f57f92..2e5154f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,7 @@ avoid adding features or APIs which do not map onto the ## Unreleased -None. +- Update h3lib to v4.3.0. (#) ## [4.2.2] - 2025-03-10 diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 2b57af2..928b665 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -87,41 +87,6 @@ cpdef H3int[:] grid_disk(H3int h, int k): return mv -cpdef H3int[:] _ring_fallback(H3int h, int k): - """ - `ring` tries to call `h3lib.hexRing` first; if that fails, we call - this function, which relies on `h3lib.kRingDistances`. - - Failures for `h3lib.hexRing` happen when the algorithm runs into a pentagon. - """ - cdef: - int64_t n - int[:] distances ## todo: weird, this needs to be specified to avoid errors. cython bug? - - check_cell(h) - check_distance(k) - - check_for_error( - h3lib.maxGridDiskSize(k, &n) - ) - hmm = H3MemoryManager(n) - - # parallel array of cell distances from `h`. - # idea: instead of a memoryview object, have a my_mv object that can return a ptr, but does the correct logic when it has length 0 - # then can always just return the pointer, instead of the weird &mv[0] syntax - distances = int_mv(n) - check_for_error( - h3lib.gridDiskDistances(h, k, hmm.ptr, &distances[0]) - ) - - for i,v in enumerate(distances): - if v != k: - hmm.ptr[i] = 0 - - mv = hmm.to_mv() - - return mv - cpdef H3int[:] grid_ring(H3int h, int k): """ Return cells at grid distance `== k` from `h`. Collection is "hollow" for k >= 1. @@ -131,11 +96,10 @@ cpdef H3int[:] grid_ring(H3int h, int k): n = 6*k if k > 0 else 1 hmm = H3MemoryManager(n) - err = h3lib.gridRingUnsafe(h, k, hmm.ptr) - if err: - mv = _ring_fallback(h, k) - else: - mv = hmm.to_mv() + check_for_error( + h3lib.gridRing(h, k, hmm.ptr) + ) + mv = hmm.to_mv() return mv diff --git a/src/h3lib b/src/h3lib index 067d9c7..f6d1b0b 160000 --- a/src/h3lib +++ b/src/h3lib @@ -1 +1 @@ -Subproject commit 067d9c7d80061118e953fa682e56e49f571fa7a1 +Subproject commit f6d1b0ba0a0eb076abe655ffdd576a445373a39e From e80494c8ea98af03afa9b3b8db456f7266dec3ca Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Tue, 17 Jun 2025 16:57:55 -0500 Subject: [PATCH 124/177] readme --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index c6cabd6..1a82d89 100644 --- a/readme.md +++ b/readme.md @@ -5,7 +5,7 @@ [![PyPI version](https://badge.fury.io/py/h3.svg)](https://badge.fury.io/py/h3) [![PyPI downloads](https://img.shields.io/pypi/dm/h3.svg)](https://pypistats.org/packages/h3) [![conda](https://img.shields.io/conda/vn/conda-forge/h3-py.svg)](https://anaconda.org/conda-forge/h3-py) -[![version](https://img.shields.io/badge/h3-v4.2.1-blue.svg)](https://github.com/uber/h3/releases/tag/v4.2.1) +[![version](https://img.shields.io/badge/h3-v4.3.0-blue.svg)](https://github.com/uber/h3/releases/tag/v4.3.0) [![version](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/uber/h3-py/blob/master/LICENSE) [![Tests](https://github.com/uber/h3-py/workflows/tests/badge.svg)](https://github.com/uber/h3-py/actions) From f82581f512a3f516eafe7261ff9e4f88b3107192 Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Tue, 17 Jun 2025 16:58:26 -0500 Subject: [PATCH 125/177] pr number --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e5154f..fb995e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,7 @@ avoid adding features or APIs which do not map onto the ## Unreleased -- Update h3lib to v4.3.0. (#) +- Update h3lib to v4.3.0. (#461) ## [4.2.2] - 2025-03-10 From 45d9c3f48273c2d84aa63f83d716c2a2207cabd7 Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Tue, 17 Jun 2025 17:50:19 -0500 Subject: [PATCH 126/177] fix --- src/h3/_cy/h3lib.pxd | 1 + 1 file changed, 1 insertion(+) diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index 4a483b2..e94f655 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -139,6 +139,7 @@ cdef extern from 'h3api.h': H3Error localIjToCell(H3int origin, const CoordIJ *ij, uint32_t mode, H3int *out) nogil H3Error gridDiskDistances(H3int origin, int k, H3int *out, int *distances) nogil + H3Error gridRing(H3int origin, int k, H3int *out) nogil H3Error gridRingUnsafe(H3int origin, int k, H3int *out) nogil H3Error areNeighborCells(H3int origin, H3int destination, int *out) nogil From a8c5ae7b279b80c6f37ff7e944a136a84829b6f2 Mon Sep 17 00:00:00 2001 From: Isaac Brodsky Date: Tue, 17 Jun 2025 17:52:00 -0500 Subject: [PATCH 127/177] fix version --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 38e4c91..8e77163 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.2.2' +version = '4.3.0' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} From ce0638d7cedb034a7b533e875e996da88a2a7268 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Wed, 18 Jun 2025 09:20:22 -0700 Subject: [PATCH 128/177] prep for 4.3.0 release (#462) --- CHANGELOG.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fb995e7..8cbc3f0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,10 @@ avoid adding features or APIs which do not map onto the ## Unreleased -- Update h3lib to v4.3.0. (#461) +## [4.3.0] - 2025-06-17 + +- Update `h3lib` to v4.3.0. (#461) + - Uses `gridRing` (uber/h3#1016) instead of Cython fallback logic. ## [4.2.2] - 2025-03-10 From 4fc8ec9ca683856e97cd3dc9822c40bd229756af Mon Sep 17 00:00:00 2001 From: newyork_loki <137760120+lowkeyrossi@users.noreply.github.com> Date: Mon, 11 Aug 2025 00:04:06 +0530 Subject: [PATCH 129/177] Add support for building h3-py wheel on WoA (#463) * Add support for building h3-py wheel on WoA * Use official MSVC reusable action for Win-builds --- .github/workflows/wheels.yml | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index c70b891..99e81d1 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -71,6 +71,16 @@ jobs: build: 'cp3*-win_amd64' name: Windows 64-bit + - os: windows-11-arm + build: 'cp311-win_arm64' + name: Windows ARM64 3.11 + - os: windows-11-arm + build: 'cp312-win_arm64' + name: Windows ARM64 3.12 + - os: windows-11-arm + build: 'cp313-win_arm64' + name: Windows ARM64 3.13 + - os: ubuntu-22.04 build: 'cp*-manylinux_x86_64' name: Linux Intel glibc 64-bit @@ -118,8 +128,17 @@ jobs: with: submodules: recursive - - uses: ilammy/msvc-dev-cmd@v1.13.0 - if: runner.os == 'Windows' + - name: Set MSVC for Windows-x64 + uses: microsoft/setup-msbuild@v2 + if: matrix.os == 'windows-latest' + with: + msbuild-architecture: x64 + + - name: Set MSVC for Windows-ARM64 + uses: microsoft/setup-msbuild@v2 + if: matrix.os == 'windows-11-arm' + with: + msbuild-architecture: arm64 - name: Set Windows variables if: runner.os == 'Windows' @@ -134,7 +153,7 @@ jobs: with: platforms: aarch64 - - uses: pypa/cibuildwheel@v2.21.3 + - uses: pypa/cibuildwheel@v3.1.3 env: CIBW_TEST_REQUIRES: pytest pytest-cov numpy CIBW_TEST_COMMAND: pytest {project}/tests From bd455be97581f0abd8d1afed41e0be066cf51e9a Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 10 Aug 2025 12:30:56 -0700 Subject: [PATCH 130/177] prep for v4.3.1 release (#464) --- CHANGELOG.md | 6 ++++++ pyproject.toml | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8cbc3f0..77fc091 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,12 @@ avoid adding features or APIs which do not map onto the ## Unreleased +None. + +## [4.3.1] - 2025-08-10 + +- Build wheels for Windows on ARM64 (#463) + ## [4.3.0] - 2025-06-17 - Update `h3lib` to v4.3.0. (#461) diff --git a/pyproject.toml b/pyproject.toml index 8e77163..9f88ce8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.3.0' +version = '4.3.1' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} From 99b62102b0c72113a6416a7c6407ba4ee1deb1da Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 6 Oct 2025 16:46:17 -0700 Subject: [PATCH 131/177] Bump pypa/gh-action-pypi-publish in /.github/workflows (#466) Bumps [pypa/gh-action-pypi-publish](https://github.com/pypa/gh-action-pypi-publish) from 1.10.3 to 1.13.0. - [Release notes](https://github.com/pypa/gh-action-pypi-publish/releases) - [Commits](https://github.com/pypa/gh-action-pypi-publish/compare/v1.10.3...v1.13.0) --- updated-dependencies: - dependency-name: pypa/gh-action-pypi-publish dependency-version: 1.13.0 dependency-type: direct:production ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/wheels.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 99e81d1..e93afab 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -194,6 +194,6 @@ jobs: name: wheels_and_sdist path: dist - - uses: pypa/gh-action-pypi-publish@v1.10.3 + - uses: pypa/gh-action-pypi-publish@v1.13.0 with: password: ${{ secrets.pypi_password }} From 23bef19c74e5332216f079b156aa8ca196e37ec0 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 2 Nov 2025 08:23:06 -0800 Subject: [PATCH 132/177] remove macOS13 from wheels. add macOS15 (#468) * remove macOS13 from wheels. add macOS15 * bump to pypa/cibuildwheel@v3.2.1 * bump actions/setup-python@v6.0.0 * bump actions/upload-artifact@v5.0.0 * bump actions/checkout@v5.0.0 * bump actions/download-artifact@v6.0.0 * bump docker/setup-qemu-action@v3.6.0 * run tests on Python 3.14 * Add a few wheels for Python 3.14 * bump python-version: 3.13 * Revert "bump python-version: 3.13" This reverts commit 8119c62cb60d70b38cf42206c755ce7a6e408716. --- .github/workflows/build_docs.yml | 6 ++--- .github/workflows/lint_and_coverage.yml | 4 +-- .github/workflows/tests.yml | 6 ++--- .github/workflows/wheels.yml | 33 ++++++++++++++++--------- 4 files changed, 29 insertions(+), 20 deletions(-) diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index f6c950c..f8301d1 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -11,11 +11,11 @@ jobs: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v4.2.2 + - uses: actions/checkout@v5.0.0 with: submodules: recursive - - uses: actions/setup-python@v5.3.0 + - uses: actions/setup-python@v6.0.0 with: python-version: 3.11 @@ -28,7 +28,7 @@ jobs: run: jupyter-book build docs/ --warningiserror --keep-going --all - name: Upload artifacts - uses: actions/upload-artifact@v4.4.3 + uses: actions/upload-artifact@v5.0.0 with: name: html path: docs/_build/html diff --git a/.github/workflows/lint_and_coverage.yml b/.github/workflows/lint_and_coverage.yml index 723677c..d9789c7 100644 --- a/.github/workflows/lint_and_coverage.yml +++ b/.github/workflows/lint_and_coverage.yml @@ -12,11 +12,11 @@ jobs: runs-on: ubuntu-24.04 steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v5.0.0 with: submodules: recursive - - uses: actions/setup-python@v5 + - uses: actions/setup-python@v6.0.0 with: python-version: 3.11 diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index cd4153d..a82ec98 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -14,14 +14,14 @@ jobs: strategy: matrix: os: [macos-latest, windows-latest, ubuntu-22.04] - python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13'] + python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14'] steps: - - uses: actions/checkout@v4.2.2 + - uses: actions/checkout@v5.0.0 with: submodules: recursive - - uses: actions/setup-python@v5.3.0 + - uses: actions/setup-python@v6.0.0 with: python-version: '${{ matrix.python-version }}' diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index e93afab..cde27d7 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -23,12 +23,12 @@ jobs: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v4.2.2 + - uses: actions/checkout@v5.0.0 with: submodules: recursive - name: Setup Python - uses: actions/setup-python@v5.3.0 + uses: actions/setup-python@v6.0.0 with: python-version: 3.11 @@ -48,7 +48,7 @@ jobs: run: pytest - name: Upload artifacts to GitHub - uses: actions/upload-artifact@v4.4.3 + uses: actions/upload-artifact@v5.0.0 with: name: temp_result_sdist path: ./dist @@ -60,12 +60,12 @@ jobs: strategy: matrix: include: - - os: macos-13 - build: 'cp*-macosx_x86_64' - name: macOS13 - os: macos-14 build: 'cp*-macosx_arm64' name: macOS14 + - os: macos-15 + build: 'cp*-macosx_arm64' + name: macOS15 - os: windows-latest build: 'cp3*-win_amd64' @@ -80,6 +80,9 @@ jobs: - os: windows-11-arm build: 'cp313-win_arm64' name: Windows ARM64 3.13 + - os: windows-11-arm + build: 'cp314-win_arm64' + name: Windows ARM64 3.14 - os: ubuntu-22.04 build: 'cp*-manylinux_x86_64' @@ -103,6 +106,9 @@ jobs: - os: ubuntu-22.04 build: 'cp313-musllinux_x86_64' name: Linux Intel musl 64-bit 3.13 + - os: ubuntu-22.04 + build: 'cp314-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.14 - os: ubuntu-22.04 build: 'cp38-manylinux_aarch64' @@ -122,9 +128,12 @@ jobs: - os: ubuntu-22.04 build: 'cp313-manylinux_aarch64' name: Linux Aarch64 3.13 + - os: ubuntu-22.04 + build: 'cp314-manylinux_aarch64' + name: Linux Aarch64 3.14 steps: - - uses: actions/checkout@v4.2.2 + - uses: actions/checkout@v5.0.0 with: submodules: recursive @@ -149,11 +158,11 @@ jobs: - name: Set up QEMU if: runner.os == 'Linux' - uses: docker/setup-qemu-action@v3.2.0 + uses: docker/setup-qemu-action@v3.6.0 with: platforms: aarch64 - - uses: pypa/cibuildwheel@v3.1.3 + - uses: pypa/cibuildwheel@v3.2.1 env: CIBW_TEST_REQUIRES: pytest pytest-cov numpy CIBW_TEST_COMMAND: pytest {project}/tests @@ -165,7 +174,7 @@ jobs: pipx run twine check wheelhouse/* - name: Upload artifacts to GitHub - uses: actions/upload-artifact@v4.4.3 + uses: actions/upload-artifact@v5.0.0 with: name: temp_result_${{ matrix.os }}-${{ strategy.job-index }} path: wheelhouse/*.whl @@ -175,7 +184,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Merge Artifacts - uses: actions/upload-artifact/merge@v4.4.3 + uses: actions/upload-artifact/merge@v5.0.0 with: name: wheels_and_sdist pattern: temp_result_* @@ -189,7 +198,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/download-artifact@v4.1.8 + - uses: actions/download-artifact@v6.0.0 with: name: wheels_and_sdist path: dist From f9c1a944d1be1c78e713939c00a70c60dd5219bc Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sat, 22 Nov 2025 08:17:21 -0800 Subject: [PATCH 133/177] 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 --- .gitignore | 1 + CHANGELOG.md | 12 +- docs/api_quick.md | 4 + pyproject.toml | 4 +- src/h3/__init__.py | 4 + src/h3/_cy/__init__.py | 10 ++ src/h3/_cy/cells.pxd | 3 + src/h3/_cy/cells.pyx | 38 +++++- src/h3/_cy/error_system.pxd | 3 + src/h3/_cy/error_system.pyx | 37 +++++- src/h3/_cy/h3lib.pxd | 8 ++ src/h3/_cy/util.pxd | 3 +- src/h3/_cy/util.pyx | 16 ++- src/h3/api/basic_int/__init__.py | 129 +++++++++++++++++++++ src/h3lib | 2 +- tests/test_lib/test_cells_and_edges.py | 154 +++++++++++++++++++++++++ tests/test_lib/test_error_codes.py | 42 ++++--- 17 files changed, 442 insertions(+), 28 deletions(-) diff --git a/.gitignore b/.gitignore index ad8e4f3..cf6fcf3 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ h3c/ .cache/ h3/out/ .ruff_cache/ +_build/ # Generated C code from Cython test tests/**/*.c diff --git a/CHANGELOG.md b/CHANGELOG.md index 77fc091..5349789 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,17 @@ avoid adding features or APIs which do not map onto the ## Unreleased -None. +- Update `h3lib` to v4.4.1. (#470) + - Add new error codes: + - `H3IndexInvalidError` + - `H3BaseCellDomainError` + - `H3DigitDomainError` + - `H3DeletedDigitError` + - Add new functions: + - `is_valid_index` + - `get_index_digit` + - `construct_cell` + - `deconstruct_cell` ## [4.3.1] - 2025-08-10 diff --git a/docs/api_quick.md b/docs/api_quick.md index 7b29638..6694ed4 100644 --- a/docs/api_quick.md +++ b/docs/api_quick.md @@ -25,6 +25,7 @@ and should be generally aligned with the is_res_class_III is_valid_directed_edge is_valid_vertex + is_valid_index ``` ## Index representation @@ -49,6 +50,9 @@ and should be generally aligned with the get_num_cells get_resolution get_base_cell_number + get_index_digit + construct_cell + deconstruct_cell ``` ## Geographic coordinates diff --git a/pyproject.toml b/pyproject.toml index 9f88ce8..4a5e319 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.3.1' +version = '4.4.0' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} @@ -50,7 +50,7 @@ numpy = ['numpy'] test = ['pytest', 'pytest-cov', 'ruff', 'numpy'] all = [ 'h3[test]', - 'jupyter-book', + 'jupyter-book<2', 'sphinx>=7.3.3', # https://github.com/sphinx-doc/sphinx/issues/12290 'jupyterlab', 'jupyterlab-geojson', diff --git a/src/h3/__init__.py b/src/h3/__init__.py index 4f7cb32..1e4f4b8 100644 --- a/src/h3/__init__.py +++ b/src/h3/__init__.py @@ -26,4 +26,8 @@ from ._cy import ( H3MemoryAllocError, H3MemoryBoundsError, H3OptionInvalidError, + H3IndexInvalidError, + H3BaseCellDomainError, + H3DigitDomainError, + H3DeletedDigitError, ) diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index 627f3b9..70fa087 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -14,10 +14,13 @@ function interface and input conversion (string to int, for instance). """ from .cells import ( + is_valid_index, is_valid_cell, is_pentagon, get_base_cell_number, get_resolution, + get_index_digit, + construct_cell, cell_to_parent, grid_distance, grid_disk, @@ -109,4 +112,11 @@ from .error_system import ( H3MemoryAllocError, H3MemoryBoundsError, H3OptionInvalidError, + H3IndexInvalidError, + H3BaseCellDomainError, + H3DigitDomainError, + H3DeletedDigitError, + + get_H3_ERROR_END, + error_code_to_exception, ) diff --git a/src/h3/_cy/cells.pxd b/src/h3/_cy/cells.pxd index 06b35ee..1bc31b8 100644 --- a/src/h3/_cy/cells.pxd +++ b/src/h3/_cy/cells.pxd @@ -1,9 +1,12 @@ from .h3lib cimport bool, int64_t, H3int +cpdef bool is_valid_index(H3int h) cpdef bool is_valid_cell(H3int h) cpdef bool is_pentagon(H3int h) cpdef int get_base_cell_number(H3int h) except -1 cpdef int get_resolution(H3int h) except -1 +cpdef int get_index_digit(H3int h, int res) except -1 +cpdef H3int construct_cell(int baseCellNumber, const int[:] digits) except 0 cpdef int grid_distance(H3int h1, H3int h2) except -1 cpdef H3int[:] grid_disk(H3int h, int k) cpdef H3int[:] grid_ring(H3int h, int k) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 928b665..78d2561 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -3,11 +3,12 @@ from .h3lib cimport bool, int64_t, H3int, H3ErrorCodes from .util cimport ( check_cell, - check_res, # we don't use? + check_index, check_distance, ) from .error_system cimport ( + H3Error, check_for_error, check_for_error_msg, ) @@ -19,6 +20,14 @@ from .memory cimport ( # todo: add notes about Cython exception handling +cpdef bool is_valid_index(H3int h): + """Validates an H3 index (cell, vertex, or directed edge). + + Returns + ------- + boolean + """ + return h3lib.isValidIndex(h) == 1 # bool is a python type, so we don't need the except clause cpdef bool is_valid_cell(H3int h): @@ -49,6 +58,33 @@ cpdef int get_resolution(H3int h) except -1: return h3lib.getResolution(h) +cpdef int get_index_digit(H3int h, int res) except -1: + cdef: + int digit + + check_index(h) + + check_for_error( + h3lib.getIndexDigit(h, res, &digit) + ) + + return digit + +cpdef H3int construct_cell(int base_cell_number, const int[:] digits) except 0: + cdef: + H3int out + int res = len(digits) + H3Error err + + if res > 0: + err = h3lib.constructCell(res, base_cell_number, &digits[0], &out) + else: + err = h3lib.constructCell(res, base_cell_number, NULL, &out) + + check_for_error(err) + + return out + cpdef int grid_distance(H3int h1, H3int h2) except -1: """ Compute the grid distance between two cells diff --git a/src/h3/_cy/error_system.pxd b/src/h3/_cy/error_system.pxd index af8c709..4a1e3b4 100644 --- a/src/h3/_cy/error_system.pxd +++ b/src/h3/_cy/error_system.pxd @@ -1,3 +1,6 @@ from .h3lib cimport H3Error + +cpdef error_code_to_exception(H3Error err) cdef check_for_error(H3Error err) cdef check_for_error_msg(H3Error err, str msg) +cpdef H3Error get_H3_ERROR_END() diff --git a/src/h3/_cy/error_system.pyx b/src/h3/_cy/error_system.pyx index fbdd918..fc18f46 100644 --- a/src/h3/_cy/error_system.pyx +++ b/src/h3/_cy/error_system.pyx @@ -60,6 +60,10 @@ Summarizing, all exceptions originating from the C library inherit from - H3MemoryAllocError - H3MemoryBoundsError - H3OptionInvalidError +- H3IndexInvalidError +- H3BaseCellDomainError +- H3DigitDomainError +- H3DeletedDigitError # TODO: add tests verifying that concrete exception classes have the right error codes associated with them @@ -87,6 +91,11 @@ from .h3lib cimport ( E_MEMORY_ALLOC, E_MEMORY_BOUNDS, E_OPTION_INVALID, + E_INDEX_INVALID, + E_BASE_CELL_DOMAIN, + E_DIGIT_DOMAIN, + E_DELETED_DIGIT, + H3_ERROR_END # sentinel value ) @contextmanager @@ -169,6 +178,10 @@ with _the_error(H3ValueError) as e: class H3NotNeighborsError(e): ... class H3ResMismatchError(e): ... class H3OptionInvalidError(e): ... + class H3IndexInvalidError(e): ... + class H3BaseCellDomainError(e): ... + class H3DigitDomainError(e): ... + class H3DeletedDigitError(e): ... """ @@ -192,6 +205,10 @@ error_mapping = { E_MEMORY_ALLOC: H3MemoryAllocError, E_MEMORY_BOUNDS: H3MemoryBoundsError, E_OPTION_INVALID: H3OptionInvalidError, + E_INDEX_INVALID: H3IndexInvalidError, + E_BASE_CELL_DOMAIN: H3BaseCellDomainError, + E_DIGIT_DOMAIN: H3DigitDomainError, + E_DELETED_DIGIT: H3DeletedDigitError, } # Go back and modify the class definitions so that each concrete exception @@ -207,25 +224,37 @@ for code, ex in error_mapping.items(): # TODO: Move the helpers to util? # TODO: Unclear how/where to expose these functions. cdef/cpdef? -cdef code_to_exception(H3Error err): +cpdef error_code_to_exception(H3Error err): + """ + Return Python exception corresponding to integer error code + given via the H3ErrorCodes enum in `h3api.h.in` in the C library. + """ if err == E_SUCCESS: return None elif err in error_mapping: return error_mapping[err] else: - raise UnknownH3ErrorCode(err) + return UnknownH3ErrorCode(err) cdef check_for_error(H3Error err): - ex = code_to_exception(err) + ex = error_code_to_exception(err) if ex: raise ex +cpdef H3Error get_H3_ERROR_END(): + """ + Return integer H3_ERROR_END from the H3ErrorCodes enum + in `h3api.h.in` in the C library, which is one greater than + the last valid error code. + """ + return H3_ERROR_END + # todo: There's no easy way to do `*args` in `cdef` functions, but I'm also # not sure this even needs to be a Cython `cdef` function at all, or that # any of the other helper functions need to be in Cython. # todo: Revisit after we've played with this a bit. # todo: also: maybe the extra messages aren't that much more helpful... cdef check_for_error_msg(H3Error err, str msg): - ex = code_to_exception(err) + ex = error_code_to_exception(err) if ex: raise ex(msg) diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index e94f655..8cf74a7 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -29,6 +29,11 @@ cdef extern from 'h3api.h': E_MEMORY_ALLOC = 13 E_MEMORY_BOUNDS = 14 E_OPTION_INVALID = 15 + E_INDEX_INVALID = 16 + E_BASE_CELL_DOMAIN = 17 + E_DIGIT_DOMAIN = 18 + E_DELETED_DIGIT = 19 + H3_ERROR_END # sentinel value ctypedef struct LatLng: double lat # in radians @@ -71,12 +76,15 @@ cdef extern from 'h3api.h': int isResClassIII(H3int h) nogil int isValidDirectedEdge(H3int edge) nogil int isValidVertex(H3int v) nogil + int isValidIndex(H3int h) nogil double degsToRads(double degrees) nogil double radsToDegs(double radians) nogil int getResolution(H3int h) nogil int getBaseCellNumber(H3int h) nogil + H3Error getIndexDigit(H3int h, int res, int *out) nogil + H3Error constructCell(int res, int baseCellNumber, const int *digits, H3int *out) nogil H3Error latLngToCell(const LatLng *g, int res, H3int *out) nogil H3Error cellToLatLng(H3int h, LatLng *) nogil diff --git a/src/h3/_cy/util.pxd b/src/h3/_cy/util.pxd index 4d7d962..b584d3a 100644 --- a/src/h3/_cy/util.pxd +++ b/src/h3/_cy/util.pxd @@ -8,6 +8,7 @@ cpdef H3str int_to_str(H3int x) cdef check_cell(H3int h) cdef check_edge(H3int e) -cdef check_res(int res) cdef check_vertex(H3int v) +cdef check_index(H3int h) +cdef check_res(int res) cdef check_distance(int k) diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index 7b8a9f2..9b070f9 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -1,4 +1,11 @@ -from .h3lib cimport H3int, H3str, isValidCell, isValidDirectedEdge, isValidVertex +from .h3lib cimport ( + H3int, + H3str, + isValidCell, + isValidDirectedEdge, + isValidVertex, + isValidIndex, +) cimport h3lib @@ -7,7 +14,8 @@ from .error_system import ( H3DomainError, H3DirEdgeInvalidError, H3CellInvalidError, - H3VertexInvalidError + H3VertexInvalidError, + H3IndexInvalidError, ) cdef h3lib.LatLng deg2coord(double lat, double lng) nogil: @@ -78,6 +86,10 @@ cdef check_vertex(H3int v): if isValidVertex(v) == 0: raise H3VertexInvalidError('Integer is not a valid H3 vertex: {}'.format(hex(v))) +cdef check_index(H3int h): + if isValidIndex(h) == 0: + raise H3IndexInvalidError('Integer is not a valid H3 index: {}'.format(hex(h))) + cdef check_res(int res): if (res < 0) or (res > 15): raise H3ResDomainError(res) diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index 09f7deb..47f1c7e 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -1,5 +1,6 @@ # This file is **symlinked** across the APIs to ensure they are exactly the same. from typing import Literal +from array import array from ... import _cy from ..._h3shape import ( @@ -128,6 +129,20 @@ def average_hexagon_edge_length(res, unit='km'): return _cy.average_hexagon_edge_length(res, unit) +def is_valid_index(h): + """Validates *any* H3 index (cell, vertex, or directed edge). + + Returns + ------- + bool + """ + try: + h = _in_scalar(h) + return _cy.is_valid_index(h) + except (ValueError, TypeError): + return False + + def is_valid_cell(h): """ Validates an H3 cell (hexagon or pentagon). @@ -736,10 +751,124 @@ def get_base_cell_number(h): Returns ------- int + + Examples + -------- + >>> h = construct_cell(57, 2, 1, 4) + >>> h + '83728cfffffffff' + >> get_base_cell_number(h) + 57 """ return _cy.get_base_cell_number(_in_scalar(h)) +def get_index_digit(h, res): + """ + Get the index digit of a cell at the given resolution. + + Parameters + ---------- + h : H3Cell + Cell whose index digit will be returned. + res : int + Resolution (``>= 1``) at which to read the digit. + + Returns + ------- + int + The index digit at the requested resolution. + + Examples + -------- + >>> h = construct_cell(7, 2, 1, 4) + >>> h + '830e8cfffffffff' + >>> get_index_digit(h, 1) + 2 + >>> get_index_digit(h, 2) + 1 + >>> get_index_digit(h, 3) + 4 + """ + return _cy.get_index_digit(_in_scalar(h), res) + + +def construct_cell(base_cell_number, *digits, res=None): + """ + Construct cell from base cell and digits. + + Parameters + ---------- + base_cell_number : int + Base cell *number* (``0`` to ``121``). + *digits : int + Sequence of index digits (``0`` to ``6``). + Length of digits will be the resulting resolution of the output cell. + res : int, optional + Resolution of the constructed cell. If provided, it must equal + ``len(digits)``; otherwise it is inferred from the number of digits. + + Returns + ------- + H3Cell + The constructed cell. + + Examples + -------- + >>> construct_cell(7, 2, 1, 4) # resolution 3 cell + '830e8cfffffffff' + + >>> construct_cell(15, 0, 0, 5, 3) # resolution 4 cell + '841e057ffffffff' + + >>> construct_cell(15, 0, 0, 5, 3, res=4) + '841e057ffffffff' + """ + if (res is not None) and (len(digits) != res): + raise ValueError('Resolution must match number of digits.') + + digits = array('i', digits) + o = _cy.construct_cell(base_cell_number, digits) + return _out_scalar(o) + + +def deconstruct_cell(h): + """ + Deconstruct cell into base cell and digits. + + Parameters + ---------- + h : H3Cell + Cell to deconstruct. + + Returns + ------- + list of int + [base_cell_number, digit1, digit2, ..., digitN] + + Examples + -------- + >>> h = construct_cell(7, 2, 1, 4) # resolution 3 cell + >>> h + '830e8cfffffffff' + >>> deconstruct_cell(h) + (7, 2, 1, 4) + + >>> h = construct_cell(15, 0, 0, 5, 3) # resolution 4 cell + >>> h + '841e057ffffffff' + >>> deconstruct_cell(h) + (15, 0, 0, 5, 3) + >>> construct_cell(*deconstruct_cell(h), 0) == cell_to_center_child(h) + """ + res = get_resolution(h) + bc = get_base_cell_number(h) + digits = [get_index_digit(h, r + 1) for r in range(res)] + + return [bc, *digits] + + def are_neighbor_cells(h1, h2): """ Returns ``True`` if ``h1`` and ``h2`` are neighboring cells. diff --git a/src/h3lib b/src/h3lib index f6d1b0b..70d4c9e 160000 --- a/src/h3lib +++ b/src/h3lib @@ -1 +1 @@ -Subproject commit f6d1b0ba0a0eb076abe655ffdd576a445373a39e +Subproject commit 70d4c9e5007d74d77714afa44d5a2e52606828bf diff --git a/tests/test_lib/test_cells_and_edges.py b/tests/test_lib/test_cells_and_edges.py index f918019..c461582 100644 --- a/tests/test_lib/test_cells_and_edges.py +++ b/tests/test_lib/test_cells_and_edges.py @@ -8,6 +8,10 @@ from h3 import ( H3ResMismatchError, H3CellInvalidError, H3NotNeighborsError, + H3DigitDomainError, + H3BaseCellDomainError, + H3DeletedDigitError, + H3IndexInvalidError, ) @@ -597,3 +601,153 @@ def test_to_local_ij_self(): out = h3.cell_to_local_ij(h, h) assert out == (-858, -2766) + + +def test_is_valid_index(): + assert h3.is_valid_index('8001fffffffffff') + assert not h3.is_valid_index('8a28308280fffff') + assert not h3.is_valid_index(123) + assert not h3.is_valid_index('abcd') + + +def test_is_valid_index_2(): + import h3.api.basic_int as h3 + + h = h3.latlng_to_cell(0,0,9) + assert h3.is_valid_index(h) + assert not h3.is_valid_index(h + 1) + assert not h3.is_valid_directed_edge(h) + assert not h3.is_valid_vertex(h) + + e = h3.origin_to_directed_edges(h)[0] + assert h3.is_valid_index(e) + assert not h3.is_valid_index(e + 1) + assert not h3.is_valid_cell(e) + assert not h3.is_valid_vertex(e) + + v = h3.cell_to_vertex(h, 0) + assert h3.is_valid_index(v) + assert not h3.is_valid_index(v + 1) + assert not h3.is_valid_cell(v) + assert not h3.is_valid_directed_edge(v) + + +def test_get_index_digit(): + assert h3.get_index_digit('822377fffffffff', 1) == 5 + assert h3.get_index_digit('822377fffffffff', 2) == 6 + assert h3.get_index_digit('822377fffffffff', 3) == 7 + assert h3.get_index_digit('822377fffffffff', 15) == 7 + + with pytest.raises(H3ResDomainError): + h3.get_index_digit('822377fffffffff', 16) + + with pytest.raises(H3ResDomainError): + h3.get_index_digit('822377fffffffff', 0) + + with pytest.raises(H3ResDomainError): + h3.get_index_digit('822377fffffffff',-1) + + +def test_get_index_digit_non_cells(): + h = h3.construct_cell(111, 3, 6, 4) + assert h == '83def4fffffffff' + + e = h3.origin_to_directed_edges(h)[0] + assert e == '113def4fffffffff' + assert h3.is_valid_directed_edge(e) + assert h3.get_index_digit(e, 1) == 3 + assert h3.get_index_digit(e, 2) == 6 + assert h3.get_index_digit(e, 3) == 4 + + e = h3.int_to_str(1 + h3.str_to_int(e)) + assert not h3.is_valid_directed_edge(e) + assert not h3.is_valid_index(e) + with pytest.raises(H3IndexInvalidError): + h3.get_index_digit(e, 1) + + v = h3.cell_to_vertexes(h)[0] + assert v == '223de1afffffffff' + assert h3.is_valid_vertex(v) + assert h3.get_index_digit(v, 1) == 0 + assert h3.get_index_digit(v, 2) == 3 + assert h3.get_index_digit(v, 3) == 2 + + v = h3.int_to_str(1 + h3.str_to_int(v)) + assert not h3.is_valid_vertex(v) + assert not h3.is_valid_index(v) + with pytest.raises(H3IndexInvalidError): + h3.get_index_digit(v, 1) + + +def test_construct_cell(): + bc = 17 + assert h3.construct_cell(bc, 5, 6) == '822377fffffffff' + assert h3.construct_cell(bc) == '8023fffffffffff' + + digits = [0] * 15 + assert h3.construct_cell(bc, *digits) == '8f2200000000000' + + with pytest.raises(H3ResDomainError): + digits = [0] * 16 + h3.construct_cell(bc, *digits) + + with pytest.raises(ValueError): + digits = [1,2,3,4] + h3.construct_cell(bc, *digits, res=2) + + with pytest.raises(H3DigitDomainError): + h3.construct_cell(121, 1, 7) # 7 is not a valid digit + + with pytest.raises(H3DigitDomainError): + h3.construct_cell(121, 45) # 45 is not a valid digit + + with pytest.raises(H3DigitDomainError): + h3.construct_cell(121, -1) # -1 is not a valid digit + + with pytest.raises(H3BaseCellDomainError): + h3.construct_cell(122) # one past last base cell number + + with pytest.raises(H3DeletedDigitError): + # 4 is a pentagon base cell. first nonzero digit can't be a 1 + h3.construct_cell(4, 1) + + with pytest.raises(H3DeletedDigitError): + # 4 is a pentagon base cell. first nonzero digit can't be a 1 + h3.construct_cell(4, 0,0,0, 0, 1) + + +def test_deconstruct_cell(): + h = '822377fffffffff' + assert h3.deconstruct_cell(h) == [17, 5, 6] + + +def test_construct_cell_inverses(): + # demonstrate functions are inverses of each other + + h = '8ff3ac688d63446' + components = [121, 6, 5, 4, 3, 2, 1, 0, 6, 5, 4, 3, 2, 1, 0, 6] + + assert h3.construct_cell(*components) == h + assert h3.deconstruct_cell(h) == components + + assert h3.construct_cell(*h3.deconstruct_cell(h)) == h + assert h3.deconstruct_cell(h3.construct_cell(*components)) == components + + +def test_construct_cell_inverses_int_api(): + # same inverse test as above, but in int api + import h3.api.basic_int as h3 + + h = 0x8ff3ac688d63446 + components = [121, 6, 5, 4, 3, 2, 1, 0, 6, 5, 4, 3, 2, 1, 0, 6] + + assert h3.construct_cell(*components) == h + assert h3.deconstruct_cell(h) == components + + assert h3.construct_cell(*h3.deconstruct_cell(h)) == h + assert h3.deconstruct_cell(h3.construct_cell(*components)) == components + + +def test_center_child_with_deconstruct(): + for h in h3.get_res0_cells(): + h3.construct_cell(*h3.deconstruct_cell(h), 0) == h3.cell_to_center_child(h) diff --git a/tests/test_lib/test_error_codes.py b/tests/test_lib/test_error_codes.py index 9961178..4ae1d37 100644 --- a/tests/test_lib/test_error_codes.py +++ b/tests/test_lib/test_error_codes.py @@ -1,6 +1,10 @@ import pytest import h3 +from h3._cy import ( + error_code_to_exception, + get_H3_ERROR_END, +) # todo: maybe check the `check_for_error` function behavior directly? @@ -12,24 +16,30 @@ h3_exceptions = { h3.H3GridNavigationError: None, h3.H3MemoryError: None, h3.H3ValueError: None, - - h3.H3FailedError: 1, - h3.H3DomainError: 2, - h3.H3LatLngDomainError: 3, - h3.H3ResDomainError: 4, - h3.H3CellInvalidError: 5, - h3.H3DirEdgeInvalidError: 6, - h3.H3UndirEdgeInvalidError: 7, - h3.H3VertexInvalidError: 8, - h3.H3PentagonError: 9, - h3.H3DuplicateInputError: 10, - h3.H3NotNeighborsError: 11, - h3.H3ResMismatchError: 12, - h3.H3MemoryAllocError: 13, - h3.H3MemoryBoundsError: 14, - h3.H3OptionInvalidError: 15, } +for e in range(1, get_H3_ERROR_END()): + ex = error_code_to_exception(e) + h3_exceptions[ex] = e + + +def test_num_error_codes(): + assert get_H3_ERROR_END() >= 20 + assert error_code_to_exception(19) == h3.H3DeletedDigitError + + # H3_ERROR_END (and beyond) shouldn't be a valid error code + code = get_H3_ERROR_END() + assert isinstance( + error_code_to_exception(code), + h3.UnknownH3ErrorCode + ) + + code = get_H3_ERROR_END() + 1 + assert isinstance( + error_code_to_exception(code), + h3.UnknownH3ErrorCode + ) + def test_error_codes_match(): """ From 73cd306f074a92dd5a0097f7f3347aed4bda198b Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Fri, 12 Dec 2025 13:10:22 -0800 Subject: [PATCH 134/177] Prep for release of v4.4.0 (#471) --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5349789..672478a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,8 @@ avoid adding features or APIs which do not map onto the ## Unreleased +## [4.4.0] - 2025-12-12 + - Update `h3lib` to v4.4.1. (#470) - Add new error codes: - `H3IndexInvalidError` From 9f52d7445818f819a22351fa013ebd596ffdc32d Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Sun, 14 Dec 2025 14:17:09 -0800 Subject: [PATCH 135/177] attempt to fix docs publishing (#472) --- .github/workflows/build_docs.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index f8301d1..23b884f 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -6,6 +6,9 @@ on: pull_request: branches: ['*'] +permissions: + contents: write + jobs: build-docs: runs-on: ubuntu-22.04 From b70122a20e42e90d0e2c257247010f562d0b6cfa Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Mon, 15 Dec 2025 10:44:10 -0800 Subject: [PATCH 136/177] Update version badge for h3 to v4.4.1 (#473) --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 1a82d89..843324e 100644 --- a/readme.md +++ b/readme.md @@ -5,7 +5,7 @@ [![PyPI version](https://badge.fury.io/py/h3.svg)](https://badge.fury.io/py/h3) [![PyPI downloads](https://img.shields.io/pypi/dm/h3.svg)](https://pypistats.org/packages/h3) [![conda](https://img.shields.io/conda/vn/conda-forge/h3-py.svg)](https://anaconda.org/conda-forge/h3-py) -[![version](https://img.shields.io/badge/h3-v4.3.0-blue.svg)](https://github.com/uber/h3/releases/tag/v4.3.0) +[![version](https://img.shields.io/badge/h3-v4.4.1-blue.svg)](https://github.com/uber/h3/releases/tag/v4.4.1) [![version](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/uber/h3-py/blob/master/LICENSE) [![Tests](https://github.com/uber/h3-py/workflows/tests/badge.svg)](https://github.com/uber/h3-py/actions) From 7d6d37945dfbd5ece3cfe7733f2dc4120f43611b Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Mon, 15 Dec 2025 10:56:09 -0800 Subject: [PATCH 137/177] Avoid building duplicate wheels (#474) * avoid building duplicate wheels * add additional CI twine check * add back macos-14 (should fail) * remove macos-14 (should pass) --- .github/workflows/wheels.yml | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index cde27d7..0f685c3 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -60,9 +60,6 @@ jobs: strategy: matrix: include: - - os: macos-14 - build: 'cp*-macosx_arm64' - name: macOS14 - os: macos-15 build: 'cp*-macosx_arm64' name: macOS15 @@ -192,8 +189,22 @@ jobs: retention-days: 7 compression-level: 9 - to_pypi: + check_merged: needs: [merge] + runs-on: ubuntu-latest + steps: + - name: Download merged artifacts + uses: actions/download-artifact@v6.0.0 + with: + name: wheels_and_sdist + path: dist + + - name: Check all wheels and sdist with Twine + run: | + pipx run twine check dist/* + + to_pypi: + needs: [check_merged] if: github.event_name == 'release' && github.event.action == 'published' runs-on: ubuntu-latest From 486f6efd39fe50715715bd450a7f532204d80b97 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Mon, 15 Dec 2025 13:44:12 -0800 Subject: [PATCH 138/177] Prep for v4.4.1 release (#475) --- CHANGELOG.md | 6 +++++- pyproject.toml | 2 +- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 672478a..b6dece2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,11 @@ avoid adding features or APIs which do not map onto the ## Unreleased -## [4.4.0] - 2025-12-12 +## [4.4.1] - 2025-12-15 + +- Fix PyPI publishing issue (#474) + +## [4.4.0] - 2025-12-12 (never published on PyPI) - Update `h3lib` to v4.4.1. (#470) - Add new error codes: diff --git a/pyproject.toml b/pyproject.toml index 4a5e319..bfe0bda 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.4.0' +version = '4.4.1' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} From 44dd11fd10da06ae6445ad8f55317cd7382662ad Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 29 Jan 2026 09:35:34 -0800 Subject: [PATCH 139/177] check for error from cellsToLinkedMultiPolygon; add test (#477) --- src/h3/_cy/to_multipoly.pyx | 5 +- tests/test_lib/polyfill/test_to_multipoly.py | 56 +++++++++++++++++++- 2 files changed, 59 insertions(+), 2 deletions(-) diff --git a/src/h3/_cy/to_multipoly.pyx b/src/h3/_cy/to_multipoly.pyx index db29baa..d24e2c3 100644 --- a/src/h3/_cy/to_multipoly.pyx +++ b/src/h3/_cy/to_multipoly.pyx @@ -1,6 +1,7 @@ cimport h3lib from h3lib cimport H3int from .util cimport check_cell, coord2deg +from .error_system cimport check_for_error # todo: it's driving me crazy that these three functions are all essentially the same linked list walker... @@ -39,7 +40,9 @@ def _to_multi_polygon(const H3int[:] cells): for h in cells: check_cell(h) - h3lib.cellsToLinkedMultiPolygon(&cells[0], len(cells), &polygon) + check_for_error( + h3lib.cellsToLinkedMultiPolygon(&cells[0], len(cells), &polygon) + ) out = walk_polys(&polygon) diff --git a/tests/test_lib/polyfill/test_to_multipoly.py b/tests/test_lib/polyfill/test_to_multipoly.py index 61f77f6..311c8ca 100644 --- a/tests/test_lib/polyfill/test_to_multipoly.py +++ b/tests/test_lib/polyfill/test_to_multipoly.py @@ -1,5 +1,7 @@ -import h3 +import pytest +import h3 +from h3._cy.error_system import H3FailedError from .. import util as u @@ -47,3 +49,55 @@ def test_2_polys(): cells ) assert set(map(len, out)) == {1, 12} + + +def test_cells_to_h3shape_transmeridian_error(): + """ + Test for https://github.com/uber/h3-py/issues/476 + + Cells along the equator and meridian trigger an error in the C library's + normalizeMultiPolygon. Previously this caused a segfault because the error + code wasn't checked. Now it should raise H3FailedError. + """ + cells = [ + '81007ffffffffff', '81017ffffffffff', '81033ffffffffff', + '81047ffffffffff', '81057ffffffffff', '81093ffffffffff', + '81097ffffffffff', '8109bffffffffff', '810cbffffffffff', + '810dbffffffffff', '81167ffffffffff', '81177ffffffffff', + '81187ffffffffff', '81197ffffffffff', '81227ffffffffff', + '8132bffffffffff', '8133bffffffffff', '81383ffffffffff', + '8138bffffffffff', '81397ffffffffff', '8147bffffffffff', + '8158bffffffffff', '81593ffffffffff', '8159bffffffffff', + '815abffffffffff', '815bbffffffffff', '815f3ffffffffff', + '81617ffffffffff', '81657ffffffffff', '8166fffffffffff', + '8168bffffffffff', '8168fffffffffff', '816abffffffffff', + '816afffffffffff', '816c7ffffffffff', '816cfffffffffff', + '816f3ffffffffff', '816f7ffffffffff', '816fbffffffffff', + '81707ffffffffff', '8170bffffffffff', '8170fffffffffff', + '8171bffffffffff', '8172bffffffffff', '8172fffffffffff', + '8173bffffffffff', '81743ffffffffff', '8174bffffffffff', + '81753ffffffffff', '81757ffffffffff', '81763ffffffffff', + '81767ffffffffff', '8177bffffffffff', '81783ffffffffff', + '81787ffffffffff', '8179bffffffffff', '817a3ffffffffff', + '817a7ffffffffff', '817bbffffffffff', '817c3ffffffffff', + '817c7ffffffffff', '817cbffffffffff', '817e3ffffffffff', + '817ebffffffffff', '817efffffffffff', '817f7ffffffffff', + '817fbffffffffff', '81807ffffffffff', '8180bffffffffff', + '8180fffffffffff', '81827ffffffffff', '8182bffffffffff', + '8182fffffffffff', '81853ffffffffff', '81857ffffffffff', + '8186bffffffffff', '8186fffffffffff', '8188bffffffffff', + '8188fffffffffff', '818a7ffffffffff', '818afffffffffff', + '818cbffffffffff', '818cfffffffffff', '818f3ffffffffff', + '81933ffffffffff', '81987ffffffffff', '81997ffffffffff', + '819a7ffffffffff', '819b7ffffffffff', '81ac7ffffffffff', + '81ba3ffffffffff', '81bafffffffffff', '81bb3ffffffffff', + '81c07ffffffffff', '81c17ffffffffff', '81d0bffffffffff', + '81d1bffffffffff', '81db3ffffffffff', '81dbbffffffffff', + '81dcbffffffffff', '81ddbffffffffff', '81e67ffffffffff', + '81eabffffffffff', '81eafffffffffff', '81ed7ffffffffff', + '81eebffffffffff', '81efbffffffffff', '81f17ffffffffff', + '81f2bffffffffff', '81f33ffffffffff', '81f3bffffffffff', + ] + + with pytest.raises(H3FailedError): + h3.cells_to_h3shape(cells) From 26084144a264b978c1a7a0cfe6e9d261e58d4da3 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 29 Jan 2026 10:20:16 -0800 Subject: [PATCH 140/177] prep for v4.4.2 release (#478) --- CHANGELOG.md | 4 ++++ pyproject.toml | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b6dece2..662c3fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,10 @@ avoid adding features or APIs which do not map onto the ## Unreleased +## [4.4.2] - 2026-01-29 + +- Check for error from `cellsToLinkedMultiPolygon` (#477) + ## [4.4.1] - 2025-12-15 - Fix PyPI publishing issue (#474) diff --git a/pyproject.toml b/pyproject.toml index bfe0bda..ad6d0a0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.4.1' +version = '4.4.2' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} From 3355f53aa6d213fe4c7f38e62765f5b86815932e Mon Sep 17 00:00:00 2001 From: Salman Chishti Date: Wed, 11 Feb 2026 20:51:02 +0000 Subject: [PATCH 141/177] Upgrade GitHub Actions for Node 24 compatibility (#479) Signed-off-by: Salman Muin Kayser Chishti <13schishti@gmail.com> --- .github/workflows/build_docs.yml | 6 +++--- .github/workflows/lint_and_coverage.yml | 4 ++-- .github/workflows/tests.yml | 4 ++-- .github/workflows/wheels.yml | 14 +++++++------- 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index 23b884f..ae8140e 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -14,11 +14,11 @@ jobs: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v5.0.0 + - uses: actions/checkout@v6.0.2 with: submodules: recursive - - uses: actions/setup-python@v6.0.0 + - uses: actions/setup-python@v6.2.0 with: python-version: 3.11 @@ -31,7 +31,7 @@ jobs: run: jupyter-book build docs/ --warningiserror --keep-going --all - name: Upload artifacts - uses: actions/upload-artifact@v5.0.0 + uses: actions/upload-artifact@v6.0.0 with: name: html path: docs/_build/html diff --git a/.github/workflows/lint_and_coverage.yml b/.github/workflows/lint_and_coverage.yml index d9789c7..b10b1de 100644 --- a/.github/workflows/lint_and_coverage.yml +++ b/.github/workflows/lint_and_coverage.yml @@ -12,11 +12,11 @@ jobs: runs-on: ubuntu-24.04 steps: - - uses: actions/checkout@v5.0.0 + - uses: actions/checkout@v6.0.2 with: submodules: recursive - - uses: actions/setup-python@v6.0.0 + - uses: actions/setup-python@v6.2.0 with: python-version: 3.11 diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index a82ec98..8b79555 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -17,11 +17,11 @@ jobs: python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14'] steps: - - uses: actions/checkout@v5.0.0 + - uses: actions/checkout@v6.0.2 with: submodules: recursive - - uses: actions/setup-python@v6.0.0 + - uses: actions/setup-python@v6.2.0 with: python-version: '${{ matrix.python-version }}' diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 0f685c3..7e7caed 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -23,12 +23,12 @@ jobs: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v5.0.0 + - uses: actions/checkout@v6.0.2 with: submodules: recursive - name: Setup Python - uses: actions/setup-python@v6.0.0 + uses: actions/setup-python@v6.2.0 with: python-version: 3.11 @@ -48,7 +48,7 @@ jobs: run: pytest - name: Upload artifacts to GitHub - uses: actions/upload-artifact@v5.0.0 + uses: actions/upload-artifact@v6.0.0 with: name: temp_result_sdist path: ./dist @@ -130,7 +130,7 @@ jobs: name: Linux Aarch64 3.14 steps: - - uses: actions/checkout@v5.0.0 + - uses: actions/checkout@v6.0.2 with: submodules: recursive @@ -171,7 +171,7 @@ jobs: pipx run twine check wheelhouse/* - name: Upload artifacts to GitHub - uses: actions/upload-artifact@v5.0.0 + uses: actions/upload-artifact@v6.0.0 with: name: temp_result_${{ matrix.os }}-${{ strategy.job-index }} path: wheelhouse/*.whl @@ -194,7 +194,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Download merged artifacts - uses: actions/download-artifact@v6.0.0 + uses: actions/download-artifact@v7.0.0 with: name: wheels_and_sdist path: dist @@ -209,7 +209,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/download-artifact@v6.0.0 + - uses: actions/download-artifact@v7.0.0 with: name: wheels_and_sdist path: dist From 4d0c33241bddd5415769d693c987a33f68b9af3b Mon Sep 17 00:00:00 2001 From: Salman Chishti Date: Sun, 15 Feb 2026 21:25:25 +0000 Subject: [PATCH 142/177] Upgrade GitHub Actions to latest versions (#480) Signed-off-by: Salman Muin Kayser Chishti <13schishti@gmail.com> --- .github/workflows/wheels.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 7e7caed..9f40ef7 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -155,11 +155,11 @@ jobs: - name: Set up QEMU if: runner.os == 'Linux' - uses: docker/setup-qemu-action@v3.6.0 + uses: docker/setup-qemu-action@v3.7.0 with: platforms: aarch64 - - uses: pypa/cibuildwheel@v3.2.1 + - uses: pypa/cibuildwheel@v3.3.1 env: CIBW_TEST_REQUIRES: pytest pytest-cov numpy CIBW_TEST_COMMAND: pytest {project}/tests @@ -181,7 +181,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Merge Artifacts - uses: actions/upload-artifact/merge@v5.0.0 + uses: actions/upload-artifact/merge@v6 with: name: wheels_and_sdist pattern: temp_result_* From 9a7d6dfd6f2813e1d448151dbb7e25def752f018 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 26 Feb 2026 14:12:54 -0800 Subject: [PATCH 143/177] v4.5a (alpha version) (#483) * bump h3lib to unreleased a9c0a2e (cellsToMultiPolygon) * initial changes * move around dependencies * update CI * ci separation * h3.pc.in * clean up .gitignore * changelog * better changelog * add cellsToMultiPolygon to h3-py in separate release * sdist exclude and coverage for version test * warn that changing some justfile rules will affect CI * try to silence some CI warnings * one more warning --- .github/workflows/build_docs.yml | 11 ++-- .github/workflows/lint_and_coverage.yml | 24 ++++--- .github/workflows/tests.yml | 20 +++--- .github/workflows/wheels.yml | 48 ++++++-------- .gitignore | 86 ++++++++++--------------- CHANGELOG.md | 7 ++ dev_notes.md | 15 ++++- justfile | 61 ++++++++++++++++++ makefile | 52 --------------- pyproject.toml | 24 ++++--- src/h3lib | 2 +- tests/test_lib/test_cells_and_edges.py | 8 ++- 12 files changed, 183 insertions(+), 175 deletions(-) create mode 100644 justfile delete mode 100644 makefile diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index ae8140e..9cc00a2 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -18,17 +18,14 @@ jobs: with: submodules: recursive - - uses: actions/setup-python@v6.2.0 + - uses: astral-sh/setup-uv@v7 with: - python-version: 3.11 + python-version: '3.11' - - name: Install dependencies - run: | - pip install --upgrade pip setuptools wheel - pip install .[all] + - uses: extractions/setup-just@v2 - name: Build the book - run: jupyter-book build docs/ --warningiserror --keep-going --all + run: just docs - name: Upload artifacts uses: actions/upload-artifact@v6.0.0 diff --git a/.github/workflows/lint_and_coverage.yml b/.github/workflows/lint_and_coverage.yml index b10b1de..c0eb154 100644 --- a/.github/workflows/lint_and_coverage.yml +++ b/.github/workflows/lint_and_coverage.yml @@ -16,22 +16,20 @@ jobs: with: submodules: recursive - - uses: actions/setup-python@v6.2.0 + - uses: astral-sh/setup-uv@v7 with: - python-version: 3.11 + python-version: '3.11' - - name: Install from source - run: pip install .[test] + - uses: extractions/setup-just@v2 - - name: Run Linting - uses: astral-sh/ruff-action@v3 + - name: Lint + run: just lint - - name: Coverage Requirement - Library - run: | - pytest tests/test_lib --cov=h3 --cov=tests/test_lib --cov-fail-under=100 + - name: Install + run: uv sync + + - name: Coverage - Library + run: just ci-test - name: Coverage - Cython - run: | - pip install cython - cythonize tests/test_cython/cython_example.pyx - pytest tests/test_cython --cov=tests/test_cython + run: just ci-test-cython diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 8b79555..7920a84 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -14,17 +14,19 @@ jobs: strategy: matrix: os: [macos-latest, windows-latest, ubuntu-22.04] - python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14'] + python-version: ['3.10', '3.11', '3.12', '3.13', '3.14'] steps: - uses: actions/checkout@v6.0.2 with: submodules: recursive - - uses: actions/setup-python@v6.2.0 + - uses: astral-sh/setup-uv@v7 with: python-version: '${{ matrix.python-version }}' + - uses: extractions/setup-just@v2 + ## Start Windows stuff - uses: ilammy/msvc-dev-cmd@v1.13.0 if: startsWith(matrix.os, 'windows') @@ -36,13 +38,11 @@ jobs: echo "CXX=cl.exe" >> $GITHUB_ENV ## End Windows stuff - - name: Install from source - run: | - pip install --upgrade pip setuptools wheel - pip install .[test] + - name: Install + run: uv sync - name: Tests - run: | - pip install cython - cythonize tests/test_cython/cython_example.pyx - pytest + run: just ci-test + + - name: Cython Tests + run: just ci-test-cython diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 9f40ef7..dbc8d6d 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -27,25 +27,25 @@ jobs: with: submodules: recursive - - name: Setup Python - uses: actions/setup-python@v6.2.0 + - uses: astral-sh/setup-uv@v7 with: - python-version: 3.11 + python-version: '3.11' + - name: Make sdist - run: | - python --version - pipx --version - pipx run build --sdist + run: uv build --sdist + # Test the sdist, NOT the local checkout. + # Use a fresh venv + uv pip install (not uv sync, which would build from source). - name: Install from sdist run: | - pip install --upgrade pip setuptools wheel + uv venv cp dist/h3-*.tar.gz h3.tar.gz - pip install h3.tar.gz[test] + uv pip install h3.tar.gz[numpy] pytest pytest-cov - name: Test sdist - run: pytest + # run pytest directly from the venv to avoid `uv run` syncing from the local checkout + run: .venv/bin/pytest - name: Upload artifacts to GitHub uses: actions/upload-artifact@v6.0.0 @@ -85,12 +85,6 @@ jobs: build: 'cp*-manylinux_x86_64' name: Linux Intel glibc 64-bit - - os: ubuntu-22.04 - build: 'cp38-musllinux_x86_64' - name: Linux Intel musl 64-bit 3.8 - - os: ubuntu-22.04 - build: 'cp39-musllinux_x86_64' - name: Linux Intel musl 64-bit 3.9 - os: ubuntu-22.04 build: 'cp310-musllinux_x86_64' name: Linux Intel musl 64-bit 3.10 @@ -107,12 +101,6 @@ jobs: build: 'cp314-musllinux_x86_64' name: Linux Intel musl 64-bit 3.14 - - os: ubuntu-22.04 - build: 'cp38-manylinux_aarch64' - name: Linux Aarch64 3.8 - - os: ubuntu-22.04 - build: 'cp39-manylinux_aarch64' - name: Linux Aarch64 3.9 - os: ubuntu-22.04 build: 'cp310-manylinux_aarch64' name: Linux Aarch64 3.10 @@ -134,7 +122,9 @@ jobs: with: submodules: recursive - - name: Set MSVC for Windows-x64 + - uses: astral-sh/setup-uv@v7 + + - name: Set MSVC for Windows-x64 uses: microsoft/setup-msbuild@v2 if: matrix.os == 'windows-latest' with: @@ -161,14 +151,14 @@ jobs: - uses: pypa/cibuildwheel@v3.3.1 env: + CIBW_BUILD_FRONTEND: 'build[uv]' CIBW_TEST_REQUIRES: pytest pytest-cov numpy CIBW_TEST_COMMAND: pytest {project}/tests CIBW_ARCHS_LINUX: auto aarch64 CIBW_BUILD: ${{ matrix.build }} - name: Check with Twine - run: | - pipx run twine check wheelhouse/* + run: uvx twine check wheelhouse/* - name: Upload artifacts to GitHub uses: actions/upload-artifact@v6.0.0 @@ -193,6 +183,11 @@ jobs: needs: [merge] runs-on: ubuntu-latest steps: + - uses: astral-sh/setup-uv@v7 + with: + enable-cache: false + ignore-empty-workdir: true + - name: Download merged artifacts uses: actions/download-artifact@v7.0.0 with: @@ -200,8 +195,7 @@ jobs: path: dist - name: Check all wheels and sdist with Twine - run: | - pipx run twine check dist/* + run: uvx twine check dist/* to_pypi: needs: [check_merged] diff --git a/.gitignore b/.gitignore index cf6fcf3..1141de9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,75 +1,57 @@ -h3c/ +# Byte-compiled / optimized *.py[cod] -.cache/ -h3/out/ -.ruff_cache/ -_build/ +__pycache__/ + +# C extensions +*.so # Generated C code from Cython test tests/**/*.c # Cython HTML annotations *.html -# C extensions -*.so - -# Packages -*.egg +# Build artifacts +build/ +dist/ *.egg-info -dist -build -eggs -parts -bin -var -sdist -develop-eggs -.installed.cfg -# Installer logs -pip-log.txt - -# Unit test / coverage reports +# Coverage .coverage coverage.xml coverage.lcov -.tox -nosetests.xml -.noseids -.pytest_cache - -# Mr Developer -.mr.developer.cfg -.project -.pydevproject - -*.csv -build/ -env/ -env_docs/ -docs/_build/ htmlcov/ -# vim/emacs backup files +# Test +.pytest_cache/ + +# Tools +.ruff_cache/ +.cache/ + +# Docs +_build/ +docs/_build/ + +# Environment +.venv/ +uv.lock + +# OS +.DS_Store + +# Editor backup files *~ \#*\# .\#* .*.sw* -#DB snapshots -db_snapshots/ - -#OSX -.DS_Store - -node_modules/ -bower_components/ -.sass-cache/ +# IDE .idea/ -.unison.* +# IPython / Jupyter .ipynb_checkpoints/ -_skbuild/ -# might want to remove this later when distributing -MANIFEST +# Legacy build dirs +_skbuild/ +h3c/ +h3/out/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 662c3fc..b71f774 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,13 @@ avoid adding features or APIs which do not map onto the ## Unreleased +## [4.5.0a1] - 2026-02-25 + +- Update `h3lib` with draft v4.5 changes +- Drop Python 3.8 and 3.9 (EOL); minimum is now Python 3.10 +- Document Python 3.14 support +- Migrate build tooling from Makefile/pip to justfile/uv, including CI + ## [4.4.2] - 2026-01-29 - Check for error from `cellsToLinkedMultiPolygon` (#477) diff --git a/dev_notes.md b/dev_notes.md index 300ee42..d8635b0 100644 --- a/dev_notes.md +++ b/dev_notes.md @@ -2,11 +2,20 @@ ## Install for development +This repo uses [`just`](https://github.com/casey/just) for running common development commands. + +To get started: + - `git clone git@github.com:uber/h3-py.git` - `cd h3-py` -- `make init` -- `make test` -- `make lint` +- `just lint` +- `just test` +- `just test-cython` + +To build and view docs: + +- `just docs` +- `just view` ## Docstrings diff --git a/justfile b/justfile new file mode 100644 index 0000000..d8e44fb --- /dev/null +++ b/justfile @@ -0,0 +1,61 @@ +# disable editable installs so uv sync does a full build of the C extension +export UV_NO_EDITABLE := "1" + +_: + just --list + +# force-rebuild the C extension to avoid stale builds +reinstall: + uv cache clean h3 + uv sync --reinstall-package h3 + +# locally, always reinstall before testing +test: reinstall ci-test +test-cython: reinstall ci-test-cython + +fix: + uvx ruff check --fix + +lab: + uv sync --group docs + uv run jupyter lab + +view: + open docs/_build/html/index.html + +purge: + just _rm .venv + just _rm '*.pytest_cache' + just _rm .DS_Store + just _rm '*.egg-info' + just _rm dist + just _rm '*.ipynb_checkpoints' + just _rm __pycache__ + just _rm uv.lock + just _rm .coverage + just _rm build + just _rm _build + just _rm _skbuild + just _rm .ruff_cache + uv cache clean h3 + +_rm pattern: + -@find . -name "{{pattern}}" -prune -exec rm -rf {} + + + +# Recipes below are used by CI workflows (.github/workflows/). +# Changes here may break CI — update the workflows accordingly. + +ci-test: + uv run pytest tests/test_lib --cov=h3 --cov=tests/test_lib --cov-fail-under=100 + +ci-test-cython: + uv run --with cython --with setuptools cythonize tests/test_cython/cython_example.pyx + uv run pytest tests/test_cython --cov=tests/test_cython + +lint: + uvx ruff check + +docs: + uv sync --group docs + uv run jupyter-book build docs/ --warningiserror --keep-going --all diff --git a/makefile b/makefile deleted file mode 100644 index df39c8f..0000000 --- a/makefile +++ /dev/null @@ -1,52 +0,0 @@ -.PHONY: init clear rebuild purge test lint lab ipython - -PYTHON=$(shell command -v python || command -v python3) - - -build-docs: - ./env/bin/pip install .[all] - ./env/bin/jupyter-book build docs/ --warningiserror --keep-going --all - -open: - open docs/_build/html/index.html - -init: purge - git submodule update --init - $(PYTHON) -m venv env - ./env/bin/pip install --upgrade pip wheel setuptools - ./env/bin/pip install .[test] - -clear: - -./env/bin/pip uninstall -y h3 - -@rm -rf MANIFEST - -@rm -rf .pytest_cache _skbuild dist .coverage build docs/_build .ruff_cache - -@find . -type d -name '__pycache__' | xargs rm -r - -@find . -type d -name '*.egg-info' | xargs rm -r - -@find . -type f -name '*.pyc' | xargs rm -r - -@find . -type f -name '*.so' | xargs rm -r - -@find . -type d -name '*.ipynb_checkpoints' | xargs rm -r - -@find ./tests -type f -name '*.c' | xargs rm -r - -@find ./tests -type f -name '*.html' | xargs rm -r - -rebuild: clear - ./env/bin/pip install .[test] - -purge: clear - -@rm -rf env - -test: - ./env/bin/pytest tests/test_lib --cov=h3 --cov=tests/test_lib --cov-fail-under=100 - - ./env/bin/pip install cython - ./env/bin/cythonize tests/test_cython/cython_example.pyx - ./env/bin/pytest tests/test_cython --cov=tests/test_cython - -lint: - ./env/bin/ruff check - -fix: - ./env/bin/ruff check --fix - -lab: - ./env/bin/pip install .[all] - ./env/bin/jupyter lab diff --git a/pyproject.toml b/pyproject.toml index ad6d0a0..3c9effe 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.4.2' +version = '4.5.0a1' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} @@ -14,7 +14,7 @@ authors = [ maintainers = [ { name = 'AJ Friend', email = 'ajfriend@gmail.com' }, ] -requires-python = '>=3.8' +requires-python = '>=3.10' dependencies = [] @@ -25,12 +25,11 @@ classifiers = [ 'License :: OSI Approved :: Apache Software License', 'Programming Language :: C', 'Programming Language :: Cython', - 'Programming Language :: Python :: 3.8', - 'Programming Language :: Python :: 3.9', 'Programming Language :: Python :: 3.10', 'Programming Language :: Python :: 3.11', 'Programming Language :: Python :: 3.12', 'Programming Language :: Python :: 3.13', + 'Programming Language :: Python :: 3.14', 'Operating System :: MacOS :: MacOS X', 'Operating System :: POSIX :: Linux', 'Operating System :: Microsoft :: Windows', @@ -47,9 +46,11 @@ Changelog = 'https://uber.github.io/h3-py/_changelog.html' [project.optional-dependencies] numpy = ['numpy'] -test = ['pytest', 'pytest-cov', 'ruff', 'numpy'] -all = [ - 'h3[test]', + +[dependency-groups] +dev = ['pytest', 'pytest-cov', 'numpy'] +docs = [ + 'numpy', 'jupyter-book<2', 'sphinx>=7.3.3', # https://github.com/sphinx-doc/sphinx/issues/12290 'jupyterlab', @@ -73,18 +74,25 @@ omit = [ ] +[tool.uv] +default-groups = ['dev'] + [tool.scikit-build] sdist.exclude = [ 'src/h3lib', 'docs', 'dev_notes.md', - 'makefile', + 'justfile', + '.github', + '.gitignore', + '.gitmodules', ] sdist.include = [ 'src/h3lib/LICENSE', 'src/h3lib/README.md', 'src/h3lib/VERSION', 'src/h3lib/CMakeLists.txt', + 'src/h3lib/h3.pc.in', 'src/h3lib/cmake/*', 'src/h3lib/src/h3lib/*' ] diff --git a/src/h3lib b/src/h3lib index 70d4c9e..a9c0a2e 160000 --- a/src/h3lib +++ b/src/h3lib @@ -1 +1 @@ -Subproject commit 70d4c9e5007d74d77714afa44d5a2e52606828bf +Subproject commit a9c0a2ec7869fa01772dcebdf930590469910600 diff --git a/tests/test_lib/test_cells_and_edges.py b/tests/test_lib/test_cells_and_edges.py index c461582..4b8e107 100644 --- a/tests/test_lib/test_cells_and_edges.py +++ b/tests/test_lib/test_cells_and_edges.py @@ -456,8 +456,12 @@ def test_versions(): v_c = Version(v['c']) v_p = Version(v['python']) - # of X.Y.Z, X and Y must match - assert v_c.release[:2] == v_p.release[:2] + # For all releases (including pre-release), major version must match + assert v_c.release[0] == v_p.release[0] + + if not v_p.is_prerelease: # pragma: no cover + # of X.Y.Z, X and Y must match + assert v_c.release[:2] == v_p.release[:2] def test_str_int_convert(): From adba976e22a65a5b1ae29eabe8782ff5922f843b Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Fri, 27 Feb 2026 19:28:16 -0800 Subject: [PATCH 144/177] v4.5.0a2 (#484) * first pass * helper * better tests * changelog * better comments * be robust against os-specific floating point behavior --- CHANGELOG.md | 8 + pyproject.toml | 2 +- src/h3/_cy/h3lib.pxd | 25 +- src/h3/_cy/to_multipoly.pyx | 70 ++-- tests/test_lib/polyfill/test_to_multipoly.py | 349 ++++++++++++++++--- 5 files changed, 343 insertions(+), 111 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b71f774..64fe3e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,14 @@ avoid adding features or APIs which do not map onto the ## Unreleased +## [4.5.0a2] - 2026-02-27 + +- `cells_to_h3shape`/`cells_to_geo` now handle all valid cell sets, including + sets that would produce global polygons crossing the antimeridian, poles, or are larger than a hemisphere + - Duplicate cells now raise `H3DuplicateInputError` + - Mixed-resolution cells now raise `H3ResMismatchError` + - Internal: switch from linked-list to array-based C API for cells-to-polygon conversion + ## [4.5.0a1] - 2026-02-25 - Update `h3lib` with draft v4.5 changes diff --git a/pyproject.toml b/pyproject.toml index 3c9effe..1da4918 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.5.0a1' +version = '4.5.0a2' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index 8cf74a7..7dfa0c5 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -47,21 +47,6 @@ cdef extern from 'h3api.h': int i int j - ctypedef struct LinkedLatLng: - LatLng data 'vertex' - LinkedLatLng *next - - # renaming these for clarity - ctypedef struct LinkedGeoLoop: - LinkedLatLng *data 'first' - LinkedLatLng *_data_last 'last' # not needed in Cython bindings - LinkedGeoLoop *next - - ctypedef struct LinkedGeoPolygon: - LinkedGeoLoop *data 'first' - LinkedGeoLoop *_data_last 'last' # not needed in Cython bindings - LinkedGeoPolygon *next - ctypedef struct GeoLoop: int numVerts LatLng *verts @@ -171,8 +156,8 @@ cdef extern from 'h3api.h': double greatCircleDistanceKm(const LatLng *a, const LatLng *b) nogil double greatCircleDistanceM(const LatLng *a, const LatLng *b) nogil - H3Error cellsToLinkedMultiPolygon(const H3int *h3Set, const int numCells, LinkedGeoPolygon *out) - void destroyLinkedMultiPolygon(LinkedGeoPolygon *polygon) + H3Error cellsToMultiPolygon(const H3int *cells, const int64_t numCells, GeoMultiPolygon *out) + void destroyGeoMultiPolygon(GeoMultiPolygon *mpoly) H3Error maxPolygonToCellsSize(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t *count) H3Error polygonToCells(const GeoPolygon *geoPolygon, int res, uint32_t flags, H3int *out) @@ -180,9 +165,9 @@ cdef extern from 'h3api.h': H3Error maxPolygonToCellsSizeExperimental(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t *count) H3Error polygonToCellsExperimental(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t sz, H3int *out) - # ctypedef struct GeoMultiPolygon: - # int numPolygons - # GeoPolygon *polygons + ctypedef struct GeoMultiPolygon: + int numPolygons + GeoPolygon *polygons # int hexRange(H3int origin, int k, H3int *out) diff --git a/src/h3/_cy/to_multipoly.pyx b/src/h3/_cy/to_multipoly.pyx index d24e2c3..ed3e763 100644 --- a/src/h3/_cy/to_multipoly.pyx +++ b/src/h3/_cy/to_multipoly.pyx @@ -4,60 +4,42 @@ from .util cimport check_cell, coord2deg from .error_system cimport check_for_error -# todo: it's driving me crazy that these three functions are all essentially the same linked list walker... -# grumble: no way to do iterators in with cdef functions! -cdef walk_polys(const h3lib.LinkedGeoPolygon* L): - out = [] - while L: - out += [walk_loops(L.data)] - L = L.next - - return out +cdef _loop_to_list(const h3lib.GeoLoop *loop): + return [coord2deg(loop.verts[v]) for v in range(loop.numVerts)] -cdef walk_loops(const h3lib.LinkedGeoLoop* L): - out = [] - while L: - out += [walk_coords(L.data)] - L = L.next - - return out - - -cdef walk_coords(const h3lib.LinkedLatLng* L): - out = [] - while L: - out += [coord2deg(L.data)] - L = L.next - - return out - -# todo: tuples instead of lists? -def _to_multi_polygon(const H3int[:] cells): - cdef: - h3lib.LinkedGeoPolygon polygon - - for h in cells: - check_cell(h) - - check_for_error( - h3lib.cellsToLinkedMultiPolygon(&cells[0], len(cells), &polygon) +cdef _poly_to_lists(const h3lib.GeoPolygon *poly): + return ( + [_loop_to_list(&poly.geoloop)] + + [_loop_to_list(&poly.holes[h]) for h in range(poly.numHoles)] ) - out = walk_polys(&polygon) - # we're still responsible for cleaning up the passed in `polygon`, - # but not a problem here, since it is stack allocated - h3lib.destroyLinkedMultiPolygon(&polygon) +def _to_multi_polygon(const H3int[:] cells): + cdef: + h3lib.GeoMultiPolygon mpoly + H3int cell + + for cell in cells: + check_cell(cell) + + check_for_error( + h3lib.cellsToMultiPolygon(&cells[0], len(cells), &mpoly) + ) + + try: + out = [ + _poly_to_lists(&mpoly.polygons[p]) + for p in range(mpoly.numPolygons) + ] + finally: + h3lib.destroyGeoMultiPolygon(&mpoly) return out def cells_to_multi_polygon(const H3int[:] cells): - # todo: gotta be a more elegant way to handle these... if len(cells) == 0: return [] - multipoly = _to_multi_polygon(cells) - - return multipoly + return _to_multi_polygon(cells) diff --git a/tests/test_lib/polyfill/test_to_multipoly.py b/tests/test_lib/polyfill/test_to_multipoly.py index 311c8ca..80c5a75 100644 --- a/tests/test_lib/polyfill/test_to_multipoly.py +++ b/tests/test_lib/polyfill/test_to_multipoly.py @@ -1,11 +1,21 @@ import pytest import h3 -from h3._cy.error_system import H3FailedError +from h3._cy.error_system import H3DuplicateInputError, H3ResMismatchError, H3FailedError from .. import util as u +def assert_cells_roundtrip(cells): + """Convert cells to multi-polygon and back, checking we recover the original set.""" + res = h3.get_resolution(cells[0]) + mpoly = h3.cells_to_h3shape(cells, tight=False) + + recovered = h3.h3shape_to_cells(mpoly, res) + + assert u.same_set(recovered, cells) + + def test_cells_to_h3shape(): h = '8928308280fffff' cells = h3.grid_disk(h, 1) @@ -51,53 +61,300 @@ def test_2_polys(): assert set(map(len, out)) == {1, 12} -def test_cells_to_h3shape_transmeridian_error(): - """ - Test for https://github.com/uber/h3-py/issues/476 +def test_empty(): + mpoly = h3.cells_to_h3shape([], tight=False) + assert isinstance(mpoly, h3.LatLngMultiPoly) + assert len(mpoly) == 0 - Cells along the equator and meridian trigger an error in the C library's - normalizeMultiPolygon. Previously this caused a segfault because the error - code wasn't checked. Now it should raise H3FailedError. - """ + mpoly = h3.cells_to_h3shape([], tight=True) + assert isinstance(mpoly, h3.LatLngMultiPoly) + assert len(mpoly) == 0 + + +def test_all_res0_cells(): + cells = h3.get_res0_cells() + mpoly = h3.cells_to_h3shape(cells, tight=False) + + # We should get an "entire globe" multipolygon back + # The current implementation returns 8 triangles + assert len(mpoly) == 8 + for poly in mpoly: + assert len(poly.outer) == 3 + assert len(poly.holes) == 0 + + # Roundtrip fails: h3shape_to_cells recovers only 69/122 cells. + # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons. + cells2 = h3.h3shape_to_cells(mpoly, 0) + assert len(cells2) == 69 + + +def test_pentagons(): + for res in range(16): + cells = h3.get_pentagons(res) + mpoly = h3.cells_to_h3shape(cells, tight=False) + + if res % 2 == 0: + expected_verts = 5 + else: + # pentagons have distortion vertices at odd resolutions + expected_verts = 10 + + assert len(mpoly) == 12 + for poly in mpoly: + assert len(poly.holes) == 0 + assert len(poly.outer) == expected_verts + + assert_cells_roundtrip(cells) + + +def test_duplicate_cells_error(): + cell = '8928308280fffff' + with pytest.raises(H3DuplicateInputError): + h3.cells_to_h3shape([cell, cell]) + + +def test_mixed_resolution_error(): + with pytest.raises(H3ResMismatchError): + h3.cells_to_h3shape(['8027fffffffffff', '81efbffffffffff']) + + +def test_three_polygons(): cells = [ - '81007ffffffffff', '81017ffffffffff', '81033ffffffffff', - '81047ffffffffff', '81057ffffffffff', '81093ffffffffff', - '81097ffffffffff', '8109bffffffffff', '810cbffffffffff', - '810dbffffffffff', '81167ffffffffff', '81177ffffffffff', - '81187ffffffffff', '81197ffffffffff', '81227ffffffffff', - '8132bffffffffff', '8133bffffffffff', '81383ffffffffff', - '8138bffffffffff', '81397ffffffffff', '8147bffffffffff', - '8158bffffffffff', '81593ffffffffff', '8159bffffffffff', - '815abffffffffff', '815bbffffffffff', '815f3ffffffffff', - '81617ffffffffff', '81657ffffffffff', '8166fffffffffff', - '8168bffffffffff', '8168fffffffffff', '816abffffffffff', - '816afffffffffff', '816c7ffffffffff', '816cfffffffffff', - '816f3ffffffffff', '816f7ffffffffff', '816fbffffffffff', - '81707ffffffffff', '8170bffffffffff', '8170fffffffffff', - '8171bffffffffff', '8172bffffffffff', '8172fffffffffff', - '8173bffffffffff', '81743ffffffffff', '8174bffffffffff', - '81753ffffffffff', '81757ffffffffff', '81763ffffffffff', - '81767ffffffffff', '8177bffffffffff', '81783ffffffffff', - '81787ffffffffff', '8179bffffffffff', '817a3ffffffffff', - '817a7ffffffffff', '817bbffffffffff', '817c3ffffffffff', - '817c7ffffffffff', '817cbffffffffff', '817e3ffffffffff', - '817ebffffffffff', '817efffffffffff', '817f7ffffffffff', - '817fbffffffffff', '81807ffffffffff', '8180bffffffffff', - '8180fffffffffff', '81827ffffffffff', '8182bffffffffff', - '8182fffffffffff', '81853ffffffffff', '81857ffffffffff', - '8186bffffffffff', '8186fffffffffff', '8188bffffffffff', - '8188fffffffffff', '818a7ffffffffff', '818afffffffffff', - '818cbffffffffff', '818cfffffffffff', '818f3ffffffffff', - '81933ffffffffff', '81987ffffffffff', '81997ffffffffff', - '819a7ffffffffff', '819b7ffffffffff', '81ac7ffffffffff', - '81ba3ffffffffff', '81bafffffffffff', '81bb3ffffffffff', - '81c07ffffffffff', '81c17ffffffffff', '81d0bffffffffff', - '81d1bffffffffff', '81db3ffffffffff', '81dbbffffffffff', - '81dcbffffffffff', '81ddbffffffffff', '81e67ffffffffff', - '81eabffffffffff', '81eafffffffffff', '81ed7ffffffffff', - '81eebffffffffff', '81efbffffffffff', '81f17ffffffffff', - '81f2bffffffffff', '81f33ffffffffff', '81f3bffffffffff', + '8027fffffffffff', '802bfffffffffff', '804dfffffffffff', + '8067fffffffffff', '806dfffffffffff', '8049fffffffffff', + '805ffffffffffff', '8057fffffffffff', '807dfffffffffff', + '80a5fffffffffff', '80a9fffffffffff', '808bfffffffffff', + '801bfffffffffff', '8035fffffffffff', '803ffffffffffff', + '8053fffffffffff', '8043fffffffffff', '8021fffffffffff', + '8011fffffffffff', '801ffffffffffff', '8097fffffffffff', ] + mpoly = h3.cells_to_h3shape(cells, tight=False) + + assert len(mpoly) == 3 + hole_counts = [len(p.holes) for p in mpoly] + + # Polygons are ordered by size, and we know the hole counts of each + assert hole_counts == [3, 1, 0] + + assert_cells_roundtrip(cells) + + +def test_issue_1049(): + cells = [ + '827487fffffffff', '82748ffffffffff', '827497fffffffff', + '82749ffffffffff', '8274affffffffff', '8274c7fffffffff', + '8274cffffffffff', '8274d7fffffffff', '8274e7fffffffff', + '8274effffffffff', '8274f7fffffffff', '82754ffffffffff', + '827c07fffffffff', '827c27fffffffff', '827c2ffffffffff', + '827c37fffffffff', '827d87fffffffff', '827d8ffffffffff', + '827d97fffffffff', '827d9ffffffffff', '827da7fffffffff', + '827daffffffffff', '82801ffffffffff', '8280a7fffffffff', + '8280affffffffff', '8280b7fffffffff', '828197fffffffff', + '82819ffffffffff', '8281a7fffffffff', '8281b7fffffffff', + '828207fffffffff', '82820ffffffffff', '828227fffffffff', + '82822ffffffffff', '8282e7fffffffff', '828307fffffffff', + '82830ffffffffff', '82831ffffffffff', '82832ffffffffff', + '828347fffffffff', '82834ffffffffff', '828357fffffffff', + '82835ffffffffff', '828367fffffffff', '828377fffffffff', + '82a447fffffffff', '82a457fffffffff', '82a45ffffffffff', + '82a467fffffffff', '82a46ffffffffff', '82a477fffffffff', + '82a4c7fffffffff', '82a4cffffffffff', '82a4d7fffffffff', + '82a4e7fffffffff', '82a4effffffffff', '82a4f7fffffffff', + '82a547fffffffff', '82a54ffffffffff', '82a557fffffffff', + '82a55ffffffffff', '82a567fffffffff', '82a577fffffffff', + '82a837fffffffff', '82a897fffffffff', '82a8a7fffffffff', + '82a8b7fffffffff', '82a917fffffffff', '82a927fffffffff', + '82a937fffffffff', '82a987fffffffff', '82a98ffffffffff', + '82a997fffffffff', '82a99ffffffffff', '82a9a7fffffffff', + '82a9affffffffff', '82ac47fffffffff', '82ac57fffffffff', + '82ac5ffffffffff', '82ac67fffffffff', '82ac6ffffffffff', + '82ac77fffffffff', '82ad47fffffffff', '82ad4ffffffffff', + '82ad57fffffffff', '82ad5ffffffffff', '82ad67fffffffff', + '82ad77fffffffff', '82c207fffffffff', '82c217fffffffff', + '82c227fffffffff', '82c237fffffffff', '82c287fffffffff', + '82c28ffffffffff', '82c29ffffffffff', '82c2a7fffffffff', + '82c2affffffffff', '82c2b7fffffffff', '82c307fffffffff', + '82c317fffffffff', '82c31ffffffffff', '82c337fffffffff', + '82cfb7fffffffff', '82d0c7fffffffff', '82d0d7fffffffff', + '82d0dffffffffff', '82d0e7fffffffff', '82d0f7fffffffff', + '82d147fffffffff', '82d157fffffffff', '82d15ffffffffff', + '82d167fffffffff', '82d177fffffffff', '82d187fffffffff', + '82d18ffffffffff', '82d197fffffffff', '82d19ffffffffff', + '82d1a7fffffffff', '82d1affffffffff', '82dc47fffffffff', + '82dc57fffffffff', '82dc5ffffffffff', '82dc67fffffffff', + '82dc6ffffffffff', '82dc77fffffffff', '82dcc7fffffffff', + '82dccffffffffff', '82dcd7fffffffff', '82dce7fffffffff', + '82dceffffffffff', '82dcf7fffffffff', '82dd1ffffffffff', + '82dd47fffffffff', '82dd4ffffffffff', '82dd57fffffffff', + '82dd5ffffffffff', '82dd6ffffffffff', '82dd87fffffffff', + '82dd8ffffffffff', '82dd97fffffffff', '82dd9ffffffffff', + '82ddaffffffffff', '82ddb7fffffffff', '82dec7fffffffff', + '82decffffffffff', '82ded7fffffffff', '82dee7fffffffff', + '82deeffffffffff', '82def7fffffffff', '82df0ffffffffff', + '82df1ffffffffff', '82df47fffffffff', '82df4ffffffffff', + '82df57fffffffff', '82df5ffffffffff', '82df77fffffffff', + '82df8ffffffffff', '82df9ffffffffff', '82e6c7fffffffff', + '82e6cffffffffff', '82e6d7fffffffff', '82e6dffffffffff', + '82e6effffffffff', '82e6f7fffffffff', + ] + + mpoly = h3.cells_to_h3shape(cells, tight=False) + + assert len(mpoly) == 12 + for poly in mpoly: + assert len(poly.holes) == 0 + + assert_cells_roundtrip(cells) + + +def test_equator_cells(): + """Continuous band of cells overlapping the equator. + """ + cells = [ + '81807ffffffffff', '817efffffffffff', '81723ffffffffff', + '817ebffffffffff', '817c3ffffffffff', '817e3ffffffffff', + '817a3ffffffffff', '8166fffffffffff', '8172bffffffffff', + '816afffffffffff', '81933ffffffffff', '8168fffffffffff', + '8188fffffffffff', '81853ffffffffff', '817f7ffffffffff', + '8180bffffffffff', '81783ffffffffff', '81743ffffffffff', + '8170bffffffffff', '8173bffffffffff', '8179bffffffffff', + '817cbffffffffff', '8188bffffffffff', '81857ffffffffff', + '816f7ffffffffff', '8177bffffffffff', '81617ffffffffff', + '816f3ffffffffff', '8174bffffffffff', '8180fffffffffff', + '817a7ffffffffff', '81767ffffffffff', '81757ffffffffff', + '81957ffffffffff', '81787ffffffffff', '81847ffffffffff', + '81653ffffffffff', '817bbffffffffff', '816cfffffffffff', + '816abffffffffff', '815f3ffffffffff', '817c7ffffffffff', + '8168bffffffffff', '818cbffffffffff', '818cfffffffffff', + '818afffffffffff', '8174fffffffffff', '8172fffffffffff', + '8170fffffffffff', '816fbffffffffff', '81657ffffffffff', + '816c7ffffffffff', '8186bffffffffff', '81763ffffffffff', + '818a7ffffffffff', '8186fffffffffff', '81707ffffffffff', + '8182bffffffffff', '818f3ffffffffff', '8182fffffffffff', + ] + mpoly = h3.cells_to_h3shape(cells, tight=False) + + assert len(mpoly) == 1 + poly = mpoly[0] + assert len(poly.holes) == 1 + + # Roundtrip fails: h3shape_to_cells recovers only 18/60 cells. + # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons. + cells2 = h3.h3shape_to_cells(mpoly, 1) + assert len(cells2) == 18 + + +def test_prime_meridian(): + """Continuous band of cells overlapping the prime meridian. + """ + cells = [ + '81efbffffffffff', '81c07ffffffffff', '81d1bffffffffff', + '81097ffffffffff', '8109bffffffffff', '81d0bffffffffff', + '81987ffffffffff', '81017ffffffffff', '81e67ffffffffff', + '81ddbffffffffff', '81ac7ffffffffff', '8158bffffffffff', + '81397ffffffffff', '81593ffffffffff', '81c17ffffffffff', + '81827ffffffffff', '81197ffffffffff', '81eebffffffffff', + '81383ffffffffff', '81dcbffffffffff', '81757ffffffffff', + '81093ffffffffff', '81073ffffffffff', '8159bffffffffff', + '81f17ffffffffff', '81187ffffffffff', '81007ffffffffff', + '81997ffffffffff', '81753ffffffffff', '81033ffffffffff', + '81f2bffffffffff', '8138bffffffffff', + ] + mpoly = h3.cells_to_h3shape(cells, tight=False) + + assert len(mpoly) == 1 + poly = mpoly[0] + assert len(poly.holes) == 0 + assert len(poly.outer) == 128 + + # Roundtrip fails: h3shape_to_cells raises on this global polygon. + # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons. with pytest.raises(H3FailedError): - h3.cells_to_h3shape(cells) + h3.h3shape_to_cells(mpoly, 1) + + +def test_anti_meridian(): + """Continuous band of cells overlapping the anti-meridian.""" + cells = [ + '817ebffffffffff', '8133bffffffffff', '81047ffffffffff', + '81f3bffffffffff', '81dbbffffffffff', '8132bffffffffff', + '810cbffffffffff', '81bb3ffffffffff', '81db3ffffffffff', + '81bafffffffffff', '81177ffffffffff', '817fbffffffffff', + '81ba3ffffffffff', '815abffffffffff', '815bbffffffffff', + '81eafffffffffff', '81ed7ffffffffff', '81057ffffffffff', + '819a7ffffffffff', '81eabffffffffff', '819b7ffffffffff', + '81167ffffffffff', '81227ffffffffff', '8171bffffffffff', + '81237ffffffffff', '810dbffffffffff', '81033ffffffffff', + '81f2bffffffffff', '8147bffffffffff', '81f33ffffffffff', + ] + mpoly = h3.cells_to_h3shape(cells, tight=False) + + assert len(mpoly) == 1 + poly = mpoly[0] + assert len(poly.holes) == 0 + assert len(poly.outer) == 117 + + # Roundtrip fails: h3shape_to_cells raises on this global polygon. + # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons. + with pytest.raises(H3FailedError): + h3.h3shape_to_cells(mpoly, 1) + + +def test_issue_482_with_antimeridian(): + """From https://github.com/uber/h3-py/issues/482 + + Test three versions: the full set, removal of antimeridian overlaps, and removal + of one cell by the north pole also causing roundtrip issues. + + Roundtrip works after removal of all troublesome cells. + """ + cells0 = { + '8001fffffffffff', '8005fffffffffff', '8009fffffffffff', '800bfffffffffff', + '8011fffffffffff', '8015fffffffffff', '8017fffffffffff', '801ffffffffffff', + '8021fffffffffff', '8025fffffffffff', '802dfffffffffff', '802ffffffffffff', + '8031fffffffffff', '8033fffffffffff', '803dfffffffffff', '803ffffffffffff', + '8041fffffffffff', '8043fffffffffff', '804bfffffffffff', '804ffffffffffff', + '8053fffffffffff', '8059fffffffffff', '8061fffffffffff', '8063fffffffffff', + '8065fffffffffff', '8069fffffffffff', '806bfffffffffff', '8073fffffffffff', + '8077fffffffffff', + } + + # remove cells that overlap the antimeridian + cells1 = cells0 - {'8005fffffffffff', '8017fffffffffff', '8033fffffffffff'} + + # remove cell that is very close to north pole (maybe touches) + cells2 = cells1 - {'8001fffffffffff'} + + # --- cells0: all 29 cells --- + mpoly = h3.cells_to_h3shape(cells0, tight=False) + assert len(mpoly) == 1 + assert len(mpoly[0].holes) == 0 + assert len(mpoly[0].outer) == 37 + + # Roundtrip fails: recovers ~23/29, and not even a subset of the original. + # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons. + cells_out = h3.h3shape_to_cells(mpoly, 0) + assert len(cells_out) < len(cells0) # exact count differs by OS + assert not (set(cells_out) <= cells0) + + # --- cells1: remove antimeridian-crossing cells (26 remaining) --- + mpoly = h3.cells_to_h3shape(cells1, tight=False) + assert len(mpoly) == 1 + assert len(mpoly[0].holes) == 0 + assert len(mpoly[0].outer) == 37 + + # Roundtrip fails: recovers 18/26, and not even a subset of the original. + # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons. + cells_out = h3.h3shape_to_cells(mpoly, 0) + assert len(cells_out) == 18 + assert not (set(cells_out) <= cells1) + + # --- cells2: also remove near-pole cell (25 remaining) --- + mpoly = h3.cells_to_h3shape(cells2, tight=False) + assert len(mpoly) == 1 + assert len(mpoly[0].holes) == 0 + assert len(mpoly[0].outer) == 37 + + # Roundtrip succeeds. + assert_cells_roundtrip(list(cells2)) From 13c17b5067133bd3c2ab6e68c31a10e100e68930 Mon Sep 17 00:00:00 2001 From: zabop Date: Thu, 26 Mar 2026 21:59:38 +0100 Subject: [PATCH 145/177] make docstring reflect what the function does (#486) --- src/h3/api/basic_int/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index 47f1c7e..1086a63 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -160,7 +160,7 @@ def is_valid_cell(h): def is_valid_directed_edge(edge): """ - Validates an H3 unidirectional edge. + Validates an H3 directed edge. Returns ------- From f175d06282b1f6933c9e5e61362d396b73a9b9c2 Mon Sep 17 00:00:00 2001 From: Marco Barbosa Date: Mon, 20 Apr 2026 02:24:41 -0300 Subject: [PATCH 146/177] updates readme.md clone instructions (#489) --- dev_notes.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/dev_notes.md b/dev_notes.md index d8635b0..65b4f62 100644 --- a/dev_notes.md +++ b/dev_notes.md @@ -6,7 +6,8 @@ This repo uses [`just`](https://github.com/casey/just) for running common develo To get started: -- `git clone git@github.com:uber/h3-py.git` +- `git clone --recurse-submodules git@github.com:uber/h3-py.git` + - or fork the repository and `git clone --recurse-submodules https://github.com/{username}/h3-py.git` - `cd h3-py` - `just lint` - `just test` From 40910c1291bf94df166044d496d9c288a23cb768 Mon Sep 17 00:00:00 2001 From: AJ Friend Date: Thu, 28 May 2026 12:36:48 -0700 Subject: [PATCH 147/177] prep for v4.5.0a3 (#491) * bump C lib to v4.5.0 * add (#491) --- CHANGELOG.md | 4 ++++ pyproject.toml | 2 +- src/h3/_cy/h3lib.pxd | 11 ++++++++--- src/h3lib | 2 +- 4 files changed, 14 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 64fe3e3..546f179 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,10 @@ avoid adding features or APIs which do not map onto the ## Unreleased +## [4.5.0a3] - 2026-05-22 + +- Update `h3lib` to v4.5.0 release (#491) + ## [4.5.0a2] - 2026-02-27 - `cells_to_h3shape`/`cells_to_geo` now handle all valid cell sets, including diff --git a/pyproject.toml b/pyproject.toml index 1da4918..754413f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.5.0a2' +version = '4.5.0a3' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index 7dfa0c5..6ee3b41 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -156,9 +156,6 @@ cdef extern from 'h3api.h': double greatCircleDistanceKm(const LatLng *a, const LatLng *b) nogil double greatCircleDistanceM(const LatLng *a, const LatLng *b) nogil - H3Error cellsToMultiPolygon(const H3int *cells, const int64_t numCells, GeoMultiPolygon *out) - void destroyGeoMultiPolygon(GeoMultiPolygon *mpoly) - H3Error maxPolygonToCellsSize(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t *count) H3Error polygonToCells(const GeoPolygon *geoPolygon, int res, uint32_t flags, H3int *out) @@ -184,3 +181,11 @@ cdef extern from 'h3api.h': # void h3ToString(H3int h, char *str, size_t sz) # void getH3intesFromUnidirectionalEdge(H3int edge, H3int *originDestination) + + +# cellsToMultiPolygon and destroyGeoMultiPolygon are temporarily excluded +# from the public API, so we use an internal header until they're moved +# back into h3api.h +cdef extern from 'cellsToMultiPoly.h': + H3Error cellsToMultiPolygon(const H3int *cells, const int64_t numCells, GeoMultiPolygon *out) + void destroyGeoMultiPolygon(GeoMultiPolygon *mpoly) diff --git a/src/h3lib b/src/h3lib index a9c0a2e..1b536c3 160000 --- a/src/h3lib +++ b/src/h3lib @@ -1 +1 @@ -Subproject commit a9c0a2ec7869fa01772dcebdf930590469910600 +Subproject commit 1b536c34225191ba24a75a840f634d4a48c3b206 From a663439e0e4c6c2887da8d3af0608156a7f07165 Mon Sep 17 00:00:00 2001 From: Jongbin Jung Date: Fri, 29 May 2026 09:15:58 -0700 Subject: [PATCH 148/177] Prep for v4.5.0 release --- CHANGELOG.md | 6 +++++- pyproject.toml | 2 +- readme.md | 2 +- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 546f179..651c76c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,10 @@ avoid adding features or APIs which do not map onto the ## Unreleased +## [4.5.0] - 2026-05-29 + +- Final v4.5 release includes all v4.5.x changes below + ## [4.5.0a3] - 2026-05-22 - Update `h3lib` to v4.5.0 release (#491) @@ -152,7 +156,7 @@ Beta release; feedback welcome! - Website and API documentation; along with docstring cleanup. - Add support for linters and IDE tooling (#213) - Remove Py 3.5 wheel for Windows (#214) -- Py 3.10 wheels and on more architectures (#220, #221, #223, #225) +- Py 3.10 wheels and on more architectures (#220, #221, #223, #225) - Greatly reduce sdist size (#227, #229) ## [3.7.3] - 2021-06-12 diff --git a/pyproject.toml b/pyproject.toml index 754413f..f3304b9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.5.0a3' +version = '4.5.0' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} diff --git a/readme.md b/readme.md index 843324e..8cb052b 100644 --- a/readme.md +++ b/readme.md @@ -5,7 +5,7 @@ [![PyPI version](https://badge.fury.io/py/h3.svg)](https://badge.fury.io/py/h3) [![PyPI downloads](https://img.shields.io/pypi/dm/h3.svg)](https://pypistats.org/packages/h3) [![conda](https://img.shields.io/conda/vn/conda-forge/h3-py.svg)](https://anaconda.org/conda-forge/h3-py) -[![version](https://img.shields.io/badge/h3-v4.4.1-blue.svg)](https://github.com/uber/h3/releases/tag/v4.4.1) +[![version](https://img.shields.io/badge/h3-v4.5.0-blue.svg)](https://github.com/uber/h3/releases/tag/v4.5.0) [![version](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/uber/h3-py/blob/master/LICENSE) [![Tests](https://github.com/uber/h3-py/workflows/tests/badge.svg)](https://github.com/uber/h3-py/actions) From 7d1df6e070a9c4794d31199ef945322554aca2ad Mon Sep 17 00:00:00 2001 From: Arpit Jain Date: Fri, 15 May 2026 00:51:22 +0900 Subject: [PATCH 149/177] ci: declare contents:read on lint_and_coverage workflow Signed-off-by: Arpit Jain --- .github/workflows/lint_and_coverage.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/lint_and_coverage.yml b/.github/workflows/lint_and_coverage.yml index c0eb154..8ec1ef1 100644 --- a/.github/workflows/lint_and_coverage.yml +++ b/.github/workflows/lint_and_coverage.yml @@ -6,6 +6,9 @@ on: pull_request: branches: ['*'] +permissions: + contents: read + jobs: linting: name: Lint and Coverage From 33badf14f235ec832865949dc8dabba60d56939f Mon Sep 17 00:00:00 2001 From: Marco Barbosa Date: Wed, 17 Jun 2026 23:44:05 +0000 Subject: [PATCH 150/177] annotates .pyx cython files as compatible with freethreading python --- src/h3/_cy/cells.pyx | 1 + src/h3/_cy/edges.pyx | 1 + src/h3/_cy/error_system.pyx | 1 + src/h3/_cy/latlng.pyx | 1 + src/h3/_cy/memory.pyx | 1 + src/h3/_cy/to_multipoly.pyx | 1 + src/h3/_cy/util.pyx | 1 + src/h3/_cy/vertex.pyx | 1 + 8 files changed, 8 insertions(+) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 78d2561..8b84f9d 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -1,3 +1,4 @@ +# cython: freethreading_compatible=True cimport h3lib from .h3lib cimport bool, int64_t, H3int, H3ErrorCodes diff --git a/src/h3/_cy/edges.pyx b/src/h3/_cy/edges.pyx index bd0aa7c..1d2ef74 100644 --- a/src/h3/_cy/edges.pyx +++ b/src/h3/_cy/edges.pyx @@ -1,3 +1,4 @@ +# cython: freethreading_compatible=True cimport h3lib from .h3lib cimport bool, H3int diff --git a/src/h3/_cy/error_system.pyx b/src/h3/_cy/error_system.pyx index fc18f46..5fe5cd9 100644 --- a/src/h3/_cy/error_system.pyx +++ b/src/h3/_cy/error_system.pyx @@ -1,3 +1,4 @@ +# cython: freethreading_compatible=True """ Exceptions from the h3-py library have three possible sources: diff --git a/src/h3/_cy/latlng.pyx b/src/h3/_cy/latlng.pyx index d83a9d3..1593d43 100644 --- a/src/h3/_cy/latlng.pyx +++ b/src/h3/_cy/latlng.pyx @@ -1,3 +1,4 @@ +# cython: freethreading_compatible=True from libc.stdint cimport uint64_t cimport h3lib diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index 0852105..963b00d 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -1,3 +1,4 @@ +# cython: freethreading_compatible=True from cython.view cimport array from .h3lib cimport H3int diff --git a/src/h3/_cy/to_multipoly.pyx b/src/h3/_cy/to_multipoly.pyx index ed3e763..cb5e5e2 100644 --- a/src/h3/_cy/to_multipoly.pyx +++ b/src/h3/_cy/to_multipoly.pyx @@ -1,3 +1,4 @@ +# cython: freethreading_compatible=True cimport h3lib from h3lib cimport H3int from .util cimport check_cell, coord2deg diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index 9b070f9..06823d0 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -1,3 +1,4 @@ +# cython: freethreading_compatible=True from .h3lib cimport ( H3int, H3str, diff --git a/src/h3/_cy/vertex.pyx b/src/h3/_cy/vertex.pyx index 26a674a..99cc5ef 100644 --- a/src/h3/_cy/vertex.pyx +++ b/src/h3/_cy/vertex.pyx @@ -1,3 +1,4 @@ +# cython: freethreading_compatible=True cimport h3lib from h3lib cimport bool, H3int From 1ed3273533d62a7fe61dbf4fbb35c08e4f3b0599 Mon Sep 17 00:00:00 2001 From: Marco Barbosa Date: Thu, 18 Jun 2026 00:04:12 +0000 Subject: [PATCH 151/177] adds trove for python free threading and changelog --- CHANGELOG.md | 1 + pyproject.toml | 1 + 2 files changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 651c76c..7ad11bf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ avoid adding features or APIs which do not map onto the [H3 core API](https://uber.github.io/h3/#/documentation/api-reference/). ## Unreleased +- Fix wheels for Python 3.14.6 free-threading ## [4.5.0] - 2026-05-29 diff --git a/pyproject.toml b/pyproject.toml index f3304b9..2474f88 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,6 +30,7 @@ classifiers = [ 'Programming Language :: Python :: 3.12', 'Programming Language :: Python :: 3.13', 'Programming Language :: Python :: 3.14', + 'Programming Language :: Python :: Free Threading', 'Operating System :: MacOS :: MacOS X', 'Operating System :: POSIX :: Linux', 'Operating System :: Microsoft :: Windows', From 4e9d379a2005866fc1a391b88754ee73381176c8 Mon Sep 17 00:00:00 2001 From: dyrpsf Date: Tue, 7 Jul 2026 15:23:28 +0530 Subject: [PATCH 152/177] build: detect Buildozer environment to fix Android cross-compilation --- CMakeLists.txt | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/CMakeLists.txt b/CMakeLists.txt index 40ce38e..52a76f1 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,5 +1,16 @@ cmake_minimum_required(VERSION 3.15...3.26) +# --- BEGIN ANDROID CROSS-COMPILATION FIX --- +# Buildozer/python-for-android uses standard pip install which doesn't natively +# pass a CMake toolchain file to scikit-build-core. This detects the Android compiler +# from the environment and forces CMake into cross-compilation mode to prevent +# it from building host (x86_64) binaries. +if("$ENV{CC}" MATCHES "android" AND NOT DEFINED CMAKE_SYSTEM_NAME) + message(STATUS "Detected Android cross-compilation via environment variables. Setting CMAKE_SYSTEM_NAME=Android") + set(CMAKE_SYSTEM_NAME Android) +endif() +# --- END ANDROID CROSS-COMPILATION FIX --- + project(${SKBUILD_PROJECT_NAME} LANGUAGES C) set(CMAKE_POSITION_INDEPENDENT_CODE ON) From 1d358b275ecdd7164b958982b07b8b6e40afcf5b Mon Sep 17 00:00:00 2001 From: dyrpsf Date: Wed, 22 Jul 2026 09:02:39 +0530 Subject: [PATCH 153/177] feat: add container formatting options to GeoJSON outputs --- src/h3/_h3shape.py | 56 ++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 47 insertions(+), 9 deletions(-) diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py index 5c36295..3586d29 100644 --- a/src/h3/_h3shape.py +++ b/src/h3/_h3shape.py @@ -184,13 +184,6 @@ LL0: lat/lng or lng/lat pair LL1: list of LL0s LL2: list of LL1s (i.e., a polygon with holes) LL3: list of LL2s (i.e., several polygons with holes) - - -## TODO - -- Allow user to specify "container" in `cells_to_geojson`. - - That is, they may want a MultiPolygon even if the output fits in a Polygon - - 'auto', Polygon, MultiPolygon, FeatureCollection, GeometryCollection, ... """ @@ -325,14 +318,59 @@ def geo_to_h3shape(geo): return shape -def h3shape_to_geo(h3shape): +def h3shape_to_geo(h3shape, container='auto'): """ Translate from an ``H3Shape`` to a ``__geo_interface__`` dict. ``h3shape`` should be either ``LatLngPoly`` or ``LatLngMultiPoly`` + + Parameters + ---------- + container : str, optional + Specify the desired GeoJSON output container. + Options: 'auto', 'Polygon', 'MultiPolygon', 'Feature', + 'FeatureCollection', or 'GeometryCollection'. + Default is 'auto' (returns the simplest valid geometry). Returns ------- dict """ - return h3shape.__geo_interface__ + base_geo = h3shape.__geo_interface__ + + if container == 'auto' or container == base_geo['type']: + return base_geo + + # Upgrade a Polygon to a MultiPolygon if explicitly requested + if container == 'MultiPolygon' and base_geo['type'] == 'Polygon': + return { + 'type': 'MultiPolygon', + 'coordinates': (base_geo['coordinates'],) + } + + if container == 'Feature': + return { + 'type': 'Feature', + 'geometry': base_geo, + 'properties': {} + } + + if container == 'FeatureCollection': + return { + 'type': 'FeatureCollection', + 'features': [{ + 'type': 'Feature', + 'geometry': base_geo, + 'properties': {} + }] + } + + if container == 'GeometryCollection': + return { + 'type': 'GeometryCollection', + 'geometries': [base_geo] + } + + # If a downgrade is requested (e.g., MultiPolygon to Polygon) which + # risks data loss, or an unknown container is passed, return safely. + return base_geo From b1f5f9abc8dc942c49cf4db501e4adbdde52ed38 Mon Sep 17 00:00:00 2001 From: dyrpsf Date: Wed, 22 Jul 2026 16:02:28 +0530 Subject: [PATCH 154/177] test: add unit tests for GeoJSON container options; fix linting --- src/h3/_h3shape.py | 14 ++++++------- tests/test_geojson_containers.py | 35 ++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+), 7 deletions(-) create mode 100644 tests/test_geojson_containers.py diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py index 3586d29..93059e7 100644 --- a/src/h3/_h3shape.py +++ b/src/h3/_h3shape.py @@ -337,24 +337,24 @@ def h3shape_to_geo(h3shape, container='auto'): dict """ base_geo = h3shape.__geo_interface__ - + if container == 'auto' or container == base_geo['type']: return base_geo - + # Upgrade a Polygon to a MultiPolygon if explicitly requested if container == 'MultiPolygon' and base_geo['type'] == 'Polygon': return { 'type': 'MultiPolygon', 'coordinates': (base_geo['coordinates'],) } - + if container == 'Feature': return { 'type': 'Feature', 'geometry': base_geo, 'properties': {} } - + if container == 'FeatureCollection': return { 'type': 'FeatureCollection', @@ -364,13 +364,13 @@ def h3shape_to_geo(h3shape, container='auto'): 'properties': {} }] } - + if container == 'GeometryCollection': return { 'type': 'GeometryCollection', 'geometries': [base_geo] } - - # If a downgrade is requested (e.g., MultiPolygon to Polygon) which + + # If a downgrade is requested (e.g., MultiPolygon to Polygon) which # risks data loss, or an unknown container is passed, return safely. return base_geo diff --git a/tests/test_geojson_containers.py b/tests/test_geojson_containers.py new file mode 100644 index 0000000..2ecf952 --- /dev/null +++ b/tests/test_geojson_containers.py @@ -0,0 +1,35 @@ +import pytest +from h3._h3shape import LatLngPoly, h3shape_to_geo + +def test_h3shape_to_geo_containers(): + # Create a basic dummy polygon for testing + poly = LatLngPoly( + [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)] + ) + + # Test 'auto' (Default behavior should return a Polygon) + auto_geo = h3shape_to_geo(poly, container='auto') + assert auto_geo['type'] == 'Polygon' + + # Test MultiPolygon wrapper + mp_geo = h3shape_to_geo(poly, container='MultiPolygon') + assert mp_geo['type'] == 'MultiPolygon' + assert len(mp_geo['coordinates']) == 1 + + # Test Feature wrapper + feat_geo = h3shape_to_geo(poly, container='Feature') + assert feat_geo['type'] == 'Feature' + assert feat_geo['geometry']['type'] == 'Polygon' + + # Test FeatureCollection wrapper + fc_geo = h3shape_to_geo(poly, container='FeatureCollection') + assert fc_geo['type'] == 'FeatureCollection' + assert len(fc_geo['features']) == 1 + assert fc_geo['features'][0]['type'] == 'Feature' + assert fc_geo['features'][0]['geometry']['type'] == 'Polygon' + + # Test GeometryCollection wrapper + gc_geo = h3shape_to_geo(poly, container='GeometryCollection') + assert gc_geo['type'] == 'GeometryCollection' + assert len(gc_geo['geometries']) == 1 + assert gc_geo['geometries'][0]['type'] == 'Polygon' \ No newline at end of file From e02b8a6e95ab66ee31d8a6d77a79e1924d8ed938 Mon Sep 17 00:00:00 2001 From: dyrpsf Date: Wed, 22 Jul 2026 20:40:46 +0530 Subject: [PATCH 155/177] fix: raise ValueError for invalid or insufficient GeoJSON containers --- src/h3/_h3shape.py | 8 +++++--- tests/test_geojson_containers.py | 17 +++++++++++++++-- 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py index 93059e7..477a5ec 100644 --- a/src/h3/_h3shape.py +++ b/src/h3/_h3shape.py @@ -371,6 +371,8 @@ def h3shape_to_geo(h3shape, container='auto'): 'geometries': [base_geo] } - # If a downgrade is requested (e.g., MultiPolygon to Polygon) which - # risks data loss, or an unknown container is passed, return safely. - return base_geo + # If we reach here, the requested container is either unknown or + # insufficient for the data (e.g., requesting a Polygon for MultiPolygon data). + raise ValueError( + f"Requested container '{container}' is invalid or insufficient for data of type '{base_geo['type']}'." + ) diff --git a/tests/test_geojson_containers.py b/tests/test_geojson_containers.py index 2ecf952..bfc3a41 100644 --- a/tests/test_geojson_containers.py +++ b/tests/test_geojson_containers.py @@ -1,5 +1,5 @@ import pytest -from h3._h3shape import LatLngPoly, h3shape_to_geo +from h3._h3shape import LatLngPoly, h3shape_to_geo, LatLngMultiPoly def test_h3shape_to_geo_containers(): # Create a basic dummy polygon for testing @@ -32,4 +32,17 @@ def test_h3shape_to_geo_containers(): gc_geo = h3shape_to_geo(poly, container='GeometryCollection') assert gc_geo['type'] == 'GeometryCollection' assert len(gc_geo['geometries']) == 1 - assert gc_geo['geometries'][0]['type'] == 'Polygon' \ No newline at end of file + assert gc_geo['geometries'][0]['type'] == 'Polygon' + +def test_h3shape_to_geo_invalid_containers(): + # 1. Test an unknown container string + poly = LatLngPoly([(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)]) + with pytest.raises(ValueError, match="invalid or insufficient"): + h3shape_to_geo(poly, container='InvalidString') + + # 2. Test an insufficient container (MultiPolygon data into a Polygon container) + mpoly = LatLngMultiPoly([ + [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)] + ]) + with pytest.raises(ValueError, match="invalid or insufficient"): + h3shape_to_geo(mpoly, container='Polygon') \ No newline at end of file From a2add15580cebc424d66df6081324b103401dc90 Mon Sep 17 00:00:00 2001 From: dyrpsf Date: Wed, 22 Jul 2026 22:37:23 +0530 Subject: [PATCH 156/177] test: verify MultiPolygon to MultiPolygon matching; fix line length --- src/h3/_h3shape.py | 12 +++++++----- tests/test_geojson_containers.py | 28 +++++++++++++++++++++------- 2 files changed, 28 insertions(+), 12 deletions(-) diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py index 477a5ec..7aa7f62 100644 --- a/src/h3/_h3shape.py +++ b/src/h3/_h3shape.py @@ -323,12 +323,12 @@ def h3shape_to_geo(h3shape, container='auto'): Translate from an ``H3Shape`` to a ``__geo_interface__`` dict. ``h3shape`` should be either ``LatLngPoly`` or ``LatLngMultiPoly`` - + Parameters ---------- container : str, optional - Specify the desired GeoJSON output container. - Options: 'auto', 'Polygon', 'MultiPolygon', 'Feature', + Specify the desired GeoJSON output container. + Options: 'auto', 'Polygon', 'MultiPolygon', 'Feature', 'FeatureCollection', or 'GeometryCollection'. Default is 'auto' (returns the simplest valid geometry). @@ -338,6 +338,7 @@ def h3shape_to_geo(h3shape, container='auto'): """ base_geo = h3shape.__geo_interface__ + # Return immediately if no wrapping is needed if container == 'auto' or container == base_geo['type']: return base_geo @@ -371,8 +372,9 @@ def h3shape_to_geo(h3shape, container='auto'): 'geometries': [base_geo] } - # If we reach here, the requested container is either unknown or + # If we reach here, the requested container is either unknown or # insufficient for the data (e.g., requesting a Polygon for MultiPolygon data). raise ValueError( - f"Requested container '{container}' is invalid or insufficient for data of type '{base_geo['type']}'." + f"Requested container '{container}' is invalid or insufficient " + f"for data of type '{base_geo['type']}'." ) diff --git a/tests/test_geojson_containers.py b/tests/test_geojson_containers.py index bfc3a41..35629d5 100644 --- a/tests/test_geojson_containers.py +++ b/tests/test_geojson_containers.py @@ -1,26 +1,27 @@ import pytest from h3._h3shape import LatLngPoly, h3shape_to_geo, LatLngMultiPoly + def test_h3shape_to_geo_containers(): # Create a basic dummy polygon for testing poly = LatLngPoly( [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)] ) - + # Test 'auto' (Default behavior should return a Polygon) auto_geo = h3shape_to_geo(poly, container='auto') assert auto_geo['type'] == 'Polygon' - + # Test MultiPolygon wrapper mp_geo = h3shape_to_geo(poly, container='MultiPolygon') assert mp_geo['type'] == 'MultiPolygon' assert len(mp_geo['coordinates']) == 1 - + # Test Feature wrapper feat_geo = h3shape_to_geo(poly, container='Feature') assert feat_geo['type'] == 'Feature' assert feat_geo['geometry']['type'] == 'Polygon' - + # Test FeatureCollection wrapper fc_geo = h3shape_to_geo(poly, container='FeatureCollection') assert fc_geo['type'] == 'FeatureCollection' @@ -34,15 +35,28 @@ def test_h3shape_to_geo_containers(): assert len(gc_geo['geometries']) == 1 assert gc_geo['geometries'][0]['type'] == 'Polygon' + def test_h3shape_to_geo_invalid_containers(): # 1. Test an unknown container string poly = LatLngPoly([(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)]) - with pytest.raises(ValueError, match="invalid or insufficient"): + with pytest.raises(ValueError, match='invalid or insufficient'): h3shape_to_geo(poly, container='InvalidString') # 2. Test an insufficient container (MultiPolygon data into a Polygon container) mpoly = LatLngMultiPoly([ [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)] ]) - with pytest.raises(ValueError, match="invalid or insufficient"): - h3shape_to_geo(mpoly, container='Polygon') \ No newline at end of file + with pytest.raises(ValueError, match='invalid or insufficient'): + h3shape_to_geo(mpoly, container='Polygon') + + +def test_h3shape_to_geo_exact_match(): + # Test that requesting a MultiPolygon for MultiPolygon data succeeds + mpoly = LatLngMultiPoly([ + [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)] + ]) + + mp_geo = h3shape_to_geo(mpoly, container='MultiPolygon') + + assert mp_geo['type'] == 'MultiPolygon' + assert len(mp_geo['coordinates']) == 1 From 03678bb3ed49ef93a7e84cec1f5cb7d61443fed6 Mon Sep 17 00:00:00 2001 From: dyrpsf Date: Sat, 25 Jul 2026 23:16:31 +0530 Subject: [PATCH 157/177] test: fix LatLngMultiPoly initialization to resolve CI crash and restore coverage --- tests/test_geojson_containers.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/tests/test_geojson_containers.py b/tests/test_geojson_containers.py index 35629d5..5421353 100644 --- a/tests/test_geojson_containers.py +++ b/tests/test_geojson_containers.py @@ -43,20 +43,20 @@ def test_h3shape_to_geo_invalid_containers(): h3shape_to_geo(poly, container='InvalidString') # 2. Test an insufficient container (MultiPolygon data into a Polygon container) - mpoly = LatLngMultiPoly([ - [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)] - ]) + mpoly = LatLngMultiPoly( + LatLngPoly([(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)]) + ) with pytest.raises(ValueError, match='invalid or insufficient'): h3shape_to_geo(mpoly, container='Polygon') def test_h3shape_to_geo_exact_match(): # Test that requesting a MultiPolygon for MultiPolygon data succeeds - mpoly = LatLngMultiPoly([ - [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)] - ]) + mpoly = LatLngMultiPoly( + LatLngPoly([(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)]) + ) mp_geo = h3shape_to_geo(mpoly, container='MultiPolygon') assert mp_geo['type'] == 'MultiPolygon' - assert len(mp_geo['coordinates']) == 1 + assert len(mp_geo['coordinates']) == 1 \ No newline at end of file From 55530fa42b34dd7aacc913a65d5ada6d54895fea Mon Sep 17 00:00:00 2001 From: dyrpsf Date: Sun, 26 Jul 2026 00:43:15 +0530 Subject: [PATCH 158/177] test: move tests to test_lib for coverage; fix EOF newline --- tests/{ => test_lib}/test_geojson_containers.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename tests/{ => test_lib}/test_geojson_containers.py (98%) diff --git a/tests/test_geojson_containers.py b/tests/test_lib/test_geojson_containers.py similarity index 98% rename from tests/test_geojson_containers.py rename to tests/test_lib/test_geojson_containers.py index 5421353..a890c27 100644 --- a/tests/test_geojson_containers.py +++ b/tests/test_lib/test_geojson_containers.py @@ -59,4 +59,4 @@ def test_h3shape_to_geo_exact_match(): mp_geo = h3shape_to_geo(mpoly, container='MultiPolygon') assert mp_geo['type'] == 'MultiPolygon' - assert len(mp_geo['coordinates']) == 1 \ No newline at end of file + assert len(mp_geo['coordinates']) == 1 From 497aa4df24668650e1d3e599511547d6be6b1caa Mon Sep 17 00:00:00 2001 From: dyrpsf Date: Sun, 26 Jul 2026 22:13:45 +0530 Subject: [PATCH 159/177] test: clean up string formatting in test_parent_err --- tests/test_lib/test_cells_and_edges.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/tests/test_lib/test_cells_and_edges.py b/tests/test_lib/test_cells_and_edges.py index 4b8e107..bae5d69 100644 --- a/tests/test_lib/test_cells_and_edges.py +++ b/tests/test_lib/test_cells_and_edges.py @@ -131,9 +131,7 @@ def test_parent_err(): except Exception as e: msg = str(e) - # todo: revist this weird formatting stuff - expected = 'Invalid parent resolution -1 for cell {}.' - expected = expected.format(hex(h3.str_to_int(h))) + expected = f'Invalid parent resolution -1 for cell 0x{h}.' assert msg == expected From 2f62194f0f29c8a8b05439c489604ef2d7a391be Mon Sep 17 00:00:00 2001 From: dyrpsf Date: Tue, 28 Jul 2026 08:34:00 +0530 Subject: [PATCH 160/177] test: add test for uncompacting cells to a coarser resolution --- src/h3/api/basic_int/__init__.py | 2 -- tests/test_lib/test_cells_and_edges.py | 10 ++++++++++ 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index 1086a63..ef82792 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -474,8 +474,6 @@ def uncompact_cells(cells, res): ----- There is currently no guaranteed order of the output cells. """ - # TODO: add test to make sure an error is returned when input contains cell - # smaller than output res. hc = _in_collection(cells) hu = _cy.uncompact_cells(hc, res) diff --git a/tests/test_lib/test_cells_and_edges.py b/tests/test_lib/test_cells_and_edges.py index 4b8e107..240a638 100644 --- a/tests/test_lib/test_cells_and_edges.py +++ b/tests/test_lib/test_cells_and_edges.py @@ -755,3 +755,13 @@ def test_construct_cell_inverses_int_api(): def test_center_child_with_deconstruct(): for h in h3.get_res0_cells(): h3.construct_cell(*h3.deconstruct_cell(h), 0) == h3.cell_to_center_child(h) + + +def test_uncompact_cells_invalid_resolution(): + # Create a valid cell at resolution 5 + h_res5 = h3.latlng_to_cell(0, 0, 5) + + # Attempting to uncompact to a coarser resolution (4) + # should raise an H3ResDomainError + with pytest.raises(H3ResDomainError): + h3.uncompact_cells({h_res5}, 4) From 8cd64decd00f66379946b35e37adb76531a45786 Mon Sep 17 00:00:00 2001 From: Deepak Yadav Date: Sat, 1 Aug 2026 21:07:42 +0530 Subject: [PATCH 161/177] Update tests/test_lib/test_cells_and_edges.py Co-authored-by: Isaac Brodsky --- tests/test_lib/test_cells_and_edges.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_lib/test_cells_and_edges.py b/tests/test_lib/test_cells_and_edges.py index bae5d69..46e7df2 100644 --- a/tests/test_lib/test_cells_and_edges.py +++ b/tests/test_lib/test_cells_and_edges.py @@ -131,7 +131,7 @@ def test_parent_err(): except Exception as e: msg = str(e) - expected = f'Invalid parent resolution -1 for cell 0x{h}.' + expected = f'Invalid parent resolution -1 for cell {h}.' assert msg == expected From 58be699d132f952e186757a5eeaf2bd455857e8d Mon Sep 17 00:00:00 2001 From: Deepak Yadav Date: Sat, 1 Aug 2026 21:11:58 +0530 Subject: [PATCH 162/177] Update tests/test_lib/test_cells_and_edges.py Co-authored-by: Isaac Brodsky --- tests/test_lib/test_cells_and_edges.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_lib/test_cells_and_edges.py b/tests/test_lib/test_cells_and_edges.py index 240a638..2b106e6 100644 --- a/tests/test_lib/test_cells_and_edges.py +++ b/tests/test_lib/test_cells_and_edges.py @@ -763,5 +763,5 @@ def test_uncompact_cells_invalid_resolution(): # Attempting to uncompact to a coarser resolution (4) # should raise an H3ResDomainError - with pytest.raises(H3ResDomainError): + with pytest.raises(H3ResMismatchError): h3.uncompact_cells({h_res5}, 4) From 822320f30bf7f9381b5c00c4f7800b7a7b6581bb Mon Sep 17 00:00:00 2001 From: dyrpsf Date: Sun, 2 Aug 2026 10:05:10 +0530 Subject: [PATCH 163/177] test: restore 0x prefix to match actual exception message --- tests/test_lib/test_cells_and_edges.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_lib/test_cells_and_edges.py b/tests/test_lib/test_cells_and_edges.py index 46e7df2..bae5d69 100644 --- a/tests/test_lib/test_cells_and_edges.py +++ b/tests/test_lib/test_cells_and_edges.py @@ -131,7 +131,7 @@ def test_parent_err(): except Exception as e: msg = str(e) - expected = f'Invalid parent resolution -1 for cell {h}.' + expected = f'Invalid parent resolution -1 for cell 0x{h}.' assert msg == expected From 5dc46e4f287772f6bef6090ec96b3d2219428485 Mon Sep 17 00:00:00 2001 From: dyrpsf Date: Mon, 3 Aug 2026 21:43:59 +0530 Subject: [PATCH 164/177] test: update comment to match H3ResMismatchError --- tests/test_lib/test_cells_and_edges.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_lib/test_cells_and_edges.py b/tests/test_lib/test_cells_and_edges.py index 2b106e6..77e8f5e 100644 --- a/tests/test_lib/test_cells_and_edges.py +++ b/tests/test_lib/test_cells_and_edges.py @@ -762,6 +762,6 @@ def test_uncompact_cells_invalid_resolution(): h_res5 = h3.latlng_to_cell(0, 0, 5) # Attempting to uncompact to a coarser resolution (4) - # should raise an H3ResDomainError + # should raise an H3ResMismatchError with pytest.raises(H3ResMismatchError): h3.uncompact_cells({h_res5}, 4) From e3b0a6d96d7ef8e7f68cbcb45b800b37bf383fe8 Mon Sep 17 00:00:00 2001 From: Jongbin Jung Date: Wed, 12 Aug 2026 12:52:02 -0700 Subject: [PATCH 165/177] Add CI test and build for python3.14t --- .github/workflows/tests.yml | 2 +- .github/workflows/wheels.yml | 9 +++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 7920a84..f3dcc3c 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -14,7 +14,7 @@ jobs: strategy: matrix: os: [macos-latest, windows-latest, ubuntu-22.04] - python-version: ['3.10', '3.11', '3.12', '3.13', '3.14'] + python-version: ['3.10', '3.11', '3.12', '3.13', '3.14', '3.14t'] steps: - uses: actions/checkout@v6.0.2 diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index dbc8d6d..b9bc985 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -80,6 +80,9 @@ jobs: - os: windows-11-arm build: 'cp314-win_arm64' name: Windows ARM64 3.14 + - os: windows-11-arm + build: 'cp314t-win_arm64' + name: Windows ARM64 3.14t - os: ubuntu-22.04 build: 'cp*-manylinux_x86_64' @@ -100,6 +103,9 @@ jobs: - os: ubuntu-22.04 build: 'cp314-musllinux_x86_64' name: Linux Intel musl 64-bit 3.14 + - os: ubuntu-22.04 + build: 'cp314t-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.14t - os: ubuntu-22.04 build: 'cp310-manylinux_aarch64' @@ -116,6 +122,9 @@ jobs: - os: ubuntu-22.04 build: 'cp314-manylinux_aarch64' name: Linux Aarch64 3.14 + - os: ubuntu-22.04 + build: 'cp314t-manylinux_aarch64' + name: Linux Aarch64 3.14t steps: - uses: actions/checkout@v6.0.2 From a4bc7398f42bf9cfc1983f09ffa857f58c04c0e9 Mon Sep 17 00:00:00 2001 From: Hashim1999164 <64767361+Hashim1999164@users.noreply.github.com> Date: Sun, 23 Aug 2026 01:32:12 +0500 Subject: [PATCH 166/177] Raise ValueError instead of assert in geo_to_h3shape The leftover assert isinstance check tripped Bandit and was marked for removal. Invalid inputs now get an explicit ValueError. --- src/h3/_h3shape.py | 6 +++++- tests/test_lib/polyfill/test_h3.py | 5 +++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py index 7aa7f62..a8146df 100644 --- a/src/h3/_h3shape.py +++ b/src/h3/_h3shape.py @@ -301,7 +301,11 @@ def geo_to_h3shape(geo): # get dict geo = geo.__geo_interface__ - assert isinstance(geo, dict) # todo: remove + if not isinstance(geo, dict): + raise ValueError( + 'geo must be a dict or implement __geo_interface__, got: ' + + str(type(geo)) + ) t = geo['type'] coord = geo['coordinates'] diff --git a/tests/test_lib/polyfill/test_h3.py b/tests/test_lib/polyfill/test_h3.py index 72ddd58..fed297f 100644 --- a/tests/test_lib/polyfill/test_h3.py +++ b/tests/test_lib/polyfill/test_h3.py @@ -302,6 +302,11 @@ def test_geo_to_h3shape_passthrough(): assert h3.geo_to_h3shape(shape) is shape +def test_geo_to_h3shape_rejects_non_dict(): + with pytest.raises(ValueError, match='dict or implement __geo_interface__'): + h3.geo_to_h3shape('not a geo object') + + def test_polyfill_down_under(): sydney = [ (-33.8556, 151.1979), From c7b48389da04dffba5b6c0529c60653845bba4e8 Mon Sep 17 00:00:00 2001 From: dyrpsf Date: Wed, 26 Aug 2026 22:04:52 +0530 Subject: [PATCH 167/177] fix: replace geo input assert with ValueError and add test --- src/h3/_h3shape.py | 3 ++- tests/test_lib/polyfill/test_polyfill.py | 14 ++++++++++++++ 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py index 7aa7f62..eadc2e5 100644 --- a/src/h3/_h3shape.py +++ b/src/h3/_h3shape.py @@ -301,7 +301,8 @@ def geo_to_h3shape(geo): # get dict geo = geo.__geo_interface__ - assert isinstance(geo, dict) # todo: remove + if not isinstance(geo, dict): + raise ValueError(f"Expected a dict or an object with __geo_interface__, but got: {type(geo).__name__}") t = geo['type'] coord = geo['coordinates'] diff --git a/tests/test_lib/polyfill/test_polyfill.py b/tests/test_lib/polyfill/test_polyfill.py index 9bdd9af..5f83be0 100644 --- a/tests/test_lib/polyfill/test_polyfill.py +++ b/tests/test_lib/polyfill/test_polyfill.py @@ -166,3 +166,17 @@ def test_cells_to_geo(): assert coord[0][0] == coord[0][-1] assert h3.geo_to_cells(geo, res) == [h] + +def test_bad_geo_input(): + with pytest.raises(ValueError): + h3.h3shape_to_cells('not a shape', 9) + + with pytest.raises(ValueError): + h3.h3shape_to_cells_experimental('not a shape', res=9) + + with pytest.raises(ValueError): + h3.geo_to_cells({'type': 'not a shape', 'coordinates': None}, 9) + + # Add this new block to test our specific fix! + with pytest.raises(ValueError): + h3.geo_to_cells('not a shape', 9) From 631d8a6e435dba129363e1a2d8a21bb7a5bc70e7 Mon Sep 17 00:00:00 2001 From: dyrpsf Date: Thu, 27 Aug 2026 09:36:30 +0530 Subject: [PATCH 168/177] test: consolidate test_bad_geo_input to fix linter error --- tests/test_lib/polyfill/test_polyfill.py | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) diff --git a/tests/test_lib/polyfill/test_polyfill.py b/tests/test_lib/polyfill/test_polyfill.py index 5f83be0..f70c639 100644 --- a/tests/test_lib/polyfill/test_polyfill.py +++ b/tests/test_lib/polyfill/test_polyfill.py @@ -151,6 +151,9 @@ def test_bad_geo_input(): with pytest.raises(ValueError): h3.geo_to_cells({'type': 'not a shape', 'coordinates': None}, 9) + with pytest.raises(ValueError): + h3.geo_to_cells('not a shape', 9) + def test_cells_to_geo(): h = '89754e64993ffff' @@ -166,17 +169,3 @@ def test_cells_to_geo(): assert coord[0][0] == coord[0][-1] assert h3.geo_to_cells(geo, res) == [h] - -def test_bad_geo_input(): - with pytest.raises(ValueError): - h3.h3shape_to_cells('not a shape', 9) - - with pytest.raises(ValueError): - h3.h3shape_to_cells_experimental('not a shape', res=9) - - with pytest.raises(ValueError): - h3.geo_to_cells({'type': 'not a shape', 'coordinates': None}, 9) - - # Add this new block to test our specific fix! - with pytest.raises(ValueError): - h3.geo_to_cells('not a shape', 9) From 47efd3266cb68f1efdc2baa832104f19057682f5 Mon Sep 17 00:00:00 2001 From: Conner Kupferberg Date: Tue, 22 Sep 2026 05:16:00 +0000 Subject: [PATCH 169/177] perf: bind scalar functions directly to _cy when _out_scalar is identity (#501) In h3.api.basic_int, numpy_int, and memview_int, _out_scalar is the identity function, incurring unnecessary Python function call frames and wrapper overhead on every scalar call. When _out_scalar is _in_scalar (integer-returning flavours), bind scalar functions directly to their _cy Cython implementations while preserving original docstrings and signatures. Eliminates ~18% (and up to 50%+ on ARM) latency on scalar calls. Fixes #501. --- src/h3/api/basic_int/__init__.py | 22 ++++++++++++++++++++ tests/test_lib/test_apis/test_basic_int.py | 22 ++++++++++++++++++++ tests/test_lib/test_apis/test_memview_int.py | 14 +++++++++++++ tests/test_lib/test_apis/test_numpy_int.py | 14 +++++++++++++ 4 files changed, 72 insertions(+) diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index ef82792..6ecf358 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -1365,3 +1365,25 @@ def is_valid_vertex(v): return _cy.is_valid_vertex(v) except (ValueError, TypeError): return False + + +if _out_scalar is _in_scalar: + # When _out_scalar is identity (basic_int, numpy_int, memview_int), + # bind scalar functions directly to their _cy counterparts to eliminate + # Python call frame and identity wrapper overhead (Issue #501). + for _name in ( + 'latlng_to_cell', + 'cell_to_parent', + 'cell_to_center_child', + 'cells_to_directed_edge', + 'get_directed_edge_origin', + 'get_directed_edge_destination', + 'directed_edge_to_cells', + 'local_ij_to_cell', + 'cell_to_vertex', + ): + _fn = globals()[_name] + _cy_fn = getattr(_cy, _name) + _cy_fn.__doc__ = _fn.__doc__ + globals()[_name] = _cy_fn + del _name, _fn, _cy_fn diff --git a/tests/test_lib/test_apis/test_basic_int.py b/tests/test_lib/test_apis/test_basic_int.py index a567b3d..3f3b14c 100644 --- a/tests/test_lib/test_apis/test_basic_int.py +++ b/tests/test_lib/test_apis/test_basic_int.py @@ -32,3 +32,25 @@ def test_compact_cells(): cells = h3.cell_to_children(h) assert h3.compact_cells(cells) == [h] + + +def test_identity_scalar_bindings(): + """ + Ensure scalar functions in int APIs are bound directly to _cy implementations + to eliminate wrapper and identity call overhead (Issue #501). + """ + from h3 import _cy + + assert h3.latlng_to_cell is _cy.latlng_to_cell + assert h3.cell_to_parent is _cy.cell_to_parent + assert h3.cell_to_center_child is _cy.cell_to_center_child + assert h3.cells_to_directed_edge is _cy.cells_to_directed_edge + assert h3.get_directed_edge_origin is _cy.get_directed_edge_origin + assert h3.get_directed_edge_destination is _cy.get_directed_edge_destination + assert h3.directed_edge_to_cells is _cy.directed_edge_to_cells + assert h3.local_ij_to_cell is _cy.local_ij_to_cell + assert h3.cell_to_vertex is _cy.cell_to_vertex + + # Ensure docstrings and signatures are intact + assert h3.latlng_to_cell.__doc__ is not None + assert 'latlng_to_cell' in h3.latlng_to_cell.__name__ diff --git a/tests/test_lib/test_apis/test_memview_int.py b/tests/test_lib/test_apis/test_memview_int.py index 0523794..f608f54 100644 --- a/tests/test_lib/test_apis/test_memview_int.py +++ b/tests/test_lib/test_apis/test_memview_int.py @@ -23,3 +23,17 @@ def test_line(): ] assert list(out) == expected + + +def test_identity_scalar_bindings(): + from h3 import _cy + + assert h3.latlng_to_cell is _cy.latlng_to_cell + assert h3.cell_to_parent is _cy.cell_to_parent + assert h3.cell_to_center_child is _cy.cell_to_center_child + assert h3.cells_to_directed_edge is _cy.cells_to_directed_edge + assert h3.get_directed_edge_origin is _cy.get_directed_edge_origin + assert h3.get_directed_edge_destination is _cy.get_directed_edge_destination + assert h3.directed_edge_to_cells is _cy.directed_edge_to_cells + assert h3.local_ij_to_cell is _cy.local_ij_to_cell + assert h3.cell_to_vertex is _cy.cell_to_vertex diff --git a/tests/test_lib/test_apis/test_numpy_int.py b/tests/test_lib/test_apis/test_numpy_int.py index c341b55..6bcd0b6 100644 --- a/tests/test_lib/test_apis/test_numpy_int.py +++ b/tests/test_lib/test_apis/test_numpy_int.py @@ -50,3 +50,17 @@ def test_numpy_str(): got = [h3.str_to_int(c) for c in cells] assert expected == got + + +def test_identity_scalar_bindings(): + from h3 import _cy + + assert h3.latlng_to_cell is _cy.latlng_to_cell + assert h3.cell_to_parent is _cy.cell_to_parent + assert h3.cell_to_center_child is _cy.cell_to_center_child + assert h3.cells_to_directed_edge is _cy.cells_to_directed_edge + assert h3.get_directed_edge_origin is _cy.get_directed_edge_origin + assert h3.get_directed_edge_destination is _cy.get_directed_edge_destination + assert h3.directed_edge_to_cells is _cy.directed_edge_to_cells + assert h3.local_ij_to_cell is _cy.local_ij_to_cell + assert h3.cell_to_vertex is _cy.cell_to_vertex From c0e89d0ff9e25e90a679d1da6bd01aac114e6983 Mon Sep 17 00:00:00 2001 From: kwy404 Date: Thu, 1 Oct 2026 18:48:06 -0300 Subject: [PATCH 170/177] fix: validate LatLngPoly loop length after dropping the closing point --- src/h3/_h3shape.py | 2 +- tests/test_lib/polyfill/test_polygon_class.py | 13 +++++++++++++ 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py index a8146df..b778fd6 100644 --- a/src/h3/_h3shape.py +++ b/src/h3/_h3shape.py @@ -54,7 +54,7 @@ class LatLngPoly(H3Shape): def __init__(self, outer, *holes): loops = [outer] + list(holes) for loop in loops: - if len(loop) in (1, 2): + if len(loop) > 0 and len(_open_ring(loop)) < 3: raise ValueError('Non-empty LatLngPoly loops need at least 3 points.') point_dimensions = set(map(len, loop)) diff --git a/tests/test_lib/polyfill/test_polygon_class.py b/tests/test_lib/polyfill/test_polygon_class.py index 59e8da2..a3639b6 100644 --- a/tests/test_lib/polyfill/test_polygon_class.py +++ b/tests/test_lib/polyfill/test_polygon_class.py @@ -50,3 +50,16 @@ def test_bad_subclass(): with pytest.raises(ValueError): h3.h3shape_to_cells_experimental(shoop, res=9) + + +def test_closed_loop_with_too_few_points(): + # a closed loop of 3 points only has 2 distinct points once the + # repeated closing point is removed + a, b = (37.68, -122.54), (37.82, -122.34) + outer = [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)] + + with pytest.raises(ValueError, match='at least 3 points'): + h3.LatLngPoly([a, b, a]) + + with pytest.raises(ValueError, match='at least 3 points'): + h3.LatLngPoly(outer, [a, b, a]) From 93b40427d04993957fc3820b401ed8e0652eb1cc Mon Sep 17 00:00:00 2001 From: Shaan Majid <70789625+shaanmajid@users.noreply.github.com> Date: Fri, 9 Oct 2026 17:49:47 -0700 Subject: [PATCH 171/177] Add CI test and build for Python 3.15 and 3.15t --- .github/workflows/tests.yml | 2 +- .github/workflows/wheels.yml | 20 +++++++++++++++++++- CHANGELOG.md | 1 + pyproject.toml | 1 + 4 files changed, 22 insertions(+), 2 deletions(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index f3dcc3c..f7a9854 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -14,7 +14,7 @@ jobs: strategy: matrix: os: [macos-latest, windows-latest, ubuntu-22.04] - python-version: ['3.10', '3.11', '3.12', '3.13', '3.14', '3.14t'] + python-version: ['3.10', '3.11', '3.12', '3.13', '3.14', '3.14t', '3.15', '3.15t'] steps: - uses: actions/checkout@v6.0.2 diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index b9bc985..1de5a80 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -83,6 +83,12 @@ jobs: - os: windows-11-arm build: 'cp314t-win_arm64' name: Windows ARM64 3.14t + - os: windows-11-arm + build: 'cp315-win_arm64' + name: Windows ARM64 3.15 + - os: windows-11-arm + build: 'cp315t-win_arm64' + name: Windows ARM64 3.15t - os: ubuntu-22.04 build: 'cp*-manylinux_x86_64' @@ -106,6 +112,12 @@ jobs: - os: ubuntu-22.04 build: 'cp314t-musllinux_x86_64' name: Linux Intel musl 64-bit 3.14t + - os: ubuntu-22.04 + build: 'cp315-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.15 + - os: ubuntu-22.04 + build: 'cp315t-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.15t - os: ubuntu-22.04 build: 'cp310-manylinux_aarch64' @@ -125,6 +137,12 @@ jobs: - os: ubuntu-22.04 build: 'cp314t-manylinux_aarch64' name: Linux Aarch64 3.14t + - os: ubuntu-22.04 + build: 'cp315-manylinux_aarch64' + name: Linux Aarch64 3.15 + - os: ubuntu-22.04 + build: 'cp315t-manylinux_aarch64' + name: Linux Aarch64 3.15t steps: - uses: actions/checkout@v6.0.2 @@ -158,7 +176,7 @@ jobs: with: platforms: aarch64 - - uses: pypa/cibuildwheel@v3.3.1 + - uses: pypa/cibuildwheel@v4.2.1 env: CIBW_BUILD_FRONTEND: 'build[uv]' CIBW_TEST_REQUIRES: pytest pytest-cov numpy diff --git a/CHANGELOG.md b/CHANGELOG.md index 7ad11bf..9f23b02 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ avoid adding features or APIs which do not map onto the ## Unreleased - Fix wheels for Python 3.14.6 free-threading +- Add Python 3.15 and 3.15t wheels ## [4.5.0] - 2026-05-29 diff --git a/pyproject.toml b/pyproject.toml index 2474f88..4430799 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,6 +30,7 @@ classifiers = [ 'Programming Language :: Python :: 3.12', 'Programming Language :: Python :: 3.13', 'Programming Language :: Python :: 3.14', + 'Programming Language :: Python :: 3.15', 'Programming Language :: Python :: Free Threading', 'Operating System :: MacOS :: MacOS X', 'Operating System :: POSIX :: Linux', From b19b0421fe4629479c14cf367db040730e6f1238 Mon Sep 17 00:00:00 2001 From: kwy404 Date: Sat, 10 Oct 2026 21:26:03 -0300 Subject: [PATCH 172/177] fix: return False from is_valid_* for indexes outside the uint64 range --- src/h3/api/basic_int/__init__.py | 8 ++++---- tests/test_lib/test_cells_and_edges.py | 8 ++++++++ 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index ef82792..0c62a74 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -139,7 +139,7 @@ def is_valid_index(h): try: h = _in_scalar(h) return _cy.is_valid_index(h) - except (ValueError, TypeError): + except (ValueError, TypeError, OverflowError): return False @@ -154,7 +154,7 @@ def is_valid_cell(h): try: h = _in_scalar(h) return _cy.is_valid_cell(h) - except (ValueError, TypeError): + except (ValueError, TypeError, OverflowError): return False @@ -169,7 +169,7 @@ def is_valid_directed_edge(edge): try: e = _in_scalar(edge) return _cy.is_valid_directed_edge(e) - except (ValueError, TypeError): + except (ValueError, TypeError, OverflowError): return False @@ -1363,5 +1363,5 @@ def is_valid_vertex(v): try: v = _in_scalar(v) return _cy.is_valid_vertex(v) - except (ValueError, TypeError): + except (ValueError, TypeError, OverflowError): return False diff --git a/tests/test_lib/test_cells_and_edges.py b/tests/test_lib/test_cells_and_edges.py index 9b1907e..65d9d13 100644 --- a/tests/test_lib/test_cells_and_edges.py +++ b/tests/test_lib/test_cells_and_edges.py @@ -480,6 +480,14 @@ def test_edge_is_valid_fail(): assert not h3.is_valid_directed_edge(e_invalid) +def test_is_valid_out_of_uint64_range(): + for h in ['10000000000000000', '-1']: + assert not h3.is_valid_index(h) + assert not h3.is_valid_cell(h) + assert not h3.is_valid_directed_edge(h) + assert not h3.is_valid_vertex(h) + + def test_get_pentagons(): out = h3.get_pentagons(0) From f423ef9b8dff9f000cf257d91290a056fe32cf59 Mon Sep 17 00:00:00 2001 From: Sebastian Turner Date: Mon, 19 Oct 2026 15:56:52 -0700 Subject: [PATCH 173/177] Support rads units in average_hexagon_area and average_hexagon_edge_length Signed-off-by: Sebastian Turner --- CHANGELOG.md | 1 + src/h3/_cy/cells.pyx | 5 ++++- src/h3/_cy/edges.pyx | 5 ++++- src/h3/_cy/util.pyx | 4 ++++ tests/test_lib/test_length_area.py | 24 ++++++++++++++++++++++++ 5 files changed, 37 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9f23b02..34856a9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ avoid adding features or APIs which do not map onto the ## Unreleased - Fix wheels for Python 3.14.6 free-threading - Add Python 3.15 and 3.15t wheels +- Support `unit='rads'` in `average_hexagon_area` and `average_hexagon_edge_length` (#509) ## [4.5.0] - 2026-05-29 diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 8b84f9d..f0667e5 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -8,6 +8,8 @@ from .util cimport ( check_distance, ) +from .util import EARTH_RADIUS_KM + from .error_system cimport ( H3Error, check_for_error, @@ -322,7 +324,8 @@ cpdef double average_hexagon_area(int resolution, unit='km^2') except -1: # todo: multiple units convert = { 'km^2': 1.0, - 'm^2': 1000*1000.0 + 'm^2': 1000*1000.0, + 'rads^2': 1.0/(EARTH_RADIUS_KM*EARTH_RADIUS_KM), } try: diff --git a/src/h3/_cy/edges.pyx b/src/h3/_cy/edges.pyx index 1d2ef74..7364bd5 100644 --- a/src/h3/_cy/edges.pyx +++ b/src/h3/_cy/edges.pyx @@ -4,6 +4,8 @@ from .h3lib cimport bool, H3int from .error_system cimport check_for_error +from .util import EARTH_RADIUS_KM + from .memory cimport H3MemoryManager # todo: make bint @@ -86,7 +88,8 @@ cpdef double average_hexagon_edge_length(int resolution, unit='km') except -1: # todo: multiple units convert = { 'km': 1.0, - 'm': 1000.0 + 'm': 1000.0, + 'rads': 1.0/EARTH_RADIUS_KM, } try: diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index 06823d0..74e8f80 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -19,6 +19,10 @@ from .error_system import ( H3IndexInvalidError, ) +# Must match EARTH_RADIUS_KM in h3lib's constants.h, which is not part of the +# public h3api.h header. Used to convert km based averages to radians. +EARTH_RADIUS_KM = 6371.007180918475 + cdef h3lib.LatLng deg2coord(double lat, double lng) nogil: cdef: h3lib.LatLng c diff --git a/tests/test_lib/test_length_area.py b/tests/test_lib/test_length_area.py index 1003f56..ca38257 100644 --- a/tests/test_lib/test_length_area.py +++ b/tests/test_lib/test_length_area.py @@ -86,6 +86,30 @@ def test_areas_at_00(): assert u.approx2(out, areas_rads2) +def test_average_hexagon_area_rads(): + # the ratio between km^2 and rads^2 should match the one used by cell_area + h = '89754e64993ffff' + ratio = h3.cell_area(h, unit='km^2') / h3.cell_area(h, unit='rads^2') + + for res in range(16): + km2 = h3.average_hexagon_area(res, unit='km^2') + rads2 = h3.average_hexagon_area(res, unit='rads^2') + + assert km2 / rads2 == pytest.approx(ratio) + + +def test_average_hexagon_edge_length_rads(): + # the ratio between km and rads should match the one used by edge_length + e = '139754e64993ffff' + ratio = h3.edge_length(e, unit='km') / h3.edge_length(e, unit='rads') + + for res in range(16): + km = h3.average_hexagon_edge_length(res, unit='km') + rads = h3.average_hexagon_edge_length(res, unit='rads') + + assert km / rads == pytest.approx(ratio) + + def test_bad_units(): h = '89754e64993ffff' e = '139754e64993ffff' From 1c84623b1222ee121c91937d73d6a7969bbe7c07 Mon Sep 17 00:00:00 2001 From: Sebastian Turner Date: Tue, 20 Oct 2026 16:47:26 -0700 Subject: [PATCH 174/177] Handle empty GeoJSON Polygon in geo_to_h3shape Signed-off-by: Sebastian Turner --- src/h3/_h3shape.py | 4 ++++ tests/test_lib/polyfill/test_h3.py | 12 ++++++++++++ 2 files changed, 16 insertions(+) diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py index b778fd6..68d18c2 100644 --- a/src/h3/_h3shape.py +++ b/src/h3/_h3shape.py @@ -223,6 +223,10 @@ def _remove_z(ll1): def _LL2_to_polygon(ll2): + if len(ll2) == 0: + # empty GeoJSON Polygon, like `shapely.Polygon().__geo_interface__` + return LatLngPoly([]) + ll2 = [ _remove_z(ll1) for ll1 in ll2 diff --git a/tests/test_lib/polyfill/test_h3.py b/tests/test_lib/polyfill/test_h3.py index fed297f..3021fba 100644 --- a/tests/test_lib/polyfill/test_h3.py +++ b/tests/test_lib/polyfill/test_h3.py @@ -307,6 +307,18 @@ def test_geo_to_h3shape_rejects_non_dict(): h3.geo_to_h3shape('not a geo object') +def test_geo_to_h3shape_empty_polygon(): + # e.g., shapely.Polygon().__geo_interface__ + geo = MockGeoInterface({'type': 'Polygon', 'coordinates': ()}) + + shape = h3.geo_to_h3shape(geo) + assert isinstance(shape, h3.LatLngPoly) + assert shape.outer == () + assert shape.holes == () + + assert h3.geo_to_cells(geo, 9) == [] + + def test_polyfill_down_under(): sydney = [ (-33.8556, 151.1979), From 8db9a2f9626d5cf4d1f7cf936e040bf4d66ad845 Mon Sep 17 00:00:00 2001 From: kwy404 Date: Fri, 23 Oct 2026 17:40:02 -0300 Subject: [PATCH 175/177] fix: don't return a cell twice from h3shape_to_cells_experimental for a LatLngMultiPoly --- src/h3/_cy/latlng.pyx | 8 ++++++-- tests/test_lib/polyfill/test_h3.py | 14 ++++++++++++++ 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/src/h3/_cy/latlng.pyx b/src/h3/_cy/latlng.pyx index 1593d43..630d3ad 100644 --- a/src/h3/_cy/latlng.pyx +++ b/src/h3/_cy/latlng.pyx @@ -262,11 +262,15 @@ def polygons_to_cells_experimental(polygons, int res, int flag): # probably super inefficient, but it is working! # tood: move this to C + # a cell can overlap more than one polygon, so skip the ones already added + seen = set() k = 0 for mv in mvs: for v in mv: - hmm.ptr[k] = v - k += 1 + if v not in seen: + seen.add(v) + hmm.ptr[k] = v + k += 1 return hmm.to_mv() diff --git a/tests/test_lib/polyfill/test_h3.py b/tests/test_lib/polyfill/test_h3.py index fed297f..a6966b9 100644 --- a/tests/test_lib/polyfill/test_h3.py +++ b/tests/test_lib/polyfill/test_h3.py @@ -207,6 +207,20 @@ def test_poly_to_cells_experimental_mpoly(): )) +def test_poly_to_cells_experimental_mpoly_no_duplicates(): + # cells that overlap both polygons should only be returned once + a = h3.LatLngPoly([(37.70, -122.50), (37.70, -122.45), (37.75, -122.45)]) + b = h3.LatLngPoly([(37.70, -122.449), (37.70, -122.40), (37.75, -122.40)]) + mpoly = h3.LatLngMultiPoly(a, b) + + out = h3.h3shape_to_cells_experimental(mpoly, res=7, contain='overlap') + + expected = set(h3.h3shape_to_cells_experimental(a, res=7, contain='overlap')) + expected |= set(h3.h3shape_to_cells_experimental(b, res=7, contain='overlap')) + assert len(out) == len(expected) + assert set(out) == expected + + def test_polyfill_with_hole(): poly = h3.LatLngPoly(sf_7x7, sf_hole1) From 9a26dc64775804a8b578fe07268124e098ccfa4a Mon Sep 17 00:00:00 2001 From: Jongbin Jung Date: Fri, 13 Nov 2026 14:02:49 -0800 Subject: [PATCH 176/177] Add missing items from changelog --- CHANGELOG.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 34856a9..0b6ee3a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,8 +16,15 @@ avoid adding features or APIs which do not map onto the ## Unreleased - Fix wheels for Python 3.14.6 free-threading -- Add Python 3.15 and 3.15t wheels +- Add Python 3.14t, 3.15 and 3.15t wheels - Support `unit='rads'` in `average_hexagon_area` and `average_hexagon_edge_length` (#509) +- Add `container` option to `h3shape_to_geo` (#495) +- Fix Android cross-compilation with Buildozer (#494) +- Raise `ValueError` instead of `assert` in `geo_to_h3shape` (#500, #502) +- Fix `LatLngPoly` loop length check for closed rings (#505) +- Return `False` from `is_valid_*` for out-of-range integers (#507) +- Handle empty GeoJSON Polygon in `geo_to_h3shape` (#511) +- Fix duplicate cells from `h3shape_to_cells_experimental` for `LatLngMultiPoly` (#512) ## [4.5.0] - 2026-05-29 From bec9b81090864db890ede0558104a5877df6ebdb Mon Sep 17 00:00:00 2001 From: Jongbin Jung Date: Fri, 13 Nov 2026 15:43:39 -0800 Subject: [PATCH 177/177] Exclude identity-binding block from coverage The block added in #504 only runs when `_out_scalar is _in_scalar`, which is true for basic_int, numpy_int, and memview_int, but not for basic_str. Coverage is only measured on the basic_str copy of the shared API file, so the block showed up as uncovered and failed the 100% coverage gate on master. Co-Authored-By: Claude Code --- src/h3/api/basic_int/__init__.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index 6f36e77..8eac4b1 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -1367,10 +1367,13 @@ def is_valid_vertex(v): return False -if _out_scalar is _in_scalar: +if _out_scalar is _in_scalar: # pragma: no cover # When _out_scalar is identity (basic_int, numpy_int, memview_int), # bind scalar functions directly to their _cy counterparts to eliminate # Python call frame and identity wrapper overhead (Issue #501). + # + # Coverage is only measured on the basic_str copy of this file, where + # this branch is never taken; it is exercised by the int API tests. for _name in ( 'latlng_to_cell', 'cell_to_parent',