DGGAL, the Discrete Global Grid Abstraction Library

DGGAL provides a common interface to perform various operations on Discrete Global Grid Reference Systems (DGGRS), facilitating the implementation of Discrete Global Grid Systems (DGGS), including implementing Web APIs based on the OGC API - DGGS Standard.

Installation from PyPI

Both a source distribution and built distribution for Linux, Windows and macOS, including the dgg utility and Python bindings are available from PyPI and can be installed with:

pip install dggal

DGGAL integration in other software

DGGAL is already being integrated in several DGGS-enabled software, notably:

• Vgrid plugin for QGIS, Vgrid DGGS, and Vgrid plugin for Map Libre,
• FME Community Modules: DGGS Indexer, DGGS Relator, DGGS-JSON Decoder, and DGGS-JSON Encoder,
• a5geo (adapting the DGGAL code for the DSEA / IVEA equal-area projection),
• pydggsapi,
• GeoPlegma,
• Geotoolkit, a testing ground for Apache SIS,
• Ecere's GNOSIS Software Development Kit and GNOSIS Map Server.

Supported Discrete Global Grid Reference Systems

DGGAL currently supports all nine DGGRSs described in OGC API - DGGS Annex B, as well as additional DGGRSs:

Axis-aligned DGGRS in WGS84 latitude and longitude (simple bounding boxes)

• GNOSIS Global Grid: An axis-aligned quad-tree defined in WGS84 latitude and longitude, with special handling of polar regions achieving an approximate maximum of ~48% variance from median zone area, corresponding to the OGC 2D Tile Matrix Set of the same name

Equal-Area DGGRSs based on Icosahedral Projections (aperture 3 and 7 Hexagonal, aperture 4 and 9 Axis-Aligned Rhombic)

All of these Icosahedral DGGRSs achieve equal-area on the WGS84 ellipsoid, and are oriented with a first vertex of the icosahedron positioned at authalic latitude of arctan(φ) (where φ is the golden ratio), and longitude 11.20°E, with second vertex due North, resulting in only one vertex / pentagon on land. Each of the 12 pentagons occupies 5/6th the area of a hexagon at the same refinement level.

Starting from version 0.0.6, the aperture 7 hexagonal grids and indexing are fully functional, including support for listing and resolving sub-zones for both hexagonal and pentagonal ancestral zones.

Icosahedral Snyder Equal Area (ISEA) projection

(An Equal-Area Map Projection for Polyhedral Globes (1992), or dodecahedron configuration (DVEA) of Slice & Dice (2006))

• ISEA4R: An equal area rhombic grid with a refinement ratio of 4 defined in the transformed into a 5x6 Cartesian space resulting in axis-aligned square zones
• ISEA9R: An equal area rhombic grid with a refinement ratio of 9 defined in the ISEA projection transformed into a 5x6 Cartesian space resulting in axis-aligned square zones
• ISEA3H: An equal area hexagonal grid with a refinement ratio of 3 defined in the ISEA projection
• ISEA7H: An equal area hexagonal grid with a refinement ratio of 7 defined in the ISEA projection
• ISEA7H_Z7: Same Discrete Global Grid Hierarchy (DGGH) and sub-zone order as ISEA7H, but using the Z7 indexing for interoperability with DGGRID and IGEO7.

NOTE: The DGGRID / IGEO7 interoperability of ISEA7H_Z7 relies on converting the authalic latitudes produced by DGGRID to geodetic latitudes to reference them to the WGS84 ellipsoid, and using the orientation which can be specified in DGGRID with dggs_vert0_lon 11.20, dggs_vert0_lat 58.282525588538994675786 and dggs_vert0_azimuth 0.0. Efficient conversion from authalic latitude to geodetic latitudes is described by Charles Karney's "On auxiliary latitudes" and can be performed using Geographiclib or with the authalicSetup(), latGeodeticToAuthalic() and latAuthalicToGeodetic() functions from DGGAL.

Icosahedral Vertex-oriented great circle Equal Area (IVEA) projection

(Slice & Dice (2006), or applying Snyder 1992 to the dodecahedron (DSEA))

• IVEA4R: An equal area rhombic grid with a refinement ratio of 4 defined in the IVEA projection transformed into a 5x6 Cartesian space resulting in axis-aligned square zones, using the same global indexing and sub-zone ordering as for ISEA4R
• IVEA9R: An equal area rhombic grid with a refinement ratio of 9 defined in the IVEA projection transformed into a 5x6 Cartesian space resulting in axis-aligned square zones, using the same global indexing and sub-zone ordering as for ISEA9R
• IVEA3H: An equal area hexagonal grid with a refinement ratio of 3 defined in the IVEA projection, using the same global indexing and sub-zone ordering as for ISEA3H
• IVEA7H: An equal area hexagonal grid with a refinement ratio of 7 defined in the IVEA projection, using the same global indexing and sub-zone ordering as for ISEA7H
• IVEA7H_Z7: Same DGGH and sub-zone order as IVEA7H, but using same Z7 indexing as for ISEA7H_Z7.

NOTE: This projection is superior to ISEA and RT(S)EA at avoiding perceptible cusps, resulting in more compact/regular zones.

Rhombic Triacontahedron (Snyder) Equal-Area (RT(S)EA) projection

(applying Snyder 1992 to the Rhombic Triacontahedron, alternate configuration of Slice & Dice (2006), Disdyakis Triacontahedron Discrete Global Grid System, or Construction of rhombic triacontahedron discrete global grid systems)

• RTEA4R: An equal area rhombic grid with a refinement ratio of 4 defined in the RTEA projection transformed into a 5x6 Cartesian space resulting in axis-aligned square zones, using the same global indexing and sub-zone ordering as for ISEA4R
• RTEA9R: An equal area rhombic grid with a refinement ratio of 9 defined in the RTEA projection transformed into a 5x6 Cartesian space resulting in axis-aligned square zones, using the same global indexing and sub-zone ordering as for ISEA9R
• RTEA3H: An equal area hexagonal grid with a refinement ratio of 3 defined in the RTEA projection using the same global indexing and sub-zone ordering as for ISEA3H
• RTEA7H: An equal area hexagonal grid with a refinement ratio of 7 defined in the RTEA projection using the same global indexing and sub-zone ordering as for ISEA7H
• RTEA7H_Z7: Same DGGH and sub-zone order as RTEA7H, but using same Z7 indexing as for ISEA7H_Z7.

Axis-aligned and Equal-Area DGGRSs based on HEALPix Projection

(HEALPix projection)

• HEALPix: An equal area and axis-aligned grid with square zones topology and a refinement ratio of 4 defined in the HEALPix projection, using configuration Nφ/H = 4, Nθ/K = 3 (same as default PROJ implementation), the new indexing described in OGC API - DGGS Annex B, and scanline-based sub-zone ordering
• rHEALPix: An equal area and axis-aligned grid with square zones topology and a refinement ratio of 9 defined in the rHEALPix projection using 50° E prime meridian (equivalent to PROJ implementation with parameters +proj=rhealpix +lon_0=50 +ellps=WGS84), the original hierarchical indexing, and scanline-based sub-zone ordering

libDGGAL API Documentation

The API documentation can be found here.

The DGGRS class provides most of the functionality of the library, allowing to resolve DGGRS zones by textual ID to a unique 64-bit zone integer identifier (DGGRSZone). The geometry and sub-zones of a pa