h3 3.6.0 → 3.7.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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
|