h3 3.6.0 → 3.7.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (175) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/ruby_ci.yml +30 -0
  3. data/.rubocop.yml +1 -1
  4. data/.ruby-version +1 -0
  5. data/CHANGELOG.md +39 -0
  6. data/Gemfile.lock +6 -24
  7. data/LICENSE.md +1 -1
  8. data/README.md +2 -3
  9. data/ext/h3/src/.github/workflows/test-linux.yml +118 -0
  10. data/ext/h3/src/.github/workflows/test-macos.yml +42 -0
  11. data/ext/h3/src/.github/workflows/test-website.yml +32 -0
  12. data/ext/h3/src/.github/workflows/test-windows.yml +44 -0
  13. data/ext/h3/src/.gitignore +5 -0
  14. data/ext/h3/src/.travis.yml +20 -42
  15. data/ext/h3/src/CHANGELOG.md +57 -0
  16. data/ext/h3/src/CMakeLists.txt +135 -33
  17. data/ext/h3/src/CONTRIBUTING.md +1 -1
  18. data/ext/h3/src/README.md +61 -11
  19. data/ext/h3/src/RELEASE.md +3 -1
  20. data/ext/h3/src/VERSION +1 -1
  21. data/ext/h3/src/dev-docs/RFCs/rfc-template.md +21 -0
  22. data/ext/h3/src/dev-docs/RFCs/v4.0.0/error-handling-rfc.md +21 -0
  23. data/ext/h3/src/dev-docs/RFCs/v4.0.0/names_for_concepts_types_functions.md +276 -0
  24. data/ext/h3/src/dev-docs/RFCs/v4.0.0/overrideable-allocators-rfc.md +141 -0
  25. data/ext/h3/src/dev-docs/RFCs/v4.0.0/polyfill-modes-rfc.md +21 -0
  26. data/ext/h3/src/dev-docs/RFCs/v4.0.0/vertex-mode-rfc.md +50 -0
  27. data/ext/h3/src/dev-docs/build_windows.md +6 -1
  28. data/ext/h3/src/dev-docs/creating_bindings.md +3 -3
  29. data/ext/h3/src/dev-docs/custom_alloc.md +27 -0
  30. data/ext/h3/src/docs/{overview/mainpage.md → README.md} +2 -3
  31. data/ext/h3/src/docs/api/misc.md +76 -0
  32. data/ext/h3/src/docs/community/applications.md +1 -0
  33. data/ext/h3/src/docs/community/bindings.md +10 -0
  34. data/ext/h3/src/docs/community/tutorials.md +8 -3
  35. data/ext/h3/src/docs/core-library/coordsystems.md +5 -4
  36. data/ext/h3/src/docs/core-library/filters.md +8 -9
  37. data/ext/h3/src/docs/core-library/geoToH3desc.md +2 -3
  38. data/ext/h3/src/docs/core-library/h3ToGeoBoundaryDesc.md +4 -5
  39. data/ext/h3/src/docs/core-library/h3ToGeoDesc.md +3 -4
  40. data/ext/h3/src/docs/core-library/h3indexing.md +26 -17
  41. data/ext/h3/src/docs/core-library/overview.md +2 -3
  42. data/ext/h3/src/docs/core-library/restable.md +1 -2
  43. data/ext/h3/src/docs/core-library/usage.md +1 -2
  44. data/ext/h3/src/docs/table-of-contents.json +47 -0
  45. data/ext/h3/src/docs/{overview/usecases.md → usecases.md} +6 -11
  46. data/ext/h3/src/scripts/binding_functions.sh +1 -1
  47. data/ext/h3/src/scripts/coverage.sh.in +1 -1
  48. data/ext/h3/src/scripts/update_version.sh +2 -2
  49. data/ext/h3/src/src/apps/applib/include/args.h +1 -0
  50. data/ext/h3/src/src/apps/applib/include/test.h +1 -0
  51. data/ext/h3/src/src/apps/applib/include/utility.h +7 -1
  52. data/ext/h3/src/src/apps/applib/lib/args.c +2 -0
  53. data/ext/h3/src/src/apps/applib/lib/kml.c +2 -0
  54. data/ext/h3/src/src/apps/applib/lib/test.c +1 -0
  55. data/ext/h3/src/src/apps/applib/lib/utility.c +133 -2
  56. data/ext/h3/src/src/apps/benchmarks/benchmarkH3Api.c +1 -1
  57. data/ext/h3/src/{website/html.config.js → src/apps/benchmarks/benchmarkH3UniEdge.c} +15 -12
  58. data/ext/h3/src/src/apps/filters/h3ToComponents.c +1 -0
  59. data/ext/h3/src/src/apps/filters/h3ToGeo.c +1 -0
  60. data/ext/h3/src/src/apps/filters/h3ToGeoBoundary.c +1 -0
  61. data/ext/h3/src/src/apps/filters/h3ToLocalIj.c +1 -0
  62. data/ext/h3/src/src/apps/filters/hexRange.c +1 -0
  63. data/ext/h3/src/src/apps/filters/kRing.c +1 -0
  64. data/ext/h3/src/src/apps/filters/localIjToH3.c +1 -0
  65. data/ext/h3/src/src/apps/miscapps/generateFaceCenterPoint.c +1 -0
  66. data/ext/h3/src/src/apps/miscapps/generateNumHexagons.c +1 -0
  67. data/ext/h3/src/src/apps/miscapps/generatePentagonDirectionFaces.c +67 -0
  68. data/ext/h3/src/src/apps/miscapps/h3ToGeoBoundaryHier.c +1 -0
  69. data/ext/h3/src/src/apps/miscapps/h3ToGeoHier.c +1 -0
  70. data/ext/h3/src/src/apps/miscapps/h3ToHier.c +1 -0
  71. data/ext/h3/src/src/apps/testapps/mkRandGeo.c +1 -0
  72. data/ext/h3/src/src/apps/testapps/mkRandGeoBoundary.c +1 -0
  73. data/ext/h3/src/src/apps/testapps/testBBox.c +1 -0
  74. data/ext/h3/src/src/apps/testapps/testBaseCells.c +15 -1
  75. data/ext/h3/src/src/apps/testapps/testCompact.c +109 -2
  76. data/ext/h3/src/src/apps/testapps/testCoordIj.c +1 -0
  77. data/ext/h3/src/src/apps/testapps/testGeoCoord.c +47 -8
  78. data/ext/h3/src/src/apps/testapps/testGeoToH3.c +1 -0
  79. data/ext/h3/src/src/apps/testapps/testH3Api.c +1 -0
  80. data/ext/h3/src/src/apps/testapps/testH3CellArea.c +47 -0
  81. data/ext/h3/src/src/apps/testapps/testH3CellAreaExhaustive.c +180 -0
  82. data/ext/h3/src/src/apps/testapps/testH3Distance.c +1 -0
  83. data/ext/h3/src/src/apps/testapps/testH3DistanceExhaustive.c +1 -0
  84. data/ext/h3/src/src/apps/testapps/testH3GetFaces.c +1 -0
  85. data/ext/h3/src/src/apps/testapps/testH3Index.c +33 -3
  86. data/ext/h3/src/src/apps/testapps/testH3Line.c +1 -0
  87. data/ext/h3/src/src/apps/testapps/testH3LineExhaustive.c +1 -0
  88. data/ext/h3/src/src/apps/testapps/testH3Memory.c +175 -0
  89. data/ext/h3/src/src/apps/testapps/testH3NeighborRotations.c +1 -0
  90. data/ext/h3/src/src/apps/testapps/testH3SetToLinkedGeo.c +1 -0
  91. data/ext/h3/src/src/apps/testapps/testH3SetToVertexGraph.c +1 -0
  92. data/ext/h3/src/src/apps/testapps/testH3ToCenterChild.c +1 -0
  93. data/ext/h3/src/src/apps/testapps/testH3ToChildren.c +1 -0
  94. data/ext/h3/src/src/apps/testapps/testH3ToGeo.c +1 -0
  95. data/ext/h3/src/src/apps/testapps/testH3ToGeoBoundary.c +1 -0
  96. data/ext/h3/src/src/apps/testapps/testH3ToLocalIj.c +12 -6
  97. data/ext/h3/src/src/apps/testapps/testH3ToLocalIjExhaustive.c +1 -0
  98. data/ext/h3/src/src/apps/testapps/testH3ToParent.c +1 -0
  99. data/ext/h3/src/src/apps/testapps/testH3UniEdge.c +45 -16
  100. data/ext/h3/src/src/apps/testapps/testH3UniEdgeExhaustive.c +111 -0
  101. data/ext/h3/src/src/apps/testapps/testHexRanges.c +1 -0
  102. data/ext/h3/src/src/apps/testapps/testHexRing.c +1 -0
  103. data/ext/h3/src/src/apps/testapps/testKRing.c +19 -0
  104. data/ext/h3/src/src/apps/testapps/testLinkedGeo.c +1 -0
  105. data/ext/h3/src/src/apps/testapps/testMaxH3ToChildrenSize.c +1 -0
  106. data/ext/h3/src/src/apps/testapps/testPentagonIndexes.c +1 -0
  107. data/ext/h3/src/src/apps/testapps/testPolyfill.c +72 -9
  108. data/ext/h3/src/src/apps/testapps/testPolyfillReported.c +157 -0
  109. data/ext/h3/src/src/apps/testapps/testPolygon.c +27 -1
  110. data/ext/h3/src/src/apps/testapps/testVec2d.c +1 -0
  111. data/ext/h3/src/src/apps/testapps/testVec3d.c +1 -0
  112. data/ext/h3/src/src/apps/testapps/testVertex.c +66 -0
  113. data/ext/h3/src/src/apps/testapps/testVertexGraph.c +1 -0
  114. data/ext/h3/src/src/h3lib/include/algos.h +8 -0
  115. data/ext/h3/src/src/h3lib/include/alloc.h +40 -0
  116. data/ext/h3/src/src/h3lib/include/baseCells.h +4 -0
  117. data/ext/h3/src/src/h3lib/include/bbox.h +4 -1
  118. data/ext/h3/src/src/h3lib/include/faceijk.h +3 -2
  119. data/ext/h3/src/src/h3lib/include/geoCoord.h +2 -3
  120. data/ext/h3/src/src/h3lib/include/h3Index.h +37 -4
  121. data/ext/h3/src/src/h3lib/include/h3api.h.in +65 -17
  122. data/ext/h3/src/src/h3lib/include/linkedGeo.h +1 -0
  123. data/ext/h3/src/src/h3lib/include/polygon.h +1 -0
  124. data/ext/h3/src/src/h3lib/include/polygonAlgos.h +1 -0
  125. data/ext/h3/src/src/h3lib/include/vertex.h +44 -0
  126. data/ext/h3/src/src/h3lib/include/vertexGraph.h +1 -0
  127. data/ext/h3/src/src/h3lib/lib/algos.c +304 -76
  128. data/ext/h3/src/src/h3lib/lib/baseCells.c +26 -4
  129. data/ext/h3/src/src/h3lib/lib/bbox.c +56 -27
  130. data/ext/h3/src/src/h3lib/lib/coordijk.c +2 -0
  131. data/ext/h3/src/src/h3lib/lib/faceijk.c +32 -21
  132. data/ext/h3/src/src/h3lib/lib/geoCoord.c +162 -44
  133. data/ext/h3/src/src/h3lib/lib/h3Index.c +83 -42
  134. data/ext/h3/src/src/h3lib/lib/h3UniEdge.c +42 -57
  135. data/ext/h3/src/src/h3lib/lib/linkedGeo.c +20 -15
  136. data/ext/h3/src/src/h3lib/lib/localij.c +1 -1
  137. data/ext/h3/src/src/h3lib/lib/polygon.c +2 -0
  138. data/ext/h3/src/src/h3lib/lib/vec2d.c +1 -0
  139. data/ext/h3/src/src/h3lib/lib/vec3d.c +1 -0
  140. data/ext/h3/src/src/h3lib/lib/vertex.c +134 -0
  141. data/ext/h3/src/src/h3lib/lib/vertexGraph.c +8 -5
  142. data/ext/h3/src/website/.eslintignore +2 -0
  143. data/ext/h3/src/website/.gitignore +57 -0
  144. data/ext/h3/src/website/.nvmrc +1 -0
  145. data/ext/h3/src/website/README.md +8 -6
  146. data/ext/h3/src/website/gatsby-config.js +83 -0
  147. data/ext/h3/src/website/package.json +20 -12
  148. data/ext/h3/src/website/scripts/build-to-gh-pages.sh +7 -5
  149. data/ext/h3/src/website/src/.gitkeep +0 -0
  150. data/ext/h3/src/website/templates/documentation.jsx +129 -0
  151. data/ext/h3/src/website/yarn.lock +13723 -0
  152. data/h3.gemspec +2 -2
  153. data/lib/h3/bindings/base.rb +14 -4
  154. data/lib/h3/bindings/private.rb +12 -9
  155. data/lib/h3/hierarchy.rb +0 -18
  156. data/lib/h3/indexing.rb +0 -18
  157. data/lib/h3/inspection.rb +3 -59
  158. data/lib/h3/miscellaneous.rb +119 -14
  159. data/lib/h3/regions.rb +3 -0
  160. data/lib/h3/traversal.rb +0 -18
  161. data/lib/h3/unidirectional_edges.rb +5 -60
  162. data/lib/h3/version.rb +1 -1
  163. data/spec/geo_json_spec.rb +8 -0
  164. data/spec/miscellaneous_spec.rb +117 -0
  165. data/spec/{region_spec.rb → regions_spec.rb} +1 -1
  166. data/spec/spec_helper.rb +2 -2
  167. metadata +44 -36
  168. data/.travis.yml +0 -11
  169. data/ext/h3/src/.ycm_extra_conf.py +0 -92
  170. data/ext/h3/src/appveyor.yml +0 -50
  171. data/ext/h3/src/website/src/config.js +0 -46
  172. data/ext/h3/src/website/src/mdRoutes.js +0 -151
  173. data/ext/h3/src/website/src/styles/_variables.scss +0 -16
  174. data/ext/h3/src/website/src/styles/index.scss +0 -3
  175. data/ext/h3/src/website/static/index.html +0 -15
