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..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/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/makefile b/makefile index 6e44c02..44eceb8 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 @@ -23,6 +22,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/__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 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..e61bb4e 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -69,10 +69,33 @@ from .util import ( c_version, hex2int, int2hex, - from_iter, +) + +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.pyx b/src/h3/_cy/cells.pyx index 4206b81..2a05cd2 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -1,17 +1,21 @@ 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 @@ -24,15 +28,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,35 +47,44 @@ 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 + check_cell(h1) check_cell(h2) - d = h3lib.h3Distance(h1,h2) + check_for_error( + h3lib.gridDistance(h1, h2, &distance) + ) # todo: should this raise a distance error? - if d < 0: - s = 'Cells are too far apart to compute distance: {} and {}' - s = s.format(hex(h1), hex(h2)) - raise H3ValueError(s) + # s = 'Cells are too far apart to compute distance: {} and {}' - return d + return distance cpdef H3int[:] 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,30 +94,33 @@ 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 @@ -114,93 +132,101 @@ 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 parent(H3int h, res=None) except 0: - check_cell(h) + cdef: + H3int parent + + 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_for_error_msg(err, msg) - check_res(res) + return parent - return h3lib.h3ToParent(h, res) cpdef H3int[:] children(H3int h, res=None): + cdef: + 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_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: + cdef: + H3int child + 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_for_error_msg(err, msg) - check_res(res) - - return h3lib.h3ToCenterChild(h, res) + return child 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 # 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): @@ -209,38 +235,56 @@ 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: + 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 + ) + ) + + # todo: again! doesn't work if i have this before the error check! + # why isn't hmm.to_mv() robust to failures before it? + mv = hmm.to_mv() return mv cpdef int64_t num_hexagons(int resolution) except -1: - check_res(resolution) + 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) + cdef: + double area - area = h3lib.hexAreaKm2(resolution) + check_for_error( + h3lib.getHexagonAreaAvgKm2(resolution, &area) + ) # todo: multiple units convert = { @@ -251,125 +295,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 +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): - check_cell(start) - check_cell(end) + cdef: + int64_t n - n = h3lib.h3LineSize(start, 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 n < 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) - ptr = create_ptr(n) - flag = h3lib.h3Line(start, end, ptr) - mv = create_mv(ptr, n) + hmm = H3MemoryManager(n) + err = h3lib.gridPathCells(start, end, hmm.ptr) - 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) + + # 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) + 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() + 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_faces(H3int h): - check_cell(h) + cdef: + int n + int[:] faces ## todo: weird, this needs to be specified to avoid errors. cython bug? - n = h3lib.maxFaceCount(h) + check_for_error( + h3lib.maxFaceCount(h, &n) + ) - cdef int* ptr = stdlib.calloc(n, sizeof(int)) - if (n > 0) and (not ptr): - raise MemoryError() + faces = int_mv(n) + check_for_error( + h3lib.getIcosahedronFaces(h, &faces[0]) + ) - h3lib.h3GetFaces(h, ptr) + # 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 *: 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: 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..bf4c5c4 100644 --- a/src/h3/_cy/edges.pxd +++ b/src/h3/_cy/edges.pxd @@ -1,7 +1,7 @@ from .h3lib cimport bool, H3int cpdef bool are_neighbors(H3int h1, H3int h2) -cpdef H3int edge(H3int origin, H3int destination) except 1 +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 diff --git a/src/h3/_cy/edges.pyx b/src/h3/_cy/edges.pyx index 6560006..7f1701e 100644 --- a/src/h3/_cy/edges.pyx +++ b/src/h3/_cy/edges.pyx @@ -1,71 +1,81 @@ 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 +# todo: make bint cpdef bool are_neighbors(H3int h1, H3int h2): - check_cell(h1) - check_cell(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 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 + 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) + cdef: + H3int out - return h3lib.getOriginH3IndexFromUnidirectionalEdge(e) + check_for_error( + h3lib.getDirectedEdgeOrigin(e, &out) + ) + + return out cpdef H3int edge_destination(H3int e) except 1: - check_edge(e) + cdef: + H3int out - return h3lib.getDestinationH3IndexFromUnidirectionalEdge(e) + check_for_error( + 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.getH3UnidirectionalEdgesFromHexagon(origin, ptr) - mv = create_mv(ptr, 6) + hmm = H3MemoryManager(6) + 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) + cdef: + double length - length = h3lib.edgeLengthKm(resolution) + h3lib.getHexagonEdgeLengthAvgKm(resolution, &length) # todo: multiple units convert = { @@ -76,25 +86,26 @@ 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) + cdef: + double length # 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) + h3lib.exactEdgeLengthRads(e, &length) elif unit == 'km': - length = h3lib.exactEdgeLengthKm(e) + h3lib.exactEdgeLengthKm(e, &length) elif unit == 'm': - length = h3lib.exactEdgeLengthM(e) + 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 dc2c1d7..f6a5221 100644 --- a/src/h3/_cy/geo.pyx +++ b/src/h3/_cy/geo.pyx @@ -1,51 +1,68 @@ +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: 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 *: """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(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 + 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 @@ -53,11 +70,12 @@ cdef h3lib.Geofence make_geofence(geos, bool lnglat_order=False) except *: If False, assume coordinate pairs like (lat, lng) """ cdef: - h3lib.Geofence gf + h3lib.GeoLoop gl - gf.numVerts = len(geos) + gl.numVerts = len(geos) - gf.verts = stdlib.calloc(gf.numVerts, sizeof(h3lib.GeoCoord)) + # todo: need for memory management + gl.verts = h3_calloc(gl.numVerts, sizeof(h3lib.LatLng)) if lnglat_order: latlng = (g[::-1] for g in geos) @@ -65,14 +83,14 @@ cdef h3lib.Geofence make_geofence(geos, bool lnglat_order=False) except *: latlng = geos for i, (lat, lng) in enumerate(latlng): - gf.verts[i] = deg2coord(lat, lng) + 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): + h3_free(gl.verts) + gl.verts = NULL cdef class GeoPolygon: @@ -85,12 +103,12 @@ cdef class GeoPolygon: 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 + A sequence of GeoLoops lnglat_order : bool If True, assume coordinate pairs like (lng, lat) If False, assume coordinate pairs like (lat, lng) @@ -99,23 +117,23 @@ cdef class GeoPolygon: if holes is None: holes = [] - self.gp.geofence = make_geofence(outer, lnglat_order) + 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)) + 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, lnglat_order) 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): @@ -143,15 +161,21 @@ def polyfill_polygon(outer, int res, holes=None, bool lnglat_order=False): 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) - 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 @@ -216,11 +240,11 @@ def polyfill(dict geojson, int res, bool geo_json_conformant=False): def cell_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]) @@ -236,16 +260,16 @@ def cell_boundary(H3int h, bool geo_json=False): def edge_boundary(H3int edge, bool geo_json=False): - """ Returns the GeoBoundary containing the coordinates of the edge + """ 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) @@ -267,12 +291,12 @@ cpdef double point_dist( b = deg2coord(lat2, lng2) if unit == 'rads': - d = h3lib.pointDistRads(&a, &b) + d = h3lib.distanceRads(&a, &b) elif unit == 'km': - d = h3lib.pointDistKm(&a, &b) + d = h3lib.distanceKm(&a, &b) elif unit == 'm': - d = h3lib.pointDistM(&a, &b) + 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 5fa05cc..ec225bd 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -1,168 +1,180 @@ -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 = 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 - int pentagonIndexCount() + H3Error getHexagonEdgeLengthAvgKm(int res, double *out) nogil + H3Error getHexagonEdgeLengthAvgM(int res, double *out) nogil - void getPentagonIndexes(int res, H3Index *out) + H3Error exactEdgeLengthRads(H3int edge, double *out) nogil + H3Error exactEdgeLengthKm(H3int edge, double *out) nogil + H3Error exactEdgeLengthM(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 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 - H3Index h3ToCenterChild(H3Index h, int res) + H3Error cellsToLinkedMultiPolygon(const H3int *h3Set, const int numHexes, 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 numHexes, 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..31aecd0 --- /dev/null +++ b/src/h3/_cy/memory.pxd @@ -0,0 +1,22 @@ +from .h3lib cimport H3int + +cdef class H3MemoryManager: + cdef: + size_t n + H3int* ptr + + cdef H3int[:] to_mv(self) + +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 + +## things i'm not happy about with this current situation + +- 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 new file mode 100644 index 0000000..0e406b4 --- /dev/null +++ b/src/h3/_cy/memory.pyx @@ -0,0 +1,210 @@ +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`. + 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 + + 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 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) + + +""" +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 = h3_calloc(n, sizeof(int)) + if ptr is NULL: + raise MemoryError() + + arr = ptr + arr.callback_free_data = h3_free + + return arr + + +cdef H3int[:] simple_mv(size_t n): + # cdef: + # array mv + + if n == 0: + return empty_memory_view() + + ptr = h3_calloc(n, sizeof(H3int)) + if not ptr: + raise MemoryError() + + mv = ptr + mv.callback_free_data = h3_free + + return mv + + +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? + """ + # cdef array x # this needs to be commented out to avoid an error + + mv = simple_mv(len(hexes)) + + for i,h in enumerate(hexes): + mv[i] = h + + return mv diff --git a/src/h3/_cy/to_multipoly.pyx b/src/h3/_cy/to_multipoly.pyx index 8e5ca55..7a421f7 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)] @@ -39,13 +39,13 @@ def _to_multi_polygon(const H3int[:] hexes): 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) # 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 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..750316b 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 +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) -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 dbf17da..16c6df4 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) @@ -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). @@ -77,121 +66,19 @@ cdef check_cell(H3int h): 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/_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..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/src/h3/api/basic_int/_binding.py b/src/h3/api/basic_int/_binding.py index a232287..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.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 765fdbb..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.from_iter(it) + return _cy.iter_to_mv(it) def _out_unordered(mv): 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..a36c614 160000 --- a/src/h3lib +++ b/src/h3lib @@ -1 +1 @@ -Subproject commit ee292a96906767162f2f530b46fc2428b2555748 +Subproject commit a36c614b477fb5409a0a87e0111d347ce550e40d diff --git a/tests/test_cells_and_edges.py b/tests/test_cells_and_edges.py index 173033a..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) @@ -269,11 +293,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 = { @@ -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 4739009..58faaff 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)) @@ -209,10 +211,10 @@ def test_resolution(): 'coordinates': [[]], } - with pytest.raises(h3.H3ResolutionError): + with pytest.raises(H3ResDomainError): h3.polyfill(d, -1) - with pytest.raises(h3.H3ResolutionError): + with pytest.raises(H3ResDomainError): 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)