Abstract DGGRS providers

To implement a DGGRS provider, users need to provide the implementation of the five interfaces listed below:

  • get_cls_by_zone_level

  • get_zone_level_by_cls

  • get_cells_zone_level

  • get_relative_zonelevels

  • zone_id_from_textual

  • zone_id_to_textual

  • zoneslist

  • zonesinfo

DGGRS zone ID representation

The API always assumes the zone ID from requests is using the ‘textual’ representation. The definition of textual zone ID representation depends on the DGGRS and the DGGRS provider implementation.

For the API to support datasources with different zone ID representations of the same grid, the DGGRS provider has to implement he following two functions to support conversion between the textual and others’ representations of the zone ID, both functions take two parameters: zone_ids and zone_id_repr.

  • zone_id_from_textual: converts zone IDs from the textual format to the representation specified by zone_id_repr.

  • zone_id_to_textual : converts zone IDs from the representation specified by zone_id_repr to the textual format.

DGGRS conversion

Apart from the mandatory functions listed above, a DGGRS provider can support optional conversion from itself to other DGGRS (target).

The main idea behind achieving the purpose is straightforward: give a list of original zone IDs, and map the list to the corresponding target zone IDs. For the current implementation, the return of the convert function has to ensure that the length of the original zone ID list is the same as the converted one. The constraint implies that the target refinement level is greater (coarser) than or equal to the source refinement level.

To implement the conversion feature, the provider has to:

  1. Initialise the dggrs_conversion to register the target dggrs ID with an object instance from conversion_properties.

  2. Implement the convert interface.

The conversion_properties class stores the necessary conversion info if needed; it is not used anywhere in pydggsapi.

Implementations