h3 3.6.0 → 3.7.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.github/workflows/ruby_ci.yml +30 -0
- data/.rubocop.yml +1 -1
- data/.ruby-version +1 -0
- data/CHANGELOG.md +39 -0
- data/Gemfile.lock +6 -24
- data/LICENSE.md +1 -1
- data/README.md +2 -3
- data/ext/h3/src/.github/workflows/test-linux.yml +118 -0
- data/ext/h3/src/.github/workflows/test-macos.yml +42 -0
- data/ext/h3/src/.github/workflows/test-website.yml +32 -0
- data/ext/h3/src/.github/workflows/test-windows.yml +44 -0
- data/ext/h3/src/.gitignore +5 -0
- data/ext/h3/src/.travis.yml +20 -42
- data/ext/h3/src/CHANGELOG.md +57 -0
- data/ext/h3/src/CMakeLists.txt +135 -33
- data/ext/h3/src/CONTRIBUTING.md +1 -1
- data/ext/h3/src/README.md +61 -11
- data/ext/h3/src/RELEASE.md +3 -1
- data/ext/h3/src/VERSION +1 -1
- data/ext/h3/src/dev-docs/RFCs/rfc-template.md +21 -0
- data/ext/h3/src/dev-docs/RFCs/v4.0.0/error-handling-rfc.md +21 -0
- data/ext/h3/src/dev-docs/RFCs/v4.0.0/names_for_concepts_types_functions.md +276 -0
- data/ext/h3/src/dev-docs/RFCs/v4.0.0/overrideable-allocators-rfc.md +141 -0
- data/ext/h3/src/dev-docs/RFCs/v4.0.0/polyfill-modes-rfc.md +21 -0
- data/ext/h3/src/dev-docs/RFCs/v4.0.0/vertex-mode-rfc.md +50 -0
- data/ext/h3/src/dev-docs/build_windows.md +6 -1
- data/ext/h3/src/dev-docs/creating_bindings.md +3 -3
- data/ext/h3/src/dev-docs/custom_alloc.md +27 -0
- data/ext/h3/src/docs/{overview/mainpage.md → README.md} +2 -3
- data/ext/h3/src/docs/api/misc.md +76 -0
- data/ext/h3/src/docs/community/applications.md +1 -0
- data/ext/h3/src/docs/community/bindings.md +10 -0
- data/ext/h3/src/docs/community/tutorials.md +8 -3
- data/ext/h3/src/docs/core-library/coordsystems.md +5 -4
- data/ext/h3/src/docs/core-library/filters.md +8 -9
- data/ext/h3/src/docs/core-library/geoToH3desc.md +2 -3
- data/ext/h3/src/docs/core-library/h3ToGeoBoundaryDesc.md +4 -5
- data/ext/h3/src/docs/core-library/h3ToGeoDesc.md +3 -4
- data/ext/h3/src/docs/core-library/h3indexing.md +26 -17
- data/ext/h3/src/docs/core-library/overview.md +2 -3
- data/ext/h3/src/docs/core-library/restable.md +1 -2
- data/ext/h3/src/docs/core-library/usage.md +1 -2
- data/ext/h3/src/docs/table-of-contents.json +47 -0
- data/ext/h3/src/docs/{overview/usecases.md → usecases.md} +6 -11
- data/ext/h3/src/scripts/binding_functions.sh +1 -1
- data/ext/h3/src/scripts/coverage.sh.in +1 -1
- data/ext/h3/src/scripts/update_version.sh +2 -2
- data/ext/h3/src/src/apps/applib/include/args.h +1 -0
- data/ext/h3/src/src/apps/applib/include/test.h +1 -0
- data/ext/h3/src/src/apps/applib/include/utility.h +7 -1
- data/ext/h3/src/src/apps/applib/lib/args.c +2 -0
- data/ext/h3/src/src/apps/applib/lib/kml.c +2 -0
- data/ext/h3/src/src/apps/applib/lib/test.c +1 -0
- data/ext/h3/src/src/apps/applib/lib/utility.c +133 -2
- data/ext/h3/src/src/apps/benchmarks/benchmarkH3Api.c +1 -1
- data/ext/h3/src/{website/html.config.js → src/apps/benchmarks/benchmarkH3UniEdge.c} +15 -12
- data/ext/h3/src/src/apps/filters/h3ToComponents.c +1 -0
- data/ext/h3/src/src/apps/filters/h3ToGeo.c +1 -0
- data/ext/h3/src/src/apps/filters/h3ToGeoBoundary.c +1 -0
- data/ext/h3/src/src/apps/filters/h3ToLocalIj.c +1 -0
- data/ext/h3/src/src/apps/filters/hexRange.c +1 -0
- data/ext/h3/src/src/apps/filters/kRing.c +1 -0
- data/ext/h3/src/src/apps/filters/localIjToH3.c +1 -0
- data/ext/h3/src/src/apps/miscapps/generateFaceCenterPoint.c +1 -0
- data/ext/h3/src/src/apps/miscapps/generateNumHexagons.c +1 -0
- data/ext/h3/src/src/apps/miscapps/generatePentagonDirectionFaces.c +67 -0
- data/ext/h3/src/src/apps/miscapps/h3ToGeoBoundaryHier.c +1 -0
- data/ext/h3/src/src/apps/miscapps/h3ToGeoHier.c +1 -0
- data/ext/h3/src/src/apps/miscapps/h3ToHier.c +1 -0
- data/ext/h3/src/src/apps/testapps/mkRandGeo.c +1 -0
- data/ext/h3/src/src/apps/testapps/mkRandGeoBoundary.c +1 -0
- data/ext/h3/src/src/apps/testapps/testBBox.c +1 -0
- data/ext/h3/src/src/apps/testapps/testBaseCells.c +15 -1
- data/ext/h3/src/src/apps/testapps/testCompact.c +109 -2
- data/ext/h3/src/src/apps/testapps/testCoordIj.c +1 -0
- data/ext/h3/src/src/apps/testapps/testGeoCoord.c +47 -8
- data/ext/h3/src/src/apps/testapps/testGeoToH3.c +1 -0
- data/ext/h3/src/src/apps/testapps/testH3Api.c +1 -0
- data/ext/h3/src/src/apps/testapps/testH3CellArea.c +47 -0
- data/ext/h3/src/src/apps/testapps/testH3CellAreaExhaustive.c +180 -0
- data/ext/h3/src/src/apps/testapps/testH3Distance.c +1 -0
- data/ext/h3/src/src/apps/testapps/testH3DistanceExhaustive.c +1 -0
- data/ext/h3/src/src/apps/testapps/testH3GetFaces.c +1 -0
- data/ext/h3/src/src/apps/testapps/testH3Index.c +33 -3
- data/ext/h3/src/src/apps/testapps/testH3Line.c +1 -0
- data/ext/h3/src/src/apps/testapps/testH3LineExhaustive.c +1 -0
- data/ext/h3/src/src/apps/testapps/testH3Memory.c +175 -0
- data/ext/h3/src/src/apps/testapps/testH3NeighborRotations.c +1 -0
- data/ext/h3/src/src/apps/testapps/testH3SetToLinkedGeo.c +1 -0
- data/ext/h3/src/src/apps/testapps/testH3SetToVertexGraph.c +1 -0
- data/ext/h3/src/src/apps/testapps/testH3ToCenterChild.c +1 -0
- data/ext/h3/src/src/apps/testapps/testH3ToChildren.c +1 -0
- data/ext/h3/src/src/apps/testapps/testH3ToGeo.c +1 -0
- data/ext/h3/src/src/apps/testapps/testH3ToGeoBoundary.c +1 -0
- data/ext/h3/src/src/apps/testapps/testH3ToLocalIj.c +12 -6
- data/ext/h3/src/src/apps/testapps/testH3ToLocalIjExhaustive.c +1 -0
- data/ext/h3/src/src/apps/testapps/testH3ToParent.c +1 -0
- data/ext/h3/src/src/apps/testapps/testH3UniEdge.c +45 -16
- data/ext/h3/src/src/apps/testapps/testH3UniEdgeExhaustive.c +111 -0
- data/ext/h3/src/src/apps/testapps/testHexRanges.c +1 -0
- data/ext/h3/src/src/apps/testapps/testHexRing.c +1 -0
- data/ext/h3/src/src/apps/testapps/testKRing.c +19 -0
- data/ext/h3/src/src/apps/testapps/testLinkedGeo.c +1 -0
- data/ext/h3/src/src/apps/testapps/testMaxH3ToChildrenSize.c +1 -0
- data/ext/h3/src/src/apps/testapps/testPentagonIndexes.c +1 -0
- data/ext/h3/src/src/apps/testapps/testPolyfill.c +72 -9
- data/ext/h3/src/src/apps/testapps/testPolyfillReported.c +157 -0
- data/ext/h3/src/src/apps/testapps/testPolygon.c +27 -1
- data/ext/h3/src/src/apps/testapps/testVec2d.c +1 -0
- data/ext/h3/src/src/apps/testapps/testVec3d.c +1 -0
- data/ext/h3/src/src/apps/testapps/testVertex.c +66 -0
- data/ext/h3/src/src/apps/testapps/testVertexGraph.c +1 -0
- data/ext/h3/src/src/h3lib/include/algos.h +8 -0
- data/ext/h3/src/src/h3lib/include/alloc.h +40 -0
- data/ext/h3/src/src/h3lib/include/baseCells.h +4 -0
- data/ext/h3/src/src/h3lib/include/bbox.h +4 -1
- data/ext/h3/src/src/h3lib/include/faceijk.h +3 -2
- data/ext/h3/src/src/h3lib/include/geoCoord.h +2 -3
- data/ext/h3/src/src/h3lib/include/h3Index.h +37 -4
- data/ext/h3/src/src/h3lib/include/h3api.h.in +65 -17
- data/ext/h3/src/src/h3lib/include/linkedGeo.h +1 -0
- data/ext/h3/src/src/h3lib/include/polygon.h +1 -0
- data/ext/h3/src/src/h3lib/include/polygonAlgos.h +1 -0
- data/ext/h3/src/src/h3lib/include/vertex.h +44 -0
- data/ext/h3/src/src/h3lib/include/vertexGraph.h +1 -0
- data/ext/h3/src/src/h3lib/lib/algos.c +304 -76
- data/ext/h3/src/src/h3lib/lib/baseCells.c +26 -4
- data/ext/h3/src/src/h3lib/lib/bbox.c +56 -27
- data/ext/h3/src/src/h3lib/lib/coordijk.c +2 -0
- data/ext/h3/src/src/h3lib/lib/faceijk.c +32 -21
- data/ext/h3/src/src/h3lib/lib/geoCoord.c +162 -44
- data/ext/h3/src/src/h3lib/lib/h3Index.c +83 -42
- data/ext/h3/src/src/h3lib/lib/h3UniEdge.c +42 -57
- data/ext/h3/src/src/h3lib/lib/linkedGeo.c +20 -15
- data/ext/h3/src/src/h3lib/lib/localij.c +1 -1
- data/ext/h3/src/src/h3lib/lib/polygon.c +2 -0
- data/ext/h3/src/src/h3lib/lib/vec2d.c +1 -0
- data/ext/h3/src/src/h3lib/lib/vec3d.c +1 -0
- data/ext/h3/src/src/h3lib/lib/vertex.c +134 -0
- data/ext/h3/src/src/h3lib/lib/vertexGraph.c +8 -5
- data/ext/h3/src/website/.eslintignore +2 -0
- data/ext/h3/src/website/.gitignore +57 -0
- data/ext/h3/src/website/.nvmrc +1 -0
- data/ext/h3/src/website/README.md +8 -6
- data/ext/h3/src/website/gatsby-config.js +83 -0
- data/ext/h3/src/website/package.json +20 -12
- data/ext/h3/src/website/scripts/build-to-gh-pages.sh +7 -5
- data/ext/h3/src/website/src/.gitkeep +0 -0
- data/ext/h3/src/website/templates/documentation.jsx +129 -0
- data/ext/h3/src/website/yarn.lock +13723 -0
- data/h3.gemspec +2 -2
- data/lib/h3/bindings/base.rb +14 -4
- data/lib/h3/bindings/private.rb +12 -9
- data/lib/h3/hierarchy.rb +0 -18
- data/lib/h3/indexing.rb +0 -18
- data/lib/h3/inspection.rb +3 -59
- data/lib/h3/miscellaneous.rb +119 -14
- data/lib/h3/regions.rb +3 -0
- data/lib/h3/traversal.rb +0 -18
- data/lib/h3/unidirectional_edges.rb +5 -60
- data/lib/h3/version.rb +1 -1
- data/spec/geo_json_spec.rb +8 -0
- data/spec/miscellaneous_spec.rb +117 -0
- data/spec/{region_spec.rb → regions_spec.rb} +1 -1
- data/spec/spec_helper.rb +2 -2
- metadata +44 -36
- data/.travis.yml +0 -11
- data/ext/h3/src/.ycm_extra_conf.py +0 -92
- data/ext/h3/src/appveyor.yml +0 -50
- data/ext/h3/src/website/src/config.js +0 -46
- data/ext/h3/src/website/src/mdRoutes.js +0 -151
- data/ext/h3/src/website/src/styles/_variables.scss +0 -16
- data/ext/h3/src/website/src/styles/index.scss +0 -3
- data/ext/h3/src/website/static/index.html +0 -15
@@ -1,5 +1,6 @@
|
|
1
|
-
Coordinate
|
2
|
-
|
1
|
+
# Coordinate systems
|
2
|
+
|
3
|
+
The **H3 Core Library** uses the following coordinate systems internally.
|
3
4
|
|
4
5
|
IJK Coordinates
|
5
6
|
---
|
@@ -9,7 +10,7 @@ Discrete hexagon planar grid systems naturally have 3 coordinate axes spaced 120
|
|
9
10
|
Using an *ijk* coordinate system to address hexagon grid cells provides multiple valid addresses for each cell. *Normalizing* an *ijk* address (function `_ijkNormalize`) creates a unique address consisting of the minimal positive *ijk* components; this always results in at most two non-zero components.
|
10
11
|
|
11
12
|
<div align="center">
|
12
|
-
<img height="300" src="images/ijkp.png" />
|
13
|
+
<img height="300" src="/images/ijkp.png" />
|
13
14
|
</div>
|
14
15
|
|
15
16
|
FaceIJK Coordinates
|
@@ -20,7 +21,7 @@ The **H3 Core Library** centers an *ijk* coordinate system on each face of the i
|
|
20
21
|
Each grid resolution is rotated ~19.1° relative to the next coarser resolution. The rotation alternates between counterclockwise and clockwise at each successive resolution, so that each resolution will have one of two possible orientations: *Class II* or *Class III* (using a terminology coined by R. Buckminster Fuller). The base cells, which make up resolution 0, are *Class II*.
|
21
22
|
|
22
23
|
<div align="center">
|
23
|
-
<img height="300" src="images/classII.III.png" />
|
24
|
+
<img height="300" src="/images/classII.III.png" />
|
24
25
|
</div>
|
25
26
|
|
26
27
|
Hex2d Coordinates
|
@@ -1,11 +1,10 @@
|
|
1
|
-
Unix-style Filters for
|
2
|
-
---
|
1
|
+
# Unix-style Filters for H3
|
3
2
|
|
4
3
|
The directory `src/apps/filters` contains unix-style stdin/stdout filters that perform conversions between integer **H3** indexes and other useful types. It currently contains the filters listed in the table below. See the header comments in each application source code file for more information.
|
5
4
|
|
6
5
|
Filters are experimental and are not part of the semantic version of the H3 library.
|
7
6
|
|
8
|
-
All latitude/longitude coordinates are in decimal degrees. See the
|
7
|
+
All latitude/longitude coordinates are in decimal degrees. See the [**H3** Index Representations](/docs/core-library/h3indexing) page for information on the integer `H3Index`.
|
9
8
|
|
10
9
|
|
11
10
|
| filter | input | outputs
|
@@ -22,26 +21,26 @@ Unix Command Line Examples
|
|
22
21
|
|
23
22
|
* find the index for coordinates at resolution 5
|
24
23
|
|
25
|
-
`
|
24
|
+
`geoToH3 --resolution 5 --latitude 40.689167 --longitude -74.044444`
|
26
25
|
|
27
26
|
* output the cell center point for `H3Index` 845ad1bffffffff
|
28
27
|
|
29
|
-
`
|
28
|
+
`h3ToGeo --index 845ad1bffffffff`
|
30
29
|
|
31
30
|
* output the cell boundary for `H3Index` 845ad1bffffffff
|
32
31
|
|
33
|
-
`
|
32
|
+
`h3ToGeoBoundary --index 845ad1bffffffff`
|
34
33
|
|
35
34
|
* find the components for the `H3Index` 845ad1bffffffff
|
36
35
|
|
37
|
-
`
|
36
|
+
`h3ToComponents --index 845ad1bffffffff`
|
38
37
|
|
39
38
|
* output all indexes within distance 1 of the `H3Index` 845ad1bffffffff
|
40
39
|
|
41
|
-
`
|
40
|
+
`kRing -k 1 --origin 845ad1bffffffff`
|
42
41
|
|
43
42
|
* output all hexagon indexes within distance 2 of the `H3Index` 845ad1bffffffff
|
44
43
|
|
45
|
-
`
|
44
|
+
`hexRange -k 2 --origin 845ad1bffffffff`
|
46
45
|
|
47
46
|
Note that the filters `h3ToGeo` and `h3ToGeoBoundary` take optional arguments that allow them to generate `kml` output. See the header comments in the corresponding source code files for details.
|
@@ -1,9 +1,8 @@
|
|
1
|
-
Conversion from latitude/longitude to containing H3 cell index
|
2
|
-
---
|
1
|
+
# Conversion from latitude/longitude to containing H3 cell index
|
3
2
|
|
4
3
|
This operation is performed by function `geoToH3`. See the comments in the function for more detail.
|
5
4
|
|
6
|
-
The conversion is performed as a series of coordinate system conversions described below. See the page
|
5
|
+
The conversion is performed as a series of coordinate system conversions described below. See the page [Coordinate Systems used by the **H3 Core Library**](/docs/core-library/coordsystems) for more information on each of these coordinate systems.
|
7
6
|
|
8
7
|
1. The input latitude/longitude coordinate is first converted into the containing icosahedron face and a *Hex2d* coordinate on that face using function `_geoToHex2d`, which determines the correct face and then performs a face-centered gnomonic projection into face-centered polar coordinates. These polar coordinates are then scaled appropriately to a *Hex2d* coordinate on the input grid resolution *r*.
|
9
8
|
2. The *Hex2d* coordinate is converted into resolution *r* normalized *ijk* coordinates using function `_hex2dToCoordIJK`.
|
@@ -1,15 +1,14 @@
|
|
1
|
-
Generate the cell boundary in latitude/longitude coordinates of an H3Index cell
|
2
|
-
---
|
1
|
+
# Generate the cell boundary in latitude/longitude coordinates of an H3Index cell
|
3
2
|
|
4
3
|
This operation is performed by function `h3ToGeoBoundary`. See the comments in the function source code for more detail.
|
5
4
|
|
6
|
-
The conversion is performed as a series of coordinate system conversions described below. See the page
|
5
|
+
The conversion is performed as a series of coordinate system conversions described below. See the page [Coordinate Systems used by the **H3 Core Library**](/docs/core-library/coordsystems) for more information on each of these coordinate systems.
|
7
6
|
|
8
7
|
* We note that the cell vertices are the center points of cells in an aperture 3 grid one resolution finer than the cell resolution, which we term a *substrate* grid. We precalculate the substrate *ijk* coordinates of a cell with *ijk* coordinates (0,0,0), adding additional aperture 3 and aperture 7 (if required, by Class III cell grid) substrate grid resolutions as required to transform the vertex coordinates into a Class II substrate grid.
|
9
8
|
|
10
9
|
<div align="center">
|
11
|
-
<img height="300" src="images/substrate3.png" />
|
10
|
+
<img height="300" src="/images/substrate3.png" />
|
12
11
|
</div>
|
13
12
|
|
14
|
-
* The function `_faceIjkToGeoBoundary` calculates the *ijk* coordinates of the cell center point in the appropriate substrate grid (determined in the last step), and each of the substrate vertices is translated using the cell center point *ijk*. Each vertex *ijk* is then transformed onto the appropriate face and *Hex2d* coordinate system using the approach taken in
|
13
|
+
* The function `_faceIjkToGeoBoundary` calculates the *ijk* coordinates of the cell center point in the appropriate substrate grid (determined in the last step), and each of the substrate vertices is translated using the cell center point *ijk*. Each vertex *ijk* is then transformed onto the appropriate face and *Hex2d* coordinate system using the approach taken in [finding a cell center point](/docs/core-library/h3ToGeoDesc). If adjacent vertices lie on different icosahedron faces a point is introduced at the intersection of the cell edge and icosahedron face edge.
|
15
14
|
* The *Hex2d* coordinates are then converted to latitude/longitude using `_hex2dToGeo`.
|
@@ -1,9 +1,8 @@
|
|
1
|
-
Determine the latitude/longitude coordinates of the center point of an H3Index cell
|
2
|
-
---
|
1
|
+
# Determine the latitude/longitude coordinates of the center point of an H3Index cell
|
3
2
|
|
4
3
|
This operation is performed by function `h3ToGeo`. See the comments in the function source code for more detail.
|
5
4
|
|
6
|
-
The conversion is performed as a series of coordinate system conversions described below. See the page
|
5
|
+
The conversion is performed as a series of coordinate system conversions described below. See the page [Coordinate Systems used by the **H3 Core Library**](/docs/core-library/coordsystems) for more information on each of these coordinate systems.
|
7
6
|
|
8
7
|
* The function `_h3ToFaceIjk` then converts the **H3** index to the appropriate icosahedron face number and normalized *ijk* coordinate's on that face's coordinate system as follows:
|
9
8
|
* We start by assuming that the cell center point falls on the same icosahedron face as its base cell.
|
@@ -11,7 +10,7 @@ The conversion is performed as a series of coordinate system conversions describ
|
|
11
10
|
We determine whether an overage exists by taking the sum of the *ijk* components, and if there is an overage the positive *ijk* components indicate which adjacent face the cell center lies on. A lookup operation is then performed to find the appropriate rotation and translation to transform the *ijk* coordinates into the adjacent face-centered *ijk* system.
|
12
11
|
|
13
12
|
<div align="center">
|
14
|
-
<img height="300" src="images/triEdge.png" />
|
13
|
+
<img height="300" src="/images/triEdge.png" />
|
15
14
|
</div>
|
16
15
|
|
17
16
|
* The face-centered *ijk* coordinates are then converted into corresponding *Hex2d* coordinates using the function `_ijkToHex2d`.
|
@@ -1,45 +1,54 @@
|
|
1
|
-
H3 Index Representations
|
2
|
-
---
|
1
|
+
# H3 Index Representations
|
3
2
|
|
4
|
-
Introduction
|
5
|
-
---
|
3
|
+
## Introduction
|
6
4
|
|
7
5
|
The **H3** system assigns a unique hierarchical index to each cell. The **H3** index of a resolution *r* cell begins with the appropriate resolution 0 base cell number. This is followed by a sequence of *r* digits 0-6, where each *i*<sup>th</sup> digit *d*<sub>i</sub> specifies one of the 7 cells centered on the cell indicated by the coarser resolution digits *d*<sub>1</sub> through *d*<sub>i-1</sub>. A local hexagon coordinate system is assigned to each of the resolution 0 base cells and is used to orient all hierarchical indexing child cells of that base cell. The assignment of digits 0-6 at each resolution uses a *Central Place Indexing* arrangement (see [Sahr, 2014](http://webpages.sou.edu/~sahrk/sqspc/pubs/autocarto14.pdf)). In the case of the 12 pentagonal cells the indexing hierarchy produced by sub-digit 1 is removed at all resolutions.
|
8
6
|
|
9
7
|
Child hexagons are linearly smaller than their parent hexagons.
|
10
8
|
|
11
9
|
<div align="center">
|
12
|
-
<img height="300" src="images/cpidigits.png" />
|
10
|
+
<img height="300" src="/images/cpidigits.png" />
|
13
11
|
</div>
|
14
12
|
|
15
13
|
|
16
|
-
H3Index Representation
|
17
|
-
---
|
14
|
+
## H3Index Representation
|
18
15
|
|
19
|
-
The **H3Index** is the integer representation of an **H3** index, which can be placed into multiple modes to indicate the
|
16
|
+
The **H3Index** is the integer representation of an **H3** index, which can be placed into multiple modes to indicate the concept being indexed.
|
20
17
|
|
21
|
-
|
18
|
+
* Mode 1 is an **H3** Cell (Hexagon/Pentagon) index.
|
19
|
+
* Mode 2 is an **H3** Unidirectional Edge (Cell A -> Cell B) index.
|
20
|
+
* Mode 3 is planned to be a bidirectional edge (Cell A <-> Cell B).
|
21
|
+
* Mode 0 is reserved and indicates an invalid **H3** index.
|
22
|
+
* This mode remains, partially, for backwards compatibility with an older version of H3.
|
22
23
|
|
24
|
+
Mode 0 contains a special index, `H3_NULL`, which is unique: it is bit-equivalent to `0`.
|
25
|
+
This index indicates, *specifically*, an invalid, missing, or uninitialized **H3** index;
|
26
|
+
it is analogous to `NaN` in floating point.
|
27
|
+
It should be used instead of an arbitrary Mode 0 index, due to its uniqueness and easy identifiability.
|
28
|
+
|
29
|
+
The components of the **H3** cell index (mode 1) are packed into a 64-bit integer in order, highest bit first, as follows:
|
30
|
+
|
31
|
+
* 1 bit reserved and set to 0,
|
23
32
|
* 4 bits to indicate the index mode,
|
24
|
-
* 3 bits reserved,
|
33
|
+
* 3 bits reserved and set to 0,
|
25
34
|
* 4 bits to indicate the cell resolution 0-15,
|
26
35
|
* 7 bits to indicate the base cell 0-121, and
|
27
|
-
* 3 bits to indicate each subsequent digit 0-6 from resolution 1 up to the resolution of the cell (45 bits total
|
36
|
+
* 3 bits to indicate each subsequent digit 0-6 from resolution 1 up to the resolution of the cell (45 bits total are reserved for resolutions 1-15)
|
28
37
|
|
29
|
-
The components of the **H3** unidirectional edge index (mode 2) are packed into
|
38
|
+
The components of the **H3** unidirectional edge index (mode 2) are packed into a 64-bit integer in order, highest bit first, as follows:
|
30
39
|
|
40
|
+
* 1 bit reserved and set to 0,
|
31
41
|
* 4 bits to indicate the index mode,
|
32
42
|
* 3 bits to indicate the edge 1-6 of the cell to traverse,
|
33
43
|
* 4 bits to indicate the cell resolution 0-15,
|
34
44
|
* 7 bits to indicate the base cell 0-121, and
|
35
|
-
* 3 bits to indicate each subsequent digit 0-6 from resolution 1 up to the resolution of the cell (45 bits total
|
45
|
+
* 3 bits to indicate each subsequent digit 0-6 from resolution 1 up to the resolution of the cell (45 bits total are reserved for resolutions 1-15)
|
36
46
|
|
37
|
-
The canonical string representation of an **H3Index** is the hexadecimal representation of the integer.
|
47
|
+
The canonical string representation of an **H3Index** is the hexadecimal representation of the integer, using lowercase letters. The string representation is variable length (no zero padding) and is not prefixed or suffixed.
|
38
48
|
|
39
49
|
The three bits for each unused digit are set to 7.
|
40
50
|
|
41
|
-
Bit layout of H3Index
|
42
|
-
---
|
51
|
+
## Bit layout of H3Index
|
43
52
|
|
44
53
|
The layout of an **H3Index** is shown below in table form. The interpretation of the "Reserved/edge" field differs depending on the mode of the index.
|
45
54
|
|
@@ -65,7 +74,7 @@ The layout of an **H3Index** is shown below in table form. The interpretation of
|
|
65
74
|
</tr>
|
66
75
|
<tr>
|
67
76
|
<th>0x30</th>
|
68
|
-
<td
|
77
|
+
<td>Reserved</td>
|
69
78
|
<td colspan="4">Mode</td>
|
70
79
|
<td colspan="3">Reserved/edge</td>
|
71
80
|
<td colspan="4">Resolution</td>
|
@@ -1,5 +1,4 @@
|
|
1
|
-
Overview of the H3 Geospatial Indexing System
|
2
|
-
---
|
1
|
+
# Overview of the H3 Geospatial Indexing System
|
3
2
|
|
4
3
|
The **H3** geospatial indexing system is a discrete global grid system (see [Sahr et al., 2003](http://webpages.sou.edu/~sahrk/sqspc/pubs/gdggs03.pdf)) consisting of a multi-precision hexagonal tiling of the sphere with hierarchical indexes. The hexagonal grid system is created on the planar faces of a sphere-circumscribed icosahedron, and the grid cells are then projected to the surface of the sphere using an inverse face-centered polyhedral gnomonic projection.
|
5
4
|
|
@@ -9,6 +8,6 @@ The **H3** grid is constructed on the icosahedron by recursively creating increa
|
|
9
8
|
|
10
9
|
The first **H3** resolution (resolution 0) consists of 122 cells (110 hexagons and 12 icosahedron vertex-centered pentagons), referred to as the *base cells*. These were chosen to capture as much of the symmetry of the spherical icosahedron as possible. These base cells are assigned numbers from 0 to 121 based on the latitude of their center points; base cell 0 has the northern most center point, while base cell 121 has the southern most center point.
|
11
10
|
|
12
|
-
Each subsequent resolution beyond resolution 0 is created using an aperture 7 resolution spacing (aperture refers to the number of cells in the next finer resolution grid for each cell); as resolution increases the unit length is scaled by
|
11
|
+
Each subsequent resolution beyond resolution 0 is created using an aperture 7 resolution spacing (aperture refers to the number of cells in the next finer resolution grid for each cell); as resolution increases the unit length is scaled by $\sqrt{7}$ and each hexagon has $1/7th$ the area of a hexagon at the next coarser resolution (as measured on the icosahedron). **H3** provides 15 finer grid resolutions in addition to the resolution 0 base cells. The finest resolution, resolution 15, has cells with an area of less than $1 m^2$. A table detailing the average cell area for each H3 resolution is available [here](/docs/core-library/restable).
|
13
12
|
|
14
13
|
*Note:* you can create KML files to visualize the **H3** grids by running the `kml` make target. It will place the files in the `KML` output sub-directory.
|
@@ -1,5 +1,4 @@
|
|
1
|
-
Table of Cell Areas for H3 Resolutions
|
2
|
-
---
|
1
|
+
# Table of Cell Areas for H3 Resolutions
|
3
2
|
|
4
3
|
| H3 Resolution | Average Hexagon Area (km<sup>2</sup>) | Average Hexagon Edge Length (km) | Number of unique indexes
|
5
4
|
| ------------- | ------------------------------------: | -------------------------------: | -----------------------:
|
@@ -0,0 +1,47 @@
|
|
1
|
+
{
|
2
|
+
"id": "table-of-contents",
|
3
|
+
"chapters": [
|
4
|
+
{
|
5
|
+
"title": "Overview",
|
6
|
+
"entries": [
|
7
|
+
{"entry": "docs/README"},
|
8
|
+
{"entry": "docs/usecases"}
|
9
|
+
]
|
10
|
+
},
|
11
|
+
{
|
12
|
+
"title": "Core Library",
|
13
|
+
"entries": [
|
14
|
+
{"entry": "docs/core-library/overview"},
|
15
|
+
{"entry": "docs/core-library/h3indexing"},
|
16
|
+
{"entry": "docs/core-library/coordsystems"},
|
17
|
+
{"entry": "docs/core-library/geoToH3desc"},
|
18
|
+
{"entry": "docs/core-library/h3ToGeoDesc"},
|
19
|
+
{"entry": "docs/core-library/h3ToGeoBoundaryDesc"},
|
20
|
+
{"entry": "docs/core-library/filters"},
|
21
|
+
{"entry": "docs/core-library/usage"},
|
22
|
+
{"entry": "docs/core-library/restable"}
|
23
|
+
]
|
24
|
+
},
|
25
|
+
{
|
26
|
+
"title": "API Reference",
|
27
|
+
"entries": [
|
28
|
+
{"entry": "docs/api/indexing"},
|
29
|
+
{"entry": "docs/api/inspection"},
|
30
|
+
{"entry": "docs/api/traversal"},
|
31
|
+
{"entry": "docs/api/hierarchy"},
|
32
|
+
{"entry": "docs/api/regions"},
|
33
|
+
{"entry": "docs/api/uniedge"},
|
34
|
+
{"entry": "docs/api/misc"}
|
35
|
+
]
|
36
|
+
},
|
37
|
+
{
|
38
|
+
"title": "Community",
|
39
|
+
"entries": [
|
40
|
+
{"entry": "docs/community/bindings"},
|
41
|
+
{"entry": "docs/community/libraries"},
|
42
|
+
{"entry": "docs/community/tutorials"},
|
43
|
+
{"entry": "docs/community/applications"}
|
44
|
+
]
|
45
|
+
}
|
46
|
+
]
|
47
|
+
}
|
@@ -1,8 +1,4 @@
|
|
1
|
-
|
2
|
-
---
|
3
|
-
|
4
|
-
Use cases
|
5
|
-
---
|
1
|
+
# Use cases
|
6
2
|
|
7
3
|
Analysis of data sets of locations, such as locations of cars in a city, may be done by bucketing locations. ([Sahr et al., 2003](http://webpages.sou.edu/~sahrk/sqspc/pubs/gdggs03.pdf)) There are several options for partitioning an area into buckets, such as manually drawing regions using human knowledge, or to partition the surface using a regular grid.
|
8
4
|
|
@@ -16,7 +12,7 @@ Using a regular grid can avoid these drawbacks by providing smooth gradients and
|
|
16
12
|
|
17
13
|
| Triangle | Square | Hexagon
|
18
14
|
| -------- | ------ | -------
|
19
|
-
| <img src="images/neighbors-triangle.png" style="width:400px"> | <img src="images/neighbors-square.png" style="width:400px"> | <img src="images/neighbors-hexagon.png" style="width:400px">
|
15
|
+
| <img src="/images/neighbors-triangle.png" style="width:400px"> | <img src="/images/neighbors-square.png" style="width:400px"> | <img src="/images/neighbors-hexagon.png" style="width:400px">
|
20
16
|
| Triangles have 12 neighbors | Squares have 8 neighbors | Hexagons have 6 neighbors
|
21
17
|
|
22
18
|
In addition to indexing locations to cells, **H3** provides a number of algorithms operating on indexes.
|
@@ -24,14 +20,14 @@ In addition to indexing locations to cells, **H3** provides a number of algorith
|
|
24
20
|
Hexagons have the property of expanding rings of neighbors (`kRing`) approximating circles:
|
25
21
|
|
26
22
|
<div align="center">
|
27
|
-
<img src="images/neighbors.png" style="width:400px"><br>
|
23
|
+
<img src="/images/neighbors.png" style="width:400px"><br>
|
28
24
|
<i>All six neighbors of a hexagon (ring 1)</i>
|
29
25
|
</div>
|
30
26
|
|
31
27
|
Squares cleanly subdivide into four finer squares. Hexagons do not cleanly subdivide into seven finer hexagons. However, by alternating the orientation of grids a subdivision into seven cells (referred to as *aperture 7*) can be approximated. This makes it possible to truncate the precision (within a fixed margin of error) of an **H3** index using a few bitwise operations (`h3ToParent`). It is also possible to determine all the children of a parent **H3** index (`h3ToChildren`). Approximate containment only applies when truncating the precision of an **H3** index. The borders of hexagons indexed at a specific resolution are not approximate.
|
32
28
|
|
33
29
|
<div align="center">
|
34
|
-
<img src="images/parent-child.png" style="width:400px"><br>
|
30
|
+
<img src="/images/parent-child.png" style="width:400px"><br>
|
35
31
|
<i>A parent hexagon approximately contains seven children</i>
|
36
32
|
</div>
|
37
33
|
|
@@ -39,11 +35,10 @@ Hierarchical containment allows for use cases like making contiguous sets of hex
|
|
39
35
|
|
40
36
|
| Uncompact (dense) | Compact (sparse)
|
41
37
|
| ----------------- | ----------------
|
42
|
-
| <img src="images/ca_uncompact_6_10633.png" style="width:500px"> | <img src="images/ca_compact_6_901.png" style="width:500px">
|
38
|
+
| <img src="/images/ca_uncompact_6_10633.png" style="width:500px"> | <img src="/images/ca_compact_6_901.png" style="width:500px">
|
43
39
|
| California represented by 10633 uncompact hexagons | California represented by 901 compact hexagons
|
44
40
|
|
45
|
-
Comparisons
|
46
|
-
---
|
41
|
+
## Comparisons
|
47
42
|
|
48
43
|
| System | Index representation | Cell shape | Projection system
|
49
44
|
| --------- | -------------------- | ---------- | -----------------
|
@@ -1,4 +1,4 @@
|
|
1
|
-
#!/bin/bash
|
1
|
+
#!/usr/bin/env bash
|
2
2
|
# Copyright 2019 Uber Technologies, Inc.
|
3
3
|
#
|
4
4
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
@@ -13,7 +13,7 @@
|
|
13
13
|
# See the License for the specific language governing permissions and
|
14
14
|
# limitations under the License.
|
15
15
|
|
16
|
-
# This script is used interactively as part of the H3 release process
|
16
|
+
# This script is used interactively as part of the H3 release process
|
17
17
|
# (RELEASE.md) to update the version number in the VERSION file. Before
|
18
18
|
# writing the new version to the file, changelog information is presented
|
19
19
|
# for verification. It is invoked by the make target `update-version`.
|
@@ -1,5 +1,5 @@
|
|
1
1
|
/*
|
2
|
-
* Copyright 2016-
|
2
|
+
* Copyright 2016-2020 Uber Technologies, Inc.
|
3
3
|
*
|
4
4
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
5
5
|
* you may not use this file except in compliance with the License.
|
@@ -21,6 +21,7 @@
|
|
21
21
|
#define UTILITY_H
|
22
22
|
|
23
23
|
#include <stdio.h>
|
24
|
+
|
24
25
|
#include "coordijk.h"
|
25
26
|
#include "h3api.h"
|
26
27
|
|
@@ -54,5 +55,10 @@ void iterateAllIndexesAtResPartial(int res, void (*callback)(H3Index),
|
|
54
55
|
int maxBaseCell);
|
55
56
|
void iterateBaseCellIndexesAtRes(int res, void (*callback)(H3Index),
|
56
57
|
int baseCell);
|
58
|
+
void iterateAllUnidirectionalEdgesAtRes(int res, void (*callback)(H3Index));
|
59
|
+
double mapSumAllCells_double(int res, double (*callback)(H3Index));
|
60
|
+
size_t packNonzeros(H3Index* a, size_t n);
|
61
|
+
|
62
|
+
int countActualHexagons(H3Index* hexagons, int numHexagons);
|
57
63
|
|
58
64
|
#endif
|