diff --git a/website/docs/api/directededge.mdx b/website/docs/api/directededge.mdx index 0be79a897..833fd183c 100644 --- a/website/docs/api/directededge.mdx +++ b/website/docs/api/directededge.mdx @@ -13,6 +13,8 @@ edge from one cell to a neighboring cell. ## areNeighborCells +Determines whether or not the provided H3 cells are neighbors. + @@ -83,12 +89,12 @@ true -Returns whether or not the provided H3 cell indexes are neighbors. - -`out` will be 1 if the indexes are neighbors, 0 otherwise. ## cellsToDirectedEdge +Provides a directed edge H3 index based on the provided origin and +destination. + @@ -159,13 +167,10 @@ $ h3 cellsToDirectedEdge -o 85283473fffffff -d 85283477fffffff -Returns a unidirectional edge H3 index based on the provided origin and -destination. - -Returns 0 on success. - ## isValidDirectedEdge +Determines if the provided H3Index is a valid unidirectional edge index. + @@ -234,12 +241,10 @@ true -Determines if the provided H3Index is a valid unidirectional edge index. - -Returns 1 if it is a unidirectional edge H3Index, otherwise 0. - ## getDirectedEdgeOrigin +Provides the origin hexagon from the directed edge H3Index. + @@ -308,10 +315,10 @@ $ h3 getDirectedEdgeOrigin -c 115283473fffffff -Returns the origin hexagon from the unidirectional edge H3Index. - ## getDirectedEdgeDestination +Provides the destination hexagon from the directed edge H3Index. + @@ -380,10 +389,11 @@ $ h3 getDirectedEdgeDestination -c 115283473fffffff -Returns the destination hexagon from the unidirectional edge H3Index. ## directedEdgeToCells +Provides the origin-destination pair of cells for the given directed edge. + @@ -452,11 +467,10 @@ $ h3 directedEdgeToCells -c 115283473fffffff -Returns the origin, destination pair of hexagon IDs for the given edge ID, which are placed at `originDestination[0]` and -`originDestination[1]` respectively. - ## originToDirectedEdges +Provides all of the directed edges from the current cell. + @@ -525,12 +545,12 @@ $ h3 originToDirectedEdges -c 85283473fffffff -Provides all of the directed edges from the current H3Index. `edges` must be of length 6, -and the number of directed edges placed in the array may be less than 6. If this is the case, -one of the members of the array will be `0`. ## directedEdgeToBoundary +Provides the geographic lat/lng coordinates defining the directed edge. +Note that this may be more than two points for complex edges. + @@ -574,7 +596,7 @@ function example() { ```py -h3.directed_edge_to_boundary(edge, geo_json=False) +h3.directed_edge_to_boundary(edge) ``` @@ -598,5 +620,3 @@ $ h3 directedEdgeToBoundary -c 115283473fffffff - -Provides the coordinates defining the unidirectional edge. diff --git a/website/docs/api/hierarchy.mdx b/website/docs/api/hierarchy.mdx index 95c007da2..c922b09f2 100644 --- a/website/docs/api/hierarchy.mdx +++ b/website/docs/api/hierarchy.mdx @@ -8,10 +8,16 @@ slug: /api/hierarchy import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -These functions permit moving between resolutions in the H3 grid system. The functions produce parent cells (coarser), or child cells (finer). +These functions permit moving between resolutions in the H3 grid system. +The functions produce parent cells (coarser), or child cells (finer). ## cellToParent +Provides the unique ancestor (coarser) cell of the given `cell` for +the provided resolution. If the input cell has resolution `r`, then +`parentRes = r - 1` would give the immediate parent, +`parentRes = r - 2` would give the grandparent, and so on. + @@ -55,9 +63,12 @@ function example() { ```py -h3.cell_to_parent(cell, parent_res) +h3.cell_to_parent(h, res=None) ``` +If `res = None`, we set `res = resolution(h) - 1`. +See the [h3-py docs](https://uber.github.io/h3-py/api_verbose.html#h3.cell_to_parent). + @@ -81,12 +92,12 @@ $ h3 cellToParent -c 85283473fffffff -r 4 -Provides the parent (coarser) index containing `cell`. - -Returns 0 (`E_SUCCESS`) on success. ## cellToChildren +Provides the children (descendant) cells of `cell` at +resolution `childRes`. + @@ -130,9 +145,12 @@ function example() { ```py -h3.cell_to_children(cell, child_res) +h3.cell_to_children(h, res=None) ``` +If `res = None`, we set `res = resolution(h) + 1`. +See the [h3-py docs](https://uber.github.io/h3-py/api_verbose.html#h3.cell_to_children). + @@ -156,12 +174,11 @@ $ h3 cellToChildren -c 85283473fffffff -r 6 -Populates `children` with the indexes contained by `cell` at resolution `childRes`. `children` must be an array of at least size `cellToChildrenSize(cell, childRes)`. - -Returns 0 (`E_SUCCESS`) on success. ## cellToChildrenSize +Provides the number of children at a given resolution of the given cell. + @@ -200,11 +221,14 @@ This function exists for memory management and is not exposed. -:::note -This function exists for memory management and is not exposed. +```py +h3.cell_to_children_size(h, res=None) +``` + +If `res = None`, we set `res = resolution(h) + 1`. +See the [h3-py docs](https://uber.github.io/h3-py/api_verbose.html#h3.cell_to_children_size). -::: @@ -228,12 +252,11 @@ $ h3 cellToChildrenSize -c 85283473fffffff -r 6 -Provides the size of the `children` array needed for the given inputs to `cellToChildren`. - -Returns 0 (`E_SUCCESS`) on success. ## cellToCenterChild +Provides the center child (finer) cell contained by `cell` at resolution `childRes`. + @@ -277,9 +303,12 @@ function example() { ```py -h3.cell_to_center_child(cell, child_res) +h3.cell_to_center_child(h, res=None) ``` +If `res = None`, we set `res = resolution(h) + 1`. +See the [h3-py docs](https://uber.github.io/h3-py/api_verbose.html#h3.cell_to_center_child). + @@ -303,12 +332,13 @@ $ h3 cellToCenterChild -c 85283473fffffff -r 7 -Provides the center child (finer) index contained by `cell` at resolution `childRes`. - -Returns 0 (`E_SUCCESS`) on success. ## cellToChildPos +Provides the position of the child cell within an ordered list of all children of the cell's parent at the specified resolution `parentRes`. +The order of the ordered list is the same as that returned by `cellToChildren`. +This is the complement of `childPosToCell`. + ```c -H3Index cellToChildPos(H3Index child, int parentRes, int64_t *out); +H3Error cellToChildPos(H3Index child, int parentRes, int64_t *out); ``` +Returns 0 (`E_SUCCESS`) on success. + @@ -352,7 +384,7 @@ function example() { ```py -h3.cell_to_child_pos(child, parent_res) +h3.cell_to_child_pos(child, res_parent) ``` @@ -377,12 +409,13 @@ $ h3 cellToChildPos -c 85283473fffffff -r 3 -Returns the position of the child cell within an ordered list of all children of the cell's parent at the specified resolution `parentRes`. The order of the ordered list is the same as that returned by `cellToChildren`. This is the complement of `childPosToCell`. - -Returns 0 (`E_SUCCESS`) on success. ## childPosToCell +Provides the child cell at a given position within an ordered list of all children of `parent` at the specified resolution `childRes`. +The order of the ordered list is the same as that returned by `cellToChildren`. +This is the complement of `cellToChildPos`. + ```c -H3Index childPosToCell(int64_t childPos, H3Index parent, int childRes, H3Index *child); +H3Error childPosToCell(int64_t childPos, H3Index parent, int childRes, H3Index *child); ``` +Returns 0 (`E_SUCCESS`) on success. + + @@ -427,7 +463,7 @@ function example() { ```py -h3.child_pos_to_cell(child_pos, parent, child_res) +h3.child_pos_to_cell(parent, res_child, child_pos) ``` @@ -454,12 +490,13 @@ $ h3 childPosToCell -p 42 -c 85283473fffffff -r 7 -Returns the child cell at a given position within an ordered list of all children of `parent` at the specified resolution `childRes`. The order of the ordered list is the same as that returned by `cellToChildren`. This is the complement of `cellToChildPos`. - -Returns 0 (`E_SUCCESS`) on success. ## compactCells +Compacts a collection of H3 cells by recursively replacing children cells +with their parents if all children are present. +Input cells must all share the same resolution. + @@ -530,12 +572,11 @@ $ h3 compactCells -c 85283473fffffff,85283447fffffff,8528347bfffffff,85283463fff -Compacts the set `cellSet` of indexes as best as possible, into the array `compactedSet`. `compactedSet` must be at least the size of `cellSet` in case the set cannot be compacted. Cells in `cellSet` must all share the same resolution. - -Returns 0 (`E_SUCCESS`) on success. - ## uncompactCells +Uncompacts the set `compactedSet` of indexes to the resolution `res`. +`h3Set` must be at least of size `uncompactCellsSize(compactedSet, numHexes, res)`. + @@ -608,12 +651,12 @@ $ h3 uncompactCells -r 5 -c 85283447fffffff,8528340ffffffff,8528340bfffffff,8528 -Uncompacts the set `compactedSet` of indexes to the resolution `res`. `h3Set` must be at least of size `uncompactCellsSize(compactedSet, numHexes, res)`. - -Returns 0 (`E_SUCCESS`) on success. ## uncompactCellsSize +Provides the total resulting number of cells if uncompacting a cell set to +a given resolution. + @@ -669,7 +716,3 @@ This function exists for memory management and is not exposed. - -Places the size of the array needed by `uncompactCells` into `out`. - -Returns 0 (`E_SUCCESS`) on success. diff --git a/website/docs/api/indexing.mdx b/website/docs/api/indexing.mdx index 5809b6794..674e0d666 100644 --- a/website/docs/api/indexing.mdx +++ b/website/docs/api/indexing.mdx @@ -8,10 +8,17 @@ slug: /api/indexing import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -These functions are used for finding the H3 cell index containing coordinates, and for finding the center and boundary of H3 indexes. +These functions are used for finding the H3 cell index containing coordinates, +and for finding the center and boundary of H3 cells. ## latLngToCell +Indexes the location at the specified resolution, +providing the index of the cell containing the location. +This buckets the geographic point into the H3 grid. +For more information, see the +[algorithm description](../core-library/latLngToCellDesc). + @@ -84,12 +93,16 @@ $ h3 latLngToCell --lat 45 --lng 40 -r 2 -Indexes the location at the specified resolution, returning the index of the cell containing the location. This buckets -the geographic point into the H3 grid. See the [algorithm description](../core-library/latLngToCellDesc) for more information. +## cellToLatLng -Returns 0 (`E_SUCCESS`) on success. +Finds the center of the cell in grid space. See the +[algorithm description](../core-library/cellToLatLngDesc) for +more information. -## cellToLatLng +The center will drift versus the centroid +of the cell on Earth due to distortion from the gnomonic +projection within the icosahedron face it resides on and its +distance from the center of the icosahedron face. @@ -159,19 +174,13 @@ $ h3 cellToLatLng -c 85283473fffffff -Finds the center of the cell in grid space. See the -[algorithm description](../core-library/cellToLatLngDesc) for -more information. - -The center will drift versus the centroid -of the cell on Earth due to distortion from the gnomonic -projection within the icosahedron face it resides on and its -distance from the center of the icosahedron face. - -Returns 0 (`E_SUCCESS`) on success. ## cellToBoundary +Finds the boundary of the cell. +For more information, see the +[algorithm description](../core-library/cellToBoundaryDesc). + @@ -215,9 +226,13 @@ function example() { ```py -h3.cell_to_boundary(cell, geo_json=False) +h3.cell_to_boundary(cell) ``` +Returns tuple of lat/lng tuples. +For GeoJSON compatibility (lng/lat order), see the +[`h3-py` docs](https://uber.github.io/h3-py/api_quick.html#polygon-interface). + @@ -239,10 +254,3 @@ $ h3 cellToBoundary -c 85283473fffffff - -Finds the boundary of the cell. See the -[algorithm description](../core-library/cellToBoundaryDesc) -for more information. - - -Returns 0 (`E_SUCCESS`) on success. diff --git a/website/docs/api/inspection.mdx b/website/docs/api/inspection.mdx index 53aadf62f..40b7844da 100644 --- a/website/docs/api/inspection.mdx +++ b/website/docs/api/inspection.mdx @@ -12,6 +12,9 @@ These functions provide metadata about an H3 index, such as its resolution or ba ## getResolution +Returns the resolution of the index. +(Works for cells, edges, and vertexes.) + -Returns the resolution of the index. ## getBaseCellNumber +Returns the base cell number of the index. +(Works for cells, edges, and vertexes.) + -Returns the base cell number of the index. - ## stringToH3 +Converts the string representation to `H3Index` (`uint64_t`) representation. + @@ -181,8 +188,12 @@ long stringToH3(String h3Address); +:::note + The H3 JavaScript binding supports only the string representation of an H3 index. +::: + @@ -193,17 +204,20 @@ h3.string_to_h3(h) +:::note + The H3 CLI supports only the string representation of an H3 index. - - +::: -Converts the string representation to `H3Index` (`uint64_t`) representation. -Returns 0 (`E_SUCCESS`) on success. + + ## h3ToString +Converts the `H3Index` representation of the index to the string representation. + @@ -228,6 +245,15 @@ H3Error h3ToString(H3Index h, char *str, size_t sz); String h3ToString(long h3); ``` + + + +:::note + +The H3 JavaScript binding supports only the string representation of an H3 index. + +::: + @@ -238,17 +264,21 @@ h3.h3_to_string(h) +:::note + The H3 CLI supports only the string representation of an H3 index. +::: + -Converts the `H3Index` representation of the index to the string representation. `str` must be at least of length 17. -Returns 0 (`E_SUCCESS`) on success. ## isValidCell +Returns non-zero if this is a valid H3 cell index. + -Returns non-zero if this is a valid H3 cell index. ## isResClassIII +Returns non-zero if this index has a resolution with Class III orientation. + -Returns non-zero if this index has a resolution with Class III orientation. ## isPentagon +Returns non-zero if this index represents a pentagonal cell. + -Returns non-zero if this index represents a pentagonal cell. ## getIcosahedronFaces +Find all icosahedron faces intersected by a given H3 cell. +Faces are represented as integers from 0-19, inclusive. + @@ -532,14 +572,10 @@ $ h3 getIcosahedronFaces -c 85283473fffffff -Find all icosahedron faces intersected by a given H3 index and places them in the array `out`. `out` must be at least length of `maxFaceCount(h)`. - -Faces are represented as integers from 0-19, inclusive. The array is sparse, and empty (no intersection) array values are represented by -1. - -Returns 0 (`E_SUCCESS`) on success. - ## maxFaceCount +Returns the maximum number of icosahedron faces the given H3 index may intersect. + @@ -595,5 +633,3 @@ This function exists for memory management and is not exposed. - -Returns the maximum number of icosahedron faces the given H3 index may intersect. diff --git a/website/docs/api/misc.mdx b/website/docs/api/misc.mdx index 0df6a1162..9b6f98c8f 100644 --- a/website/docs/api/misc.mdx +++ b/website/docs/api/misc.mdx @@ -12,6 +12,8 @@ These functions include descriptions of the H3 grid system. ## degsToRads +Converts degrees to radians. + -Converts degrees to radians. - ## radsToDegs +Converts radians to degrees. + -Converts radians to degrees. - ## getHexagonAreaAvgKm2 +Average hexagon area in square kilometers at the given resolution. +Excludes pentagons. + -Average hexagon area in square kilometers at the given resolution. Excludes pentagons. - ## getHexagonAreaAvgM2 +Average hexagon area in square meters at the given resolution. +Excludes pentagons. + -Average hexagon area in square meters at the given resolution. Excludes pentagons. - - ## cellAreaRads2 +Exact area of specific cell in square radians. + -Exact area of specific cell in square radians. - ## cellAreaKm2 +Exact area of specific cell in square kilometers. + -Exact area of specific cell in square kilometers. - ## cellAreaM2 +Exact area of specific cell in square meters. + -Exact area of specific cell in square meters. - ## getHexagonEdgeLengthAvgKm +Average hexagon edge length in kilometers at the given resolution. +Excludes pentagons. + -Average hexagon edge length in kilometers at the given resolution. Excludes pentagons. ## getHexagonEdgeLengthAvgM +Average hexagon edge length in meters at the given resolution. +Excludes pentagons. + -Average hexagon edge length in meters at the given resolution. Excludes pentagons. - ## edgeLengthKm +Exact edge length of specific unidirectional edge in kilometers. + -Exact edge length of specific unidirectional edge in kilometers. ## edgeLengthM +Exact edge length of specific unidirectional edge in meters. + -Exact edge length of specific unidirectional edge in meters. ## edgeLengthRads +Exact edge length of specific unidirectional edge in radians. + -Exact edge length of specific unidirectional edge in radians. ## getNumCells +Number of unique H3 indexes at the given resolution. + -Number of unique H3 indexes at the given resolution. ## getRes0Cells +Provide all the resolution `0` H3 cells. +These are the coarsest cells that can be represented in the H3 system and are +the parents/ancestors of all other cells in the H3 grid system. +The returned cells correspond to the 122 base cells. + @@ -1004,13 +1019,11 @@ $ h3 getRes0Cells -All the resolution `0` H3 cell indexes. These are the coarsest cells that can be represented in the H3 system and are the -parents of all other cell indexes in the H3 grid system. The returned indexes correspond with the 122 base cells. - -`out` must be an array of at least size `res0CellCount()`. ## res0CellCount +Number of resolution `0` H3 indexes, which is defined as 122. + -Number of resolution `0` H3 indexes, which is defined as 122. ## getPentagons +All the pentagon H3 cells at the specified resolution. +There are 12 pentagons at each resolution. + @@ -1139,13 +1158,11 @@ $ h3 getPentagons -r 5 -All the pentagon H3 indexes at the specified resolution. -`out` must be an array of at least size `pentagonIndexCount()`. - -Returns 0 (`E_SUCCESS`) on success. - ## pentagonCount +Number of pentagon H3 cells per resolution. +This is always 12, but provided as a convenience. + -Number of pentagon H3 indexes per resolution. This is always 12, but provided as a convenience. ## greatCircleDistanceKm +Gives the "great circle" or "haversine" distance between pairs of +LatLng points (lat/lng pairs) in kilometers. + -Gives the "great circle" or "haversine" distance between pairs of -LatLng points (lat/lng pairs) in kilometers. - ## greatCircleDistanceM +Gives the "great circle" or "haversine" distance between pairs of +LatLng points (lat/lng pairs) in meters. + -Gives the "great circle" or "haversine" distance between pairs of -LatLng points (lat/lng pairs) in meters. ## greatCircleDistanceRads +Gives the "great circle" or "haversine" distance between pairs of +LatLng points (lat/lng pairs) in radians. + -Gives the "great circle" or "haversine" distance between pairs of -LatLng points (lat/lng pairs) in radians. -## describeH3Error +## describeH3Error + +Provides a human-readable description of an H3Error error code. @@ -1489,5 +1513,3 @@ Cell argument was not valid - -Provides a human-readable description of an H3Error error code. This function cannot fail, as it just returns a string stating that the H3Error value is itself invalid and does not allocate memory to do so. Do not call `free` on the result of this function. diff --git a/website/docs/api/regions.mdx b/website/docs/api/regions.mdx index da921b270..19a518e4f 100644 --- a/website/docs/api/regions.mdx +++ b/website/docs/api/regions.mdx @@ -12,6 +12,15 @@ These functions convert H3 indexes to and from polygonal areas. ## polygonToCells +Each binding's version of `polygonToCells` takes as input a GeoJSON-like data +structure describing a polygon (i.e., an outer ring and optional holes) and +a target cell resolution. +It produces a collection of cells that are contained within the polygon. + +Containment is determined by centroids of the cells, so that a partitioning +of polygons (covering an area without overlaps) will result in +a partitioning of H3 cells. + @@ -60,9 +74,15 @@ function example() { ```py -h3.polygon_to_cells(polygons, res, geo_json_conformant=False) +h3.polygon_to_cells(h3shape, res) +h3.h3shape_to_cells(h3shape, res) ``` +In Python, `h3shape_to_cells` takes an `H3Shape` object +(`LatLngPoly` or `LatLngMultiPoly`). +Note that `polygon_to_cells` is an alias for `h3shape_to_cells`. +For more info, see the [`h3-py` docs](https://uber.github.io/h3-py/api_quick.html#polygon-interface). + @@ -87,18 +107,11 @@ $ h3 polygonToCells -r 7 -p "[[37.813318999983238, -122.4089866999972145], [37.7 -polygonToCells takes a given GeoJSON-like data structure and preallocated, -zeroed memory, and fills it with the hexagons that are contained by -the GeoJSON-like data structure. -Containment is determined by the cells' centroids. A partitioning -using the GeoJSON-like data structure, where polygons cover an area -without overlap, will result in a partitioning in the H3 grid, where -cells cover the same area without overlap. +## maxPolygonToCellsSize -Returns 0 (`E_SUCCESS`) on success. - -### maxPolygonToCellsSize +Provides an upper bound on the number of cells needed for memory allocation +purposes when computing `polygonToCells` on the given GeoJSON-like data structure. @@ -167,13 +182,18 @@ $ h3 maxPolygonToCellsSize -r 7 -p "[[37.813318999983238, -122.4089866999972145] -maxPolygonToCellsSize returns the number of hexagons to allocate space for when -computing `polygonToCells` on the given GeoJSON-like data structure. - -Returns 0 (`E_SUCCESS`) on success. ## cellsToLinkedMultiPolygon / cellsToMultiPolygon +Create a GeoJSON-like multi-polygon describing the outline(s) of a set of cells. +Polygon outlines will follow GeoJSON MultiPolygon order: Each polygon will +have one outer loop, which is first in the list, followed by any holes. + +It is expected that all cells in the set have the same resolution and +that the set contains no duplicates. Behavior is undefined if duplicates +or multiple resolutions are present, and the algorithm may produce +unexpected or invalid output. + @@ -208,8 +234,8 @@ h3.cellsToMultiPolygon(cells, geoJson) ```js live function example() { - const hexagons = ['872830828ffffff', '87283082effffff']; - return h3.cellsToMultiPolygon(hexagons, true); + const cells = ['872830828ffffff', '87283082effffff']; + return h3.cellsToMultiPolygon(cells, true); } ``` @@ -217,9 +243,15 @@ function example() { ```py -h3.cells_to_multi_polygon(hexes, geo_json=False) +h3.cells_to_h3shape(cells, *, tight=True) ``` +Returns an `H3Shape` object: +- If `tight=True`, returns `LatLngPoly` if possible, otherwise `LatLngMultiPoly`. +- If `tight=False`, always returns a `LatLngMultiPoly`. + +For more info, see the [`h3-py` docs](https://uber.github.io/h3-py/api_quick.html#polygon-interface). + @@ -243,23 +275,13 @@ $ h3 cellsToMultiPolygon -c 872830828ffffff,87283082effffff -Create a LinkedGeoPolygon describing the outline(s) of a set of hexagons. -Polygon outlines will follow GeoJSON MultiPolygon order: Each polygon will -have one outer loop, which is first in the list, followed by any holes. -It is the responsibility of the caller to call destroyLinkedPolygon on the -populated linked geo structure, or the memory for that structure will -not be freed. - -It is expected that all hexagons in the set have the same resolution and -that the set contains no duplicates. Behavior is undefined if duplicates -or multiple resolutions are present, and the algorithm may produce -unexpected or invalid output. - -Returns 0 (`E_SUCCESS`) on success. ## destroyLinkedMultiPolygon +Free all allocated memory for a linked geo structure. The caller is +responsible for freeing memory allocated to the input polygon struct. + -Free all allocated memory for a linked geo structure. The caller is -responsible for freeing memory allocated to the input polygon struct. + diff --git a/website/docs/api/traversal.mdx b/website/docs/api/traversal.mdx index 3b506667a..d62367167 100644 --- a/website/docs/api/traversal.mdx +++ b/website/docs/api/traversal.mdx @@ -8,10 +8,204 @@ slug: /api/traversal import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -Grid traversal allows finding cells in the vicinity of an origin cell, and determining how to traverse the grid from one cell to another. +Grid traversal allows finding cells in the vicinity of an origin cell, +and determining how to traverse the grid from one cell to another. + +## gridDistance + +Provides the *grid distance* between two cells, which is +defined as the minimum number of "hops" needed across adjacent cells to get +from one cell to the other. + +Note that finding the grid distance may fail for a few reasons: + +- the cells are not comparable (different resolutions), +- the cells are too far apart, or +- the cells are separated by pentagonal distortion. + +This is the same set of limitations as the local IJ coordinate space functions. + + + + +```c +H3Error gridDistance(H3Index origin, H3Index h3, int64_t *distance); +``` + +Returns 0 (`E_SUCCESS`) on success, or an error if finding the distance failed. + + + + +```java +long gridDistance(long a, long b) throws DistanceUndefinedException; +long gridDistance(String a, String b) throws DistanceUndefinedException; +``` + + + + +```js +h3.gridDistance(a, b) +``` + +```js live +function example() { + const start = '85283473fffffff'; + const end = '8528342bfffffff'; + return h3.gridDistance(start, end); +} +``` + + + + +```py +h3.grid_distance(h1, h2) +``` + + + + +```sh +$ h3 gridDistance --help +h3: Returns the number of steps along the grid to move from the origin cell to the destination cell +H3 4.1.0 + + gridDistance Returns the number of steps along the grid to move from the origin cell to the destination cell + -h, --help Show this help message. + -o, --origin Required. The origin H3 cell + -d, --destination Required. The destination H3 cell +``` + +```bash +$ h3 gridDistance -o 85283473fffffff -d 8528342bfffffff +2 +``` + + + + + +## gridRingUnsafe + +Produces the "hollow ring" of cells which are *exactly* grid distance `k` +from the origin cell. + +This function may fail if pentagonal distortion is encountered. + + + + +```c +H3Error gridRingUnsafe(H3Index origin, int k, H3Index* out); +``` + +The caller should allocate memory for the maximum size of the ring, which is +`6*k` if `k > 0` and `1` if `k == 0`. + + +Returns 0 (`E_SUCCESS`) if no pentagonal distortion was encountered. + + + + +```java +List gridRingUnsafe(long h3, int k) throws PentagonEncounteredException; +List gridRingUnsafe(String h3Address, int k) throws PentagonEncounteredException; +``` + + + + +```js +h3.gridRingUnsafe(h3Index, k) +``` + +```js live +function example() { + const h = '85283473fffffff'; + const k = 1; + return h3.gridRingUnsafe(h, k); +} +``` + + + + +```py +h3.grid_ring(h, k) +``` + +:::note + +Python uses the C function `gridRingUnsafe` internally to generate the results, +but on failure falls back to `gridDiskDistances` and returns the set +of cells at the specified distance to produce an equivalent to the "safe" version, +but this consumes a lot of memory to do so. + +::: + + + + +```sh +$ h3 gridRing --help +h3: Returns an array of H3 cells, each cell 'k' steps away from the origin cell +H3 4.1.0 + + gridRing Returns an array of H3 cells, each cell 'k' steps away from the origin cell + -h, --help Show this help message. + -c, --cell Required. H3 Cell + -k Required. Maximum grid distance for the output set + -f, --format 'json' for ["CELL", ...], 'newline' for CELL\n... (Default: json) +``` + +```bash +$ h3 gridRing -k 1 -c 85283473fffffff +[ "8528340bfffffff", "85283447fffffff", "8528347bfffffff", "85283463fffffff", "85283477fffffff", "8528340ffffffff" ] +``` + +:::note + +The shell uses the C function `gridRingUnsafe` internally to generate the results, +but on failure falls back to `gridDiskDistances` and returns the set +of cells at the specified distance to produce an equivalent to the "safe" version, +but this consumes a lot of memory to do so. + +::: + + + + ## gridDisk +Produces the "filled-in disk" of cells which are *at most* grid distance `k` +from the origin cell. + +Output order is not guaranteed. + @@ -82,17 +281,10 @@ $ h3 gridDisk -k 5 -c 85283473fffffff -gridDisk produces indices within k distance of the origin index. - -gridDisk was previously named *k-ring* after the concept of a ring with -distance k. k-ring 0 is defined as the origin index, k-ring 1 is -defined as k-ring 0 and all neighboring indices, and so on. - -Output is placed in the provided array in no particular order. Elements of -the output array may be left as zero, which can happen when crossing a pentagon. - ## maxGridDiskSize +Maximum number of cells that can result from the `gridDisk` function for a given `k`. + @@ -149,10 +343,14 @@ This function exists for memory management and is not exposed. -Maximum number of indices that result from the `gridDisk` algorithm with the given `k`. ## gridDiskDistances +Produces the same set of cells as `gridDisk`, but along with each cell's +grid distance from the origin cell. + +Output order is not guaranteed. + @@ -196,9 +399,11 @@ function example() { -```py -h3.grid_disk_distances(origin, k) -``` +:::note + +This function is not exposed in Python. + +::: @@ -223,15 +428,13 @@ $ h3 gridDiskDistances -k 5 -c 85283473fffffff -gridDiskDistances produces indices within k distance of the origin index. - -k-ring 0 is defined as the origin index, k-ring 1 is defined as k-ring 0 and -all neighboring indices, and so on. +## gridDiskUnsafe -Output is placed in the provided array in no particular order. Elements of -the output array may be left as zero, which can happen when crossing a pentagon. +Produces cells within grid distance `k` of the origin cell, just like `gridDisk`. +However, the function may return an error code if pentagonal distorition is +encountered. In this case, the output in the `out` array is undefined. -## gridDiskUnsafe +Users can fall back to calling the slower but more robust `gridDiskDistances`. @@ -270,9 +479,11 @@ This function is not exposed. -```py -h3.grid_disk_unsafe(h, k) -``` +:::note + +This function is not exposed. + +::: @@ -286,20 +497,16 @@ This function is not exposed. -`gridDiskUnsafe` produces indexes within `k` distance of the origin index. -The function returns an error code when one of the returned by this -function is a pentagon or is in the pentagon distortion area. In this case, -the output behavior of the `out` array is undefined. - -k-ring 0 is defined as the origin index, k-ring 1 is defined as k-ring 0 and -all neighboring indexes, and so on. -Output is placed in the provided array in order of increasing distance from -the origin. The provided array must be of size `maxGridDiskSize(k)`. +## gridDiskDistancesUnsafe -Returns 0 (`E_SUCCESS`) if no pentagonal distortion is encountered. +`gridDiskDistancesUnsafe` produces indexes within `k` distance of the origin index. +Output behavior is undefined when one of the indexes returned by this +function is a pentagon or is in the pentagon distortion area. -## gridDiskDistancesUnsafe +Output is placed in the provided array in order of increasing distance from +the origin. The distances in hexagons is placed in the distances array at +the same offset. The provided array must be of size `maxGridDiskSize(k)`. @@ -339,9 +548,11 @@ This function is not exposed. -```py -h3.grid_disk_distances_unsafe(h, k) -``` +:::note + +This function is not exposed. + +::: @@ -355,21 +566,15 @@ This function is not exposed. -`gridDiskDistancesUnsafe` produces indexes within `k` distance of the origin index. -Output behavior is undefined when one of the indexes returned by this -function is a pentagon or is in the pentagon distortion area. -k-ring 0 is defined as the origin index, k-ring 1 is defined as k-ring 0 and -all neighboring indexes, and so on. +## gridDiskDistancesSafe + +`gridDiskDistancesSafe` produces indexes within `k` distance of the origin index. Output is placed in the provided array in order of increasing distance from the origin. The distances in hexagons is placed in the distances array at the same offset. The provided array must be of size `maxGridDiskSize(k)`. -Returns 0 (`E_SUCCESS`) if no pentagonal distortion is encountered. - -## gridDiskDistancesSafe - @@ -408,9 +615,11 @@ This function is not exposed. -```py -h3.grid_disk_distances_safe(h, k) -``` +:::note + +This function is not exposed. + +::: @@ -424,19 +633,13 @@ This function is not exposed. -`gridDiskDistancesSafe` produces indexes within `k` distance of the origin index. - -k-ring 0 is defined as the origin index, k-ring 1 is defined as k-ring 0 and -all neighboring indexes, and so on. - -Output is placed in the provided array in order of increasing distance from -the origin. The distances in hexagons is placed in the distances array at -the same offset. The provided array must be of size `maxGridDiskSize(k)`. - -Returns 0 (`E_SUCCESS`) on success. ## gridDisksUnsafe +`gridDisksUnsafe` takes an array of input cells and a max `k` and returns an +array of cells sorted first by the original cell indices and then by the +grid ring (0 to max), with no guaranteed sorting within each grid ring group. + @@ -475,112 +680,42 @@ This function is not exposed. -```py -h3.grid_disks_unsafe(h, k) -``` - - - - :::note This function is not exposed. ::: - - - -`gridDisksUnsafe` takes an array of input hex IDs and a max k and returns an -array of hexagon IDs sorted first by the original hex IDs and then by the -grid k-ring (0 to max), with no guaranteed sorting within each grid k-ring group. - -Returns 0 (`E_SUCCESS`) if no pentagonal distortion was encountered. Otherwise, output -is undefined - -## gridRingUnsafe - - - - -```c -H3Error gridRingUnsafe(H3Index origin, int k, H3Index* out); -``` - - - - -```java -List gridRingUnsafe(long h3, int k) throws PentagonEncounteredException; -List gridRingUnsafe(String h3Address, int k) throws PentagonEncounteredException; -``` - - - - -```js -h3.gridRingUnsafe(h3Index, k) -``` - -```js live -function example() { - const h = '85283473fffffff'; - const k = 1; - return h3.gridRingUnsafe(h, k); -} -``` - - - - -```py -h3.grid_ring_unsafe(h, k) -``` - :::note -The shell uses `gridRingUnsafe` internally to generate the results, but on failure falls back to `gridDiskDistances` and returns the set of cells at the specified distance to produce an equivalent to the "safe" version, but this consumes a lot of memory to do so. +This function is not exposed. ::: -```sh -$ h3 gridRing --help -h3: Returns an array of H3 cells, each cell 'k' steps away from the origin cell -H3 4.1.0 + + - gridRing Returns an array of H3 cells, each cell 'k' steps away from the origin cell - -h, --help Show this help message. - -c, --cell Required. H3 Cell - -k Required. Maximum grid distance for the output set - -f, --format 'json' for ["CELL", ...], 'newline' for CELL\n... (Default: json) -``` -```bash -$ h3 gridRing -k 1 -c 85283473fffffff -[ "8528340bfffffff", "85283447fffffff", "8528347bfffffff", "85283463fffffff", "85283477fffffff", "8528340ffffffff" ] -``` +## gridPathCells - - +Given two H3 cells, return a minimal-length contiguous path of cells +between them (inclusive of the endpoint cells). -Produces the hollow hexagonal ring centered at origin with sides of length k. +This function may fail if the cells are very far apart, or if +the cells are on opposite sides of a pentagon. -Returns 0 (`E_SUCCESS`) if no pentagonal distortion was encountered. +Notes: -## gridPathCells + * The output of this function should not be considered stable + across library versions. The only guarantees are + that the path length will be `gridDistance(start, end) + 1` and that + every cell in the path will be a neighbor of the preceding cell. + + * Paths exist in the H3 grid of cells, and may not align closely with either + Cartesian lines or great arcs. @@ -652,24 +789,11 @@ $ h3 gridPathCells -o 85283473fffffff -d 8528342bfffffff -Given two H3 indexes, return the line of indexes between them (inclusive). - -This function may fail to find the line between two indexes, for -example if they are very far apart. It may also fail when finding -distances for indexes on opposite sides of a pentagon. - -*Notes:* - - * The specific output of this function should not be considered stable - across library versions. The only guarantees the library provides are - that the line length will be `h3Distance(start, end) + 1` and that - every index in the line will be a neighbor of the preceding index. - - * Lines are drawn in grid space, and may not correspond exactly to either - Cartesian lines or great arcs. - ## gridPathCellsSize +Number of cells in a grid path from the start cell to the end cell, +to be used for allocating memory. + @@ -726,90 +852,15 @@ This function exists for memory management and is not exposed. -Number of indexes in a line from the start index to the end index, -to be used for allocating memory. - -Returns 0 (`E_SUCCESS`) on success, or an error if the line cannot be computed. - -## gridDistance - - - - -```c -H3Error gridDistance(H3Index origin, H3Index h3, int64_t *distance); -``` - - - - -```java -long gridDistance(long a, long b) throws DistanceUndefinedException; -long gridDistance(String a, String b) throws DistanceUndefinedException; -``` - - - - -```js -h3.gridDistance(a, b) -``` - -```js live -function example() { - const start = '85283473fffffff'; - const end = '8528342bfffffff'; - return h3.gridDistance(start, end); -} -``` - - - - -```py -h3.grid_distance(h1, h2) -``` - - - - -```sh -$ h3 gridDistance --help -h3: Returns the number of steps along the grid to move from the origin cell to the destination cell -H3 4.1.0 - - gridDistance Returns the number of steps along the grid to move from the origin cell to the destination cell - -h, --help Show this help message. - -o, --origin Required. The origin H3 cell - -d, --destination Required. The destination H3 cell -``` -```bash -$ h3 gridDistance -o 85283473fffffff -d 8528342bfffffff -2 -``` - - - +## cellToLocalIj -Provides the distance in grid cells between the two indexes. +Produces local IJ coordinates for an H3 cell anchored by an origin. -Returns 0 (`E_SUCCESS`) on success, or an error if finding the distance failed. Finding the distance -can fail because the two indexes are not comparable (different resolutions), too far apart, or are -separated by pentagonal distortion. This is the same set of limitations as the local IJ coordinate -space functions. +`mode` is reserved for future expansion and must be set to `0`. -## cellToLocalIj +This function's output is not guaranteed to be compatible across different +versions of H3. @@ -882,15 +935,15 @@ $ h3 cellToLocalIj -o 85283473fffffff -c 8528342bfffffff -Produces local IJ coordinates for an H3 index anchored by an origin. +## localIjToCell + +Produces an H3 cell from local IJ coordinates anchored by an origin. `mode` is reserved for future expansion and must be set to `0`. This function's output is not guaranteed to be compatible across different versions of H3. -## localIjToCell - @@ -962,11 +1017,4 @@ $ h3 localIjToCell -o 85283473fffffff -i 0 -j 0 -Produces an H3 index from local IJ coordinates anchored by an origin. - -`mode` is reserved for future expansion and must be set to `0`. - -This function's output is not guaranteed to be compatible across different -versions of H3. - diff --git a/website/docs/api/vertex.mdx b/website/docs/api/vertex.mdx index 1f1a0e6d5..c9e115b5c 100644 --- a/website/docs/api/vertex.mdx +++ b/website/docs/api/vertex.mdx @@ -12,6 +12,10 @@ Vertex mode allows encoding the topological vertexes of H3 cells. ## cellToVertex +Returns the index for the specified cell vertex. +Valid vertex numbers are between 0 and 5 (inclusive) +for hexagonal cells, and 0 and 4 (inclusive) for pentagonal cells. + @@ -82,11 +88,10 @@ $ h3 cellToVertex -v 2 -c 85283473fffffff -Returns the index for the specified cell vertex. Valid vertex numbers are between 0 and 5 (inclusive) -for hexagonal cells, and 0 and 4 (inclusive) for pentagonal cells. - ## cellToVertexes +Returns the indexes for all vertexes of the given cell. + @@ -155,13 +166,10 @@ $ h3 cellToVertexes -c 85283473fffffff -Returns the indexes for all vertexes of the given cell index. - -The length of the `out` array must be 6. If the given cell index represents a pentagon, one member of the -array will be set to `0`. - ## vertexToLatLng +Returns the latitude and longitude coordinates of the given vertex. + @@ -230,10 +240,10 @@ $ h3 vertexToLatLng -c 255283463fffffff -Returns the latitude and longitude coordinates of the given vertex. - ## isValidVertex +Determines if the given H3 index represents a valid H3 vertex. + @@ -301,5 +313,3 @@ true - -Returns 1 if the given index represents a valid H3 vertex.