Update current best practice for IGEO7

[allixender]

Update current best practice for IGEO7 in docs:

• https://dggrid4py.readthedocs.io/en/latest/usage.html#igeo7-usage

dggrid4py introduced a new class, DGGRIDv8, that aligns the setting parameters (meta configuration) with newer DGGRID versions (8.4.3).

To import the new class and create an instance:

from dggrid4py import DGGRIDv8

dg = DGGRIDv8( executable=str(DGGRID_EXE), working_dir=str(BASE_DIR), capture_logs=False, silent=False )

I would suggest creating a meta-config dictionary at the start to store commonly used settings, such as the format for input/output zone IDs. Then, this dictionary can be passed to the dggrid4py functions. For example:

meta_config = { 
                # input zone ids representation
                "input_address_type":  'HIERNDX', # hierarchy index 
                "input_hier_ndx_system": 'Z7', # z7 hierarchy
                "input_hier_ndx_form":  'DIGIT_STRING', # z7 textual representation (e.g. '003456231')
                # output zone ids representation
                "output_address_type":  'HIERNDX', 
                "output_cell_label_type":  'OUTPUT_ADDRESS_TYPE',
                "output_hier_ndx_system":  'Z7',
                "output_hier_ndx_form":  'DIGIT_STRING',
                # initial vertex longitude
                "dggs_vert0_lon": 11.20
               }

You can specify input_hier_ndx_form and output_hier_ndx_form to either DIGIT_STRING or INT64. It specifies the input/output format of the z7 zone ID. When using DIGIT_STRING in input_hier_ndx_form, DGGRID expects the z7 zone ID in textual form (i.e. Z7_STRING), for example: 003456231. The same applies to output_hier_ndx_form, but for output. INT64 specifies the z7 zone ID in integer representation.

Authalic conversion

In the current version of DGGRID, it uses an authalic sphere as the reference model for the Earth, so when passing geopoints or extents in wgs84 that use an ellipsoid as the reference model, it causes a discrepancy. So, we need to convert the input coordinates from wgs84 to authalic, and convert the output back from authalic to wgs84. You can perform the conversion using geoseries_to_authalic and geoseries_to_geodetic from dggrid4py.auxlat.

Example :

from dggrid4py import DGGRIDv8
from dggrid4py.auxlat import geoseries_to_authalic, geoseries_to_geodetic
from geopandas import GeoSeries
import shapely 

DGGRID_EXE = "path_to_dggrid"
BASE_DIR = "path_to_temp_dir"

dg = DGGRIDv8( executable=str(DGGRID_EXE), working_dir=str(BASE_DIR), capture_logs=False, silent=False )


meta_config = { 
                # input zone ids representation
                "input_address_type":  'HIERNDX', # hierarchy index 
                "input_hier_ndx_system": 'Z7', # z7 hierarchy
                "input_hier_ndx_form":  'DIGIT_STRING', # z7 textual representation (e.g. '003456231')
                # output zone ids representation
                "output_address_type":  'HIERNDX', 
                "output_cell_label_type":  'OUTPUT_ADDRESS_TYPE',
                "output_hier_ndx_system":  'Z7',
                "output_hier_ndx_form":  'DIGIT_STRING',
                # initial vertex longitude
                "dggs_vert0_lon": 11.20
               }


extent = GeoSeries([shapely.box(11.12295334,58.07561496,11.70058751,58.49571253)])

# apply authalic conversion to the extent
extent = geoseries_to_authalic(extent)

# generate IGE7 zones for the extent, passing the meta_config dictionary
hexes_4326 = dg.grid_cell_polygons_for_extent( dggs_type="IGEO7", resolution=RESOLUTION, clip_geom=extent.geometry[0], **meta_config)

# convert back to wgs84
hexes_4326['geometry'] = geoseries_to_geodetic(hexes_4326['geometry'])

Hope this helps.