The library geogrid provides methods to generate and handle the ISEA Aperture 3 Hexagon Discrete Global Grid System (ISEA3H DGGS) using the Inverse Snyder Equal-Area Projection (ISEA).
An overview of the ISEA3H DGGS and the identifier scheme used in this library can be found in:
The ISEA3H has originally been proposed by:
The projection has been proposed and has been described in detail by:
Data aggregated by a DGGS can be presented in the browser by using the JavaScript library geogrid.js, which visualizes such data as a layer to Leaflet. Data aggregation can even be performed automatically by the framework Measures REST, which even provides the aggregated data via a REST interface.
The ISEA projection maps the regular icosahedron to the sphere. A hexagonal grid introduced on the icosahedron can thus be mapped to the sphere as well. As the ISEA projection and the ISEA3H grid are thus strongly interlinked, this library offers an implementation of both, the ISEA projection and the ISEA3H grid.
A location on the icosahedron can be mapped to the sphere, as in the following example of the coordinate (20.3, 12.5) on face 2:
ISEAProjection projection = new ISEAProjection();
GeoCoordinates c = projection.icosahedronToSphere(new FaceCoordinates(2, 20.3, 12.5));
c.getLat(); // 52.739063
c.getLon(); // 0.315051The resulting geographic coordinates can be projected back to the icosahedron:
FaceCoordinates c2 = projection.sphereToIcosahedron(c);
c2.getFace(); // 2
c2.getX(); // 20.3
c2.getY(); // 12.5When the grid cell containing a given location should be determined, the method cellForLocation can be used, either for a pair of coordinates, or an instance of GeoCoordinates:
GridCell gc1 = grid.cellForLocation(41.5, 6.5);
GridCell gc2 = grid.cellForLocation(new GeoCoordinates(41.5, 6.5));The cell containing the centroid of a Geometry (from the JTS Topology Suite) can be determined accordingly:
grid.cellForCentroid(g);The grid cells of the ISEA3H for a given boundary box can easily be computed as follows:
ISEA3H grid = new ISEA3H(10);
Collection<GridCell> cells = grid.cellsForBound(41, 42, 6, 7);Observe that the constructor of the class ISEA3H accepts the grid resolution as a parameter. The method cellsForBound computes, in this case, all cells that are (about) contained in the area between 41 and 42 degree latitude and 6 and 7 degree longitude. If all cells should be computed, the method cells can be used instead:
Collection<GridCell> cellsAll = grid.cells();The resulting collection of cells contains instances of GridCell. Such an instance contains information about the centroid of the grid cell, the grid resolution, whether it is a hexagon (or a pentagon) cell, and an identifier (ID):
for (GridCell gc : cells) {
gc.getLat();
gc.getLon();
gc.getResolution();
gc.isPentagon();
gc.getID();
}Different types of cell IDs can be used:
| Type of ID | Description | Typical use |
|---|---|---|
NON_ADAPTIVE |
Non-adaptive IDs include the geometry of the cell in a heigh precision. | Perfect rendering of the grid cells |
ADAPTIVE_1_PERCENT |
Adaptive 1% IDs include the geometry in a scale dependent but yet reasonable precision. | Rendering of the grid cells on a website |
ADAPTIVE_1_PERCENT |
Adaptive unique IDs aim at being as short as possible while preserving uniqueness. | Comparison of whether two cells are identical |
Further information can be found in:
By default, non-adaptive IDs are returned. The type of ID can though be inserted explicitly as follows:
gc.getID(NON_ADAPTIVE);
gc.getID(ADAPTIVE_1_PERCENT);
gc.getID(ADAPTIVE_UNIQUE);In case that just the identifiers (IDs) of the cells should be computed, two more efficient methods can be used:
ISEA3H grid = new ISEA3H(10);
Collection<Long> cells = grid.cellIDsForBound(41, 42, 6, 7);
Collection<Long> cells2 = grid.cellIDsForBound(41, 42, 6, 7, ADAPTIVE_UNIQUE);
Collection<Long> cellsAll = grid.cellIDs();
Collection<Long> cellsAll2 = grid.cellIDs(ADAPTIVE_UNIQUE);The IDs can even be saved to the hard disc:
ISEA3H grid = new ISEA3H(10);
grid.cellIDs("path/filename");
grid.cellIDs("path/filename2", ADAPTIVE_UNIQUE);Each of the created files contains only IDs that refer to one face of the icosahedron, and the data is divided into a number of chunks. The same ID can occur multiple times (for different faces) when it refers to a cell that is partially contained in different faces. The files are named as filename.face.chunk_number. The first part of this name refers to the filename provided in the method cellsIDs; the second part, to the face to which the IDs contained in the file belong to; and the third part consists of consecutive numbers to distinguish the chunks.
Many properties of the ISEA projection are provided by an instance of the ISEAProjection. The following table provides an overview over some of them:
| Function | Description |
|---|---|
numberOfFaces() |
number of faces of the icosahedron |
maximumAngularDistortion() |
maximum angular distortion |
maximumScaleVariation() |
maximum scale variation |
miniumScaleVariation() |
minimum scale variation |
lengthOfTriangleBase() |
length of the bases of the triangles of the icosahedron |
sphericalDistanceFromCenterToVerticesOnSphere() |
spherical distance from center of a face to any of its vertices on the sphere; in degrees |
The ISEA projection maps from the icosahedron to the sphere. By default, two of the vertices of the faces of the icosahedron are mapped to the poles. Another orientation might, however, be useful in many cases, as, for example, in the case of the ISEA3H DGGS: distortions are especially large at the vertices of the faces, and one aims at mapping the vertices to places that are within the oceans. Such an ‘ideal’ choice of an orientation can be reached by:
ISEAProjection projection = new ISEAProjection();
projection.setOrientationSymmetricEquator();If the orientation is to be set manually by shifting the orientation relative to the standard orientation (two of the vertices are mapped to the poles). The following method shifts every location by the angle orientationLon in the direction of positive longitude, and thereafter by the angle orientationLat in direction of positive latitude:
projection.setOrientation(orientationLat, orientationLon);Many properties of the ISEA3H DGGS are provided by an instance of the ISEA3H. The following table provides an overview over some of them:
| Function | Description |
|---|---|
diameterOfHexagonalCellOnIcosahedron() |
diameter of a hexagonal cell on the icosahedron, in kilometres |
lengthOfASideOfHexagonalCellOnIcosahedron() |
length of a side of a hexagonal cell on the icosahedron, in kilometres |
lowerBoundForLengthOfASideOfHexagonalCellOnSphere() |
lower bound for the length of a side of a hexagonal cell on the sphere, in kilometres |
areaOfAHexagonalCell() |
area of a hexagonal cell; the cells have all the same area by construction, because the ISEA projection is equal-area, in square kilometres |
areaOfAPentagonalCell() |
area of a pentagonal cell; the cells have all the same area by construction, because the ISEA projection is equal-area, in square kilometres |
numberOfHexagonalCells() |
number of hexagonal cells |
numberOfPentagonalCells() |
number of pentagonal cells |
Some of the computations can be executed in parallel. The number of threads can be set as follows:
ISEA3H grid = new ISEA3H(10);
grid.setNumberOfThreads(8);By default, 8 threads are used.
This software is written and maintained by Franz-Benjamin Mocnik, [email protected].
In 2017–2019, this software has been supported by the DFG project A framework for measuring the fitness for purpose of OpenStreetMap data based on intrinsic quality indicators (FA 1189/3-1).
All commits after 9/2019 (c) by Franz-Benjamin Mocnik, 2019. All commits before 8/2019 (c) by Heidelberg University, 2017–2019.
The code is licensed under the MIT license.