@@ -1,5 +1,6 @@
1
- Coordinate Systems used by the H3 Core Library
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&deg; 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 Address Conversion
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 <a href="#/documentation/core-library/h3-index-representations"> **H3** Index Representations</a> page for information on the integer `H3Index`.
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
- `echo 40.689167 -74.044444 | geoToH3 5`
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
- `echo 845ad1bffffffff | h3ToGeo`
28
+ `h3ToGeo --index 845ad1bffffffff`
30
29
 
31
30
  * output the cell boundary for `H3Index` 845ad1bffffffff
32
31
 
33
- `echo 845ad1bffffffff | h3ToGeoBoundary`
32
+ `h3ToGeoBoundary --index 845ad1bffffffff`
34
33
 
35
34
  * find the components for the `H3Index` 845ad1bffffffff
36
35
 
37
- `echo 845ad1bffffffff | h3ToComponents`
36
+ `h3ToComponents --index 845ad1bffffffff`
38
37
 
39
38
  * output all indexes within distance 1 of the `H3Index` 845ad1bffffffff
40
39
 
41
- `echo 845ad1bffffffff | kRing 1`
40
+ `kRing -k 1 --origin 845ad1bffffffff`
42
41
 
43
42
  * output all hexagon indexes within distance 2 of the `H3Index` 845ad1bffffffff
