Search code examples
javascriptgeospatialh3

Where is the origin that maps the base hexagons in Uber's H3 Hexagonal hierarchical geospatial indexing system to the globe?

I just learned about H3 and would like to basically get the "standard reference" point, referencing each hexagon (and the 12 pentagons) at each resolution, and then determine what the lat/lng coordinates are for each hexagon. How does this work?

The H3 grid is constructed on the icosahedron by recursively creating increasingly higher precision hexagon grids until the desired resolution is achieved. Note that it is impossible to tile the sphere/icosahedron completely with hexagons; each resolution of an icosahedral hexagon grid must contain exactly 12 pentagons at every resolution, with one pentagon centered on each of the icosahedron vertices.

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.

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 m2.

I would like to go down to resolution 10, which is about 15m^2 area. I would like to store a custom generated key with each hexagon at this resolution, associating the key with the index or hash of the hexagon, which I assume is somehow associated to the origin of the system, and somehow the origin is hardcoded to a specific place on the globe.

So it appears that h3.getRes0Indexes will give us the 122 origin cells at base 0. And the hierarchy docs show in the JavaScript library how to traverse the resolutions at least.

function example() {
  const h = '85283473fffffff';
  return h3.h3ToCenterChild(h, 10);
}

So given I have figured out what the origin hash is, that will get me centered at resolution 10. In the traversal code, I don't see a straightforward way of traversing each node once. How should that be done?

Ah nevermind, is it just that, instead of jumping to the center child at resolution 10, you ask for all the children within the base node?

const baseCells = h3.getRes0Indexes();
for (const index of baseCells) {
  yield* await getChildrenAtRes(index, h3Res);
}

async function* getChildrenAtRes(h3Index, targetRes) {
  const nextRes = h3.h3GetResolution(h3Index) + 1;
  // Iterate over all direct children of the current index
  for (const child of h3.h3ToChildren(h3Index, nextRes)) {
    if (nextRes >= targetRes) {
      await Promises.delay(300);
      yield child;
    } else {
      yield* getChildrenAtRes(child, targetRes); 
    }
  }
}

Maybe I can try just jumping directly from 0 to resolution 10 and getting all the hundreds of children? I will try that.

Also can use this:

// Get the vertices of an H3 index as lat/lng points
h3.h3ToGeoBoundary("8928342e20fffff")

So I guess I have answered all my questions except, where is the origin? Where is the part where it maps the stuff to the actual Earth globe? Is that hardcoded somehow in the codebase somewhere? How do I know that when I use the library today, the 122 base hexagons I get from the API will have the same hash as the last time I used it?

Solution

  • where is the origin?

    There is no single origin. The grid is based on a projection of a regular icosahedron onto the surface of the globe (using a spherical model).

    Where is the part where it maps the stuff to the actual Earth globe? Is that hardcoded somehow in the codebase somewhere?

    The orientation of the icosahedron is fixed relative to the Earth - you can see the center coordinates of each face here (these are, as you suggested, hardcoded in the codebase).

    How do I know that when I use the library today, the 122 base hexagons I get from the API will have the same hash as the last time I used it?

    All H3 indexes are stable - this is a function of the algorithm we use to create the index, and of the API guarantee we offer that we won't make any changes to the library that change cell indexes or geographic locations.

    You can see more info on the methodology of the indexing function here.