Discrete Global Grid Reference System (Part 1)

  • 06/03/2026
  • Johann S.

In 2024, Geomatys started working on DGGRS with our existing libraries. In 2025 we joined the OGC AI-DGGS for Disaster Management Pilot.

 As a result of this pilot our libraries made a step forward, or more exactly a huge jump, in DGGRS. With lots of new things to play with.

 Let’s see one of the results of this work. 

DGGRS Java API

In the current Java ecosystem you can find several DGGRS libraries, like S2 (https://s2geometry.io), H3 (https://h3geo.org), CDS-Healpix (https://github.com/cds-astro/cds-healpix-java). But all of them have a different API and very different capabilities.

 

From our very beginning, Geomatys has been working on OGC’s GeoAPI, a set of programming interfaces for numerous ISO and OGC standards related to GIS, and naturally we continue this effort by creating new interfaces to map DGGRSes but also to fit them into the existing GIS world.

 

Making a DGGRS API required a bit of effort, but it was nonetheless a reasonable task. Making it fluently fit with Coordinate, Temporal, and Elevation Reference Systems as well as Metadata, Geometry, and Identifier Based Reference systems was a more complex task which required a deep understanding of each of these models.

 

 The API presented here is our preliminary work for the future integration of DGGRSes into Apache-SIS and later on in OGC GeoAPI.
 The following UML diagrams hare simplified and slightly outdated versions of the existing code, but defines the core model of this new API

1. Overview

After reading and processing the different DGGRS documents and existing ISO Reference System specifications, we noted one major change with the Topic 21 — Discrete Global Grid Systems document.

 

 

The decision was made to make DGGRS extends ReferenceByIdentifiers (ISO 19112) instead of CoordinateReferenceSystem (ISO 19111). This choice did not have any impact on the OGC DGGRS API but has fundamental differences when using it in code.

The reasons behind this choice are :

 

 

  • Zone IDs are 64-bits integers, not floating points values. All CRS APIs (SIS, PROJ, …) expect floating points values, at best 64-bits, so there is not a direct mapping between float64 and int64.
  • Zone ID may eceed 64-Bits (for 3D, 4D or more) or may be text
  • Zones have a ‘depth’ or ‘level’ information, this property is correctly defined in ReferenceByIdentifiers, but idoes not exist in CRS.

Zones are areas/volumes, not exact positions, which matches ReferenceByIdentifiers locations

2. Packages

The created API is composed of two new core packages.

  • ReferenceSystem (RS) : contains a new API for Compound Reference Systems. Allowing to aggregate DGGRS with additional dimensions, such as time (the temporal dimension) and height above the surface (the vertical dimension).
  • DiscreteGlobalGridReferenceSystem (DGGRS) : contains the new DGGRS API.

3. Discrete Global Grid Reference System package

The UML below is the result from aggregation and factorization of the different API which exist in : OGC DGGRS API Topic 21, H3geo, S2geometry, DGGAL and Healpix CDS.

 I won’t go in the details here since there are a lot of classes and methods, but feel free to check the code for more informations.

4. Reference System package

Since all the DGGRSes that were used in the pilot where limited to 2D and most that exist are limited to 2D. We needed a solution for combining it with additional dimensions to support time and elevation.

 

This resulted in us creating an API composed of three classes: Code, CompoundRS, and CodeOperation, which share the same organization as DirectPosition, CoordinateReferenceSystem, and Operation.

 

They extends the scope of transformation to all kind of Reference systems, whether they use numerical or textual indexing. Allowing transformation for DGGRS, MGRS, GeoHash, OLS or any kind of code or coordinate base systems. 

The API is simple, yet very powerful. It goes way beyond DGGRS.

 For example we often say ‘meet me at {address} at {time}’.
 This can be translated to a Code  object with two components [{address}, {time}] and a Compound Reference System composed of your local country postal code system and a classic temporal reference system.
 Then you ask the API to give you the CodeOperation to transform this to a common coordinate reference system, like Mercator EPSG:3395, and there you go.

 And this works with any kind of reference system combination, MGRS, EPSG, IAU, DGGRS, postal codes..

5. Java Examples

In the end, what does this look like for a developer?

//pick a DGGS implementation : A5, H3, Healpix, ...
final DiscreteGlobalGridReferenceSystem dggrs = DiscreteGlobalGridReferenceSystems.forCode(« H3 ») ;

//create a coder instance to perform queries
final Coder coder = dggrs.createCoder();

//get a zone for a location
final String hash = coder.encode(new DirectPosition2D(12.345, 67.89));

//get a zone for a known identifier
final Zone zone  = coder.decode("811fbffffffffff");

//extract various information from the zone
final DirectPosition position = zone.getPosition(); //centroid
final Collection<? extends Zone> children = zone.getChildren();
final Collection<? extends Zone> neighbors = zone.getNeighbors();
final Collection<? extends Zone> parents = zone.getParents();
final Envelope envelope = zone.getEnvelope();
final GeographicExtent geometry = zone.getGeographicExtent();
final Double areaMetersSquare = zone.getAreaMetersSquare();

6. Next part

In the next DGGRS blog post we will see the OGCAPI DGGRS implementation in the Examind-Community server.

Menu
Linkedin Twitter Youtube