44
43
 
45
- `echo 845ad1bffffffff | hexRange 2`
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 <a href="#/documentation/core-library/coordinate-systems">Coordinate Systems used by the **H3 Core Library**</a> for more information on each of these coordinate systems.
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 <a href="#/documentation/core-library/coordinate-systems">Coordinate Systems used by the **H3 Core Library**</a> for more information on each of these coordinate systems.
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 <a href="#/documentation/core-library/walkthrough-of-h3togeo">finding a cell center point</a>. If adjacent vertices lie on different icosahedron faces a point is introduced at the intersection of the cell edge and icosahedron face edge.
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 <a href="#/documentation/core-library/coordinate-systems">Coordinate Systems used by the **H3 Core Library**</a> for more information on each of these coordinate systems.
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 kind of concept being indexed. Mode 1 is an **H3** Cell (Hexagon) Index, mode 2 is an **H3** Unidirectional Edge (Hexagon A -> Hexagon B) Index, mode 3 is planned to be a bidirectional edge (Hexagon A <-> Hexagon B). Mode 0 is reserved and indicates an invalid **H3** index.
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
- The components of the **H3** cell index (mode 1) are packed into the lowest order 63 bits of a 64-bit integer in order as follows:
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 is reserved for resolutions 1-15)
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 the lowest order 63 bits of a 64-bit integer in order as follows:
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 is reserved for resolutions 1-15)
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></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 \\(\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 <a href="#/documentation/core-library/resolution-table">here</a>.
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
  | ------------- | ------------------------------------: | -------------------------------: | -----------------------:
@@ -1,5 +1,4 @@
1
- How to use H3
2
- ---
1
+ # How to use H3
3
2
 
4
3
  The public API of the **H3 Core Library** is defined in the file h3api.h. The functions defined in h3api.h adhere to [Semantic Versioning](http://semver.org/).
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
- Why H3
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 2017 Uber Technologies, Inc.
3
3
  #
4
4
  # Licensed under the Apache License, Version 2.0 (the "License");
@@ -1,4 +1,4 @@
1
- #!/bin/bash
1
+ #!/usr/bin/env bash
2
2
 
3
3
  # Copyright 2018-2019 Uber Technologies, Inc.
4
4
  #
@@ -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`.
@@ -23,6 +23,7 @@
23
23
  #include <inttypes.h>
24
24
  #include <stdbool.h>
25
25
  #include <stdio.h>
26
+
26
27
  #include "utility.h"
27
28
 
28
29
  /** Maximum number of names an argument may have. */
@@ -21,6 +21,7 @@
21
21
  #define TEST_H
22
22
 
23
23
  #include <stdio.h>
24
+
24
25
  #include "geoCoord.h"
25
26
  #include "h3api.h"
26
27
 
@@ -1,5 +1,5 @@
1
1
  /*
2
- * Copyright 2016-2019 Uber Technologies, Inc.
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
@@ -18,10 +18,12 @@
18
18
  */
19
19
 
20
20
  #include "args.h"
21
+
21
22
  #include <stdbool.h>
22
23
  #include <stdio.h>
23
24
  #include <stdlib.h>
24
25
  #include <string.h>
26
+
25
27
  #include "h3api.h"
26
28
 
27
29
  /*
@@ -18,7 +18,9 @@
18
18
  */
19
19
 
20
20
  #include "kml.h"
21
+
21
22
  #include <stdio.h>
23
+
22
24
  #include "h3api.h"
23
25
 
24
26
  void kmlPtsHeader(const char* name, const char* desc) {
@@ -18,6 +18,7 @@
18
18
  */
19
19
 
20
20
  #include "test.h"
21
+
21
22
  #include <assert.h>
22
23
  #include <stdio.h>
23
24