Surface DGGS Scripts Package

The Surface DGGS Scripts Package contains the python scripts required to instantiate and manipulate Surface DGGS Instances.

Surface DGGS Scripts Submodules

The following submodules are defined by this package.

surface_dggs.scripts.surface_dggs_setup module

Note

Module Details

Surface DGGS Setup Script

This Module contains the core internal functions to build and manipulate DGGS instances through the TerraNexus Web Application.

This module, coupled with the volumetric_dggs.scripts.volumetric_dggs_setup module as well as the common utility functions defined in the util.dggs_operations module and the util.dggs_util module, represents a production grade implementation of Patent WO2018/136996 Purss and Pangaea-Innovations-Pty.-Ltd. [2017]

Created: 25 October 2016

@author: Dr. Matthew B.J. Purss

class src.surface_dggs.scripts.surface_dggs_setup.DGGS_Cell(mongodbname, cell_id='0', verts=[], edges=[], fixed_edges=[], colatitudes=[], surface_area=510638100096000.0, earth_model='WGS84', a=6378137.0, auth=6371007.2, f=0.003352810681182319, dggs_type='TerraNexus', cell_centroid=[], isolatitude_flag=[])

Bases: object

Note

Class Details `DGGS_Cell Class Structure`

This Class handles the creation and management of Surface DGGS Zones.

Parameters:

  • mongodbname (str, required) – The name of the MongoDB database for the selected DGGS instance - this is the OGC API - DGGS {dggrsID}

  • cell_id (str, optional, default='0') – The DGGS Zone Identifier - this is the OGC API - DGGS {zoneID}

  • verts (array-like, optional, default=[]) – The array/list of vertex coordinates for the DGGS Zone.

  • edges (array-like, optional, default=[]) – The array/list of edges for the DGGS Zone. Each edge is defined as a plane through two vertices using “normal” notation.

  • fixed_edges (array-like, optional, default=[]) –

    The index of edges to fix in space during area equalisation

    Note

    This feature is Deprecated.

  • colatitudes (array-like, optional, default=[]) – The array/list of edge colatitudes. A colatitude is the angle of inclination of a plane from the normal through the centre of the Earth. 90 degrees is parallel to the normal - i.e. a Great Circle/Ellipse.

  • surface_area (float, optional, default=5.10638100096e+14,) –

    The reference surface area of the DGGS Zone.

    Note

    This feature is Deprecated.

  • earth_model (str, optional, default='WGS84') – The Earth Model of the host DGGS Instance.

  • a (float, optional, default=6378137.0) – The semi-major ellipsoidal radius of the Earth Model. For ellipsoids of rotation (like the Earth Model) this is equivalent to the Equatorial Radius from the centre of the Earth.

  • auth (float, optional, default=6371007.2) – The Authalic Sphere Radius. The Authalic Sphere is a sphere constructed to have the same volume as the Earth Model but able to leverage the much simpler mathematics associated with spherical geometries compared to ellipsoidal geometries.

  • f (float, optional, default=1/298.257222101) – The Earth Flattening Ratio. The Ratio of flattening of the polar axes verses the equatorial axes of the Earth Model to properly define the ellipsoid of rotation.

  • dggs_type (str, optional, default='TerraNexus') – The Type of DGGS that is hosting this DGGS Zone. Currently ‘rHealPIX’ and local ‘TerraNexus’ DGGSs are implemented. This will be and can be expanded as needed to include other third party DGGS libraries.

  • cell_centroid (array-like, optional, default=[]) –

    The centroid of the DGGS Zone being instantiated.

    Note

    This feature is Deprecated.

  • isolatitude_flag (array-like, optional, default=[]) – Array/List of edges that are isolatitudinal (i.e. run parallel to the lines of latitude). This flag is used to determine if the simple or comprehensive computation of the ellipsoidal arc between the two vertices along the DGGS Zone Edge should be used.

store_cell()

Note

Function Details

Internal function to store the DGGS Zone object in the MongoDB Database.

update_cell()

Note

Function Details

Internal function to update the structure and content of the DGGS Zone object. For example, if the DGGS Zone’s edges are adjusted to equalize the zone surface area this function will be called to update the DGGS Zone structural data.

class src.surface_dggs.scripts.surface_dggs_setup.SurfaceDGGS(resolution_max=28, refinement_ratio=9, max_radius_multiple=2, dggs_type='TerraNexus', base_polyhedron='icosahedron', cell_type='triangle', earth_model='GRS80', a=6378137.0, f=1, ref_lon=200.0, ref_lat=200.0, equalise_area=True, equal_area_threshold=0.0001, equal_area_percentError_Limit=1.0)

Bases: object

Note

Class Details `SurfaceDGGS Class Structure`

This Class handles the creation and management of Surface DGGS instances.

Parameters:

  • resolution_max (int, optional, default=28) – The maximum DGGS hierarchy resolution - i.e. the number of levels of refinement defined for this Surface DGGS instance.

  • refinement_ratio (int, optional, default=9) – The Refinement Ratio governing the number of Child Zones to each Parent Zone.

  • max_radius_multiple (int, optional, default=2) – The Maximum Earth Model Radius multiple to use for the construction of the DGGS. This parameter is not needed to construct a Surface DGGS, but is included for consistency with the structural components of TerraNexus Volumetric DGGS instances.

  • dggs_type (str, optional, default="TerraNexus") – The “type” of the DGGS instance to be built. The default is “TerraNexus”, but can be an external DGGS library identifier, such as “rHealPIX” or “H3”.

  • base_polyhedron (str, optional, default="icosahedron") –

    The “base polyhedron” used to construct the initial Surface DGGS Tessellation. This can be one of the following values:

    • tetrahedron,

    • cube (hexahedron),

    • octahedron, or,

    • icosahedron

  • cell_type (str, optional, default="triangle") –

    The topological geometry shape for each DGGS Zone. This can be one of the following:

    • triangle, or,

    • square

  • earth_model (str, optional, default="GRS80") –

    The Earth Model to use as the tessellation surface for the Surface DGGS. The earth_model can be one of the following:

    • ”authalic_sphere”,

    • ”unit_sphere”,

    • ”GRS80”, or,

    • ”WGS84_G1762”

  • a (float, optional, default=6378137.0) – The semi-major ellipsoidal axis radius of the earth model in metres. This is equivalent to the equatorial radius

  • f (float, optional, default=1.0) – The earth flattening ratio that defines the degree of flattening of the Earth at its poles. This determines the semi-minor ellipsoidal axis radius of the earth model (i.e. the polar radius).

  • ref_lon (float, optional, default=0.0) – The reference longitude to fix the orientation of the Surface DGGS tessellation to.

  • ref_lat (float, optional, default=0.0) – The reference latitude to fix the orientation of the Surface DGGS tessellation to.

  • equalise_area (boolean, optional, default=True) – A Flag to select whether or not DGGS zone edge refinement will be conducted to ensure every zone for a given refinement level is exactly “equal area” within a specified level of uncertainty.

  • equal_area_threshold (float, optional, default= 0.0001) – The maximum DGGS zone area uncertainty (relative to the nominal reference zone area) in m^2 that is acceptible between DGGS Zones at a given refinement level. The default value of 0.0001 is equivalent to 1 cm^2.

  • equal_area_percentError_Limit (float, optional, default=1.0) – The maximum DGGS zone area uncertainty (relative to the nominal reference zone area) as a percentage.

auth_lat(phi, e, inverse=False, radians=False)

Note

Function Details

Given a point of geographic latitude phi on an ellipse of eccentricity e, return the authalic latitude of the point. If inverse =True, then compute its inverse approximately.

EXAMPLES:

>>> beta = auth_lat(pi/4, 0.5, radians=True)
>>> print(my_round(beta, 15))
0.689518212435
>>> print(my_round(auth_lat(beta, 0.5, radians=True, inverse=True), 15))
0.785126523581
>>> print(my_round(pi/4, 15))
0.785398163397448

Note

The power series approximation used for the inverse is standard in cartography (PROJ.4 uses it, for instance) and accurate for small eccentricities.

Parameters:

  • phi (float, required) – The geographic latitude

  • e (float, required) – The ellipsoidal eccentricity

  • inverse (boolean, optional, default=False) – compute inverse approximation

  • radians (boolean, optional, default=False) – use radians instead of degrees for the computation.

Returns:

authalic_latitude – The authalic sphere latitude for the given geographic latitude.

Return type:

float

auth_rad(a, f)

Note

Function Details

Return the radius of the authalic sphere of the ellipsoid with major radius a and eccentricity e. If inverse = True, then return the major radius of the ellipsoid with authalic radius a and eccentricity e.

EXAMPLES:

>>> auth_rad(1, 0)
1
>>> for i in range(2, 11):
...     e = 1.0/i**2
...     print(my_round((e, auth_rad(1, 1.0/i**2)), 15))
(0.25, 0.98939325967009495)
(0.111111111111111, 0.99793514742994305)
(0.0625, 0.99934823645582505)
(0.04, 0.99973321235361001)
(0.027777777777778, 0.99987137105187995)
(0.020408163265306, 0.99993057628561399)
(0.015625, 0.99995930708084702)
(0.012345679012346, 0.99997459627121099)
(0.01, 0.99998333286108898)
Parameters:

  • a (float, required) – The semi-major ellipsoidal axis radius of the earth model in metres. This is equivalent to the equatorial radius

  • f (float, required) – The earth flattening ratio that defines the degree of flattening of the Earth at its poles. This determines the semi-minor ellipsoidal axis radius of the earth model (i.e. the polar radius).

Returns:

authalic_radius – The authalic sphere radius for the given ellipsoid.

Return type:

float

construct_child_cells_callback(task_id, task_result)

Note

Function Details

Internal callback function that recieves and manages the output from the construct_cells_task asynchronous Celery Task.

Parameters:

  • task_id (str, required) – identifier of the task currently being run.

  • task_result (JSON, required) – task results in JSON format

delete_zone(zoneId)

Note

Function Details

Internal function to delete a DGGS Zone from the Database - this is used in situations where the database record of the DGGS Zone has become corrupted.

Parameters:

zoneId (str, required) – ZoneId of the DGGS Zone to delete from the MongoDB database.

equalise_cell_area(dggs_cell, parent_cell=None)

Note

Function Details This function equalises the DGGS Zone surface area by adjusting the small ellipses that define the cell boundaries until the error between the calculated surface area and the reference nominal surface area for the current level in the DGGS resolution hierarchy is within the uncertainty limits.

This function utilises a Deep Learning Artificial Intelligence (AI) driven regression model to test thousands of possible DGGS Zone edge colatitudes in parallel to find the Best edge configuration that minimises the Surface Area Error of the dGGS Zone of interest to within the specified uncertianty limits.

Parameters:

  • dggs_cell (Class-Object, required) – The DGGS_Cell class object instance for the DGGS Zone of interest.

  • parent_cell (Class-Object, optional, default=None) – The DGGS_Cell class object instance for the Parent Zone of the DGGS Zone of interest.

Returns:

area_equalised_dggs_cell – The DGGS_Cell class object instance for the Surface Area Equalised DGGS Zone of interest.

Return type:

Class-Object

get_cells(search_box=[], res_min=0, res_max=1, search_type='search_box', construct_cells=True, equalise_cells=True, generate_cell_mesh=False, construct_cells_key='construct_cells_key__', chunk_size=10000)

Note

Function Details

This function retrieves a list of DGGS Zones from a Surface DGGS instance

Parameters:

  • search_box (array-like, optional, default=[]) – The Search Box in Earth Centred Earth Fixed (ECEF) Geodetic XYZ coordinates

  • res_min (int, optional, default=0) – The minimum DGGS resolution to search for zones that are within the search_box.

  • res_max (int, optional, default=1) – The maximum DGGS resolution to search for zones that are within the search_box.

  • search_type (str, optional, default='search_box') – The search type to apply in order to retrieve the DGGS Zones from this DGGS instance.

  • construct_cells (boolean, required) – A Flag to select whether or not to construct zones of the Surface DGGS if they haven’t already been created and registered.

  • equalise_cells (boolean, required) – A Flag to select whether or not to equalise the surface area of the created Surface DGGS zone

  • generate_cell_mesh (boolean, optional, default=False) – A Flag to select whether or not to construct a 3D mesh of the DGGS zones once they have been found.

  • construct_cells_key (str, optional, default=’construct_cells_key__’) – Unique identifier for the task.

  • chunk_size (int, optional, default=10000) – Chunk size to use to throttle the process to ensure it does not exceed the hardware memory resource capacity.

Returns:

registered_zones_result_df – The set of retrieved DGGS Zones from this DGGS instance in a JSON/Dictionary format.

Return type:

JSON

get_child_cells_callback(task_id, task_result)

Note

Function Details

Internal callback function that recieves and manages the output from the get_child_cells_task asynchronous Celery Task.

Parameters:

  • task_id (str, required) – identifier of the task currently being run.

  • task_result (JSON, required) – task results in JSON format

get_dggs(a, b, db_exists=False)

Note

Function Details This function builds a DGGS instance on the specified general ellipsoid

Parameters:

  • a (float, required) – semi-major ellipsoidal radius in metres

  • b (float, required) – semi-minor ellipsoidal radius in metres

  • db_exists (boolean, optional, default=False) – Flag to designate whether or not the MongoDB database already exists for this DGGS instance.

Returns:

dggs – The structural definition of the new DGGS instance in a JSON/Dictionary format.

Return type:

JSON

get_parent_cells(dggrsID, cell_id='', number_of_levels=1)

Note

Function Details

Function to get the parent Surface DGGS Zones (Cells) from a specified child Zone.

Parameters:

  • dggrsID (str, required) – The DGGS Identifier.

  • cell_id (str, required) – The topological Surface DGGS ZoneID.

  • number_of_levels (int, optional, default=1) – The number of levels up from the selected DGGS Zone to find Parent Zones.

Returns:

parent_cell_ids – The list of Parent DGGS Zones found.

Return type:

list-list

initialise_referenceframe()

Note

Function Details

Internal function to initialise the DGGS Reference Frame

load_cell(cell_id, topological_ZoneID_flag=True)

Note

Function Details

Internal function to load a specific DGGS Zone into memory.

Parameters:

cell_id (str, required) – ZoneId of the DGGS Zone to load from the MongoDB database.

recreate_zones(parent_cell, equalise_cells_flag=False)

Note

Function Details

This function Recreates the DGGS Zone hierarchy tree from the specified DGGS Zone up to the top of the tree.

Note

This function is used where the parent DGGS Cell has not been registered - go up the hierarchy to find the parent that does exist, and

  • then traverse back down to this level creating the required parent cells as you go.

Parameters:

  • parent_cell (str, required) – ZoneId of the parent cell to rebuild the Zone heirarchy for.

  • equalise_cells_flag (boolean, optional, default=False) – Flag to equalise the surface area of each DGGS Zone as the zone hierarchy is rebuilt.

Returns:

child_cell_dict – The refined base structural information for the child DGGS Zones of the specified “parent Zone”

Return type:

JSON

test_cell_area_callback(task_id, task_result)

Note

Function Details

Internal callback function that recieves and manages the output from the test_cell_area_task asynchronous Celery Task.

Parameters:

  • task_id (str, required) – identifier of the task currently being run.

  • task_result (JSON, required) – task results in JSON format

src.surface_dggs.scripts.surface_dggs_setup.background(f)

Note

Function Details

Internal function to wrap a background processing function in an asynchronous event loop using asyncio

Parameters:

f (synchronous function call)

Returns:

wrapped_function

Return type:

asychronous function

src.surface_dggs.scripts.surface_dggs_setup.get_or_create_eventloop()

Note

Function Details

Internal function to get or create an asynchronous event loop using asyncio

surface_dggs.scripts.surface_dggs_setup tasks

src.surface_dggs.scripts.surface_dggs_setup.construct_cells_task(child_cell, dggs_specs, equalise_cells_flag)

Note

Function Details

Celery Task to Construct Specific Surface DGGS Zones in parallel.

Parameters:

  • child_cell (str, required) – The DGGS ZoneId of the Surface DGGS Cell to be created

  • dggs_specs (JSON, required) –

    JSON/Dictionary object with the specifications for the selected Surface DGGS Instance. For example

    {'resolution_max':      15,
 'refinement_ratio':    9,
 'max_radius_multiple': 2,
 'shell_dggs_type':    'TerraNexus',
 'base_polyhedron':    'cube',
 'cell_type':          'square',
 'earth_model':        'GRS80',
 'a':                  6378137.0,
 'f':                  1.0,
 'ref_lon':            0.0,
 'ref_lat':            0.0}

  • equalise_cells_flag (boolean, required) – A Flag to select whether or not to equalise the surface area of the created Surface DGGS zone

Returns:

output_dict – JSON compatible dictionary object is returned with details of the created DGGS Zone.

Return type:

JSON

src.surface_dggs.scripts.surface_dggs_setup.get_child_cells_task(parent_cell, dggs_specs, search_radius, search_box_xyz, resolution_min, resolution_max, get_all_cells_flag, construct_cells_flag, equalise_cells_flag, generate_cell_mesh_flag=False, construct_cells_key='')

Note

Function Details

Celery Task to Construct Specific Surface DGGS Zones in parallel.

Parameters:

  • parent_cell (str, required) – The DGGS ZoneId of the Parent Surface DGGS Cell to be refined

  • dggs_specs (JSON, required) –

    JSON/Dictionary object with the specifications for the selected Surface DGGS Instance. For example

    {'resolution_max':      15,
 'refinement_ratio':    9,
 'max_radius_multiple': 2,
 'shell_dggs_type':    'TerraNexus',
 'base_polyhedron':    'cube',
 'cell_type':          'square',
 'earth_model':        'GRS80',
 'a':                  6378137.0,
 'f':                  1.0,
 'ref_lon':            0.0,
 'ref_lat':            0.0}

  • search_radius (float, required) – The Search Radius in metres from a Reference Location (i.e. the centroid of the search box)

  • search_box_xyz (array-like, required) – The Search Box in Earth Centred Earth Fixed (ECEF) Geodetic XYZ coordinates

  • resolution_min (int, optional, default=0) – The minimum DGGS resolution to search for zones that are within the search_box.

  • resolution_max (int, optional, default=1) – The maximum DGGS resolution to search for zones that are within the search_box.

  • get_all_cells_flag (boolean, required) – A Flag to select whether or not to return all zones of the Surface DGGS.

  • construct_cells_flag (boolean, required) – A Flag to select whether or not to construct zones of the Surface DGGS if they haven’t already been created and registered.

  • equalise_cells_flag (boolean, required) – A Flag to select whether or not to equalise the surface area of the created Surface DGGS zone

  • generate_cell_mesh_flag (boolean, optional, default=False) – A Flag to select whether or not to construct a 3D mesh of the DGGS zones once they have been found.

  • construct_cells_key (str, optional, default="") – Unique identifier for the task.

Returns:

output_dict – JSON compatible dictionary object is returned with details of the DGGS Zone.

Return type:

JSON

src.surface_dggs.scripts.surface_dggs_setup.celery_task_loader(task_type, dggs_specs={}, parent_cells=[], search_radius=0, search_box_xyz=[], resolution_min=0, resolution_max=1, get_all_cells_flag=False, construct_cells_flag=True, equalise_cells_flag=True, generate_cell_mesh_flag=False, construct_cells_key='', cell_df=Empty DataFrame Columns: [] Index: [], cell_verts_df=Empty DataFrame Columns: [] Index: [], cell_edges=[], fixed_edges=[], colatitudes=[])

Note

Function Details Celery Task that acts as a task loader to sub-tasks in parallel.

Parameters:

  • task_type (str, required) – The name of the task to load and run.

  • dggs_specs (JSON, optional, default={}) –

    JSON/Dictionary object with the specifications for the selected Surface DGGS Instance. For example

    {'resolution_max':      15,
 'refinement_ratio':    9,
 'max_radius_multiple': 2,
 'shell_dggs_type':    'TerraNexus',
 'base_polyhedron':    'cube',
 'cell_type':          'square',
 'earth_model':        'GRS80',
 'a':                  6378137.0,
 'f':                  1.0,
 'ref_lon':            0.0,
 'ref_lat':            0.0}

  • parent_cells (array-like, optional, default=[]) – The array/list of parent zones to refine.

  • search_radius (float, required) – The Search Radius in metres from a Reference Location (i.e. the centroid of the search box)

  • search_box_xyz (array-like, required) – The Search Box in Earth Centred Earth Fixed (ECEF) Geodetic XYZ coordinates

  • resolution_min (int, optional, default=0) – The minimum DGGS resolution to search for zones that are within the search_box.

  • resolution_max (int, optional, default=1) – The maximum DGGS resolution to search for zones that are within the search_box.

  • get_all_cells_flag (boolean, required) – A Flag to select whether or not to return all zones of the Surface DGGS.

  • construct_cells_flag (boolean, required) – A Flag to select whether or not to construct zones of the Surface DGGS if they haven’t already been created and registered.

  • equalise_cells_flag (boolean, required) – A Flag to select whether or not to equalise the surface area of the created Surface DGGS zone

  • generate_cell_mesh_flag (boolean, optional, default=False) – A Flag to select whether or not to construct a 3D mesh of the DGGS zones once they have been found.

  • construct_cells_key (str, optional, default="") – Unique identifier for the task.

  • cell_df (JSON, optional, default={}) – JSON representation of a Pandas DataFrame containing the core metadata of a DGGS Zone

  • cell_verts_df (JSON, optional, default={}) – JSON representation of a Pandas DataFrame containing the vertices metadata of a DGGS Zone

  • cell_edges (JSON, optional, default={}) – JSON representation of a Pandas DataFrame containing the zone edge metadata of a DGGS Zone

  • fixed_edges (array-like, optional, default=[]) – Array/List containing the fixed zone edges of a DGGS Zone

  • colatitudes (array-like, optional, default=[]) – Array/List of colatitudes of each zone Edge. The colatitude measures the amoung of tilt/rotation of a Zone Edge about an axis through the two end vertices of that edge.

Returns:

output_dict – JSON compatible dictionary object is returned with the results of the sub-task(s).

Return type:

JSON

src.surface_dggs.scripts.surface_dggs_setup.rHealPIX_cells_from_region(dggs_specs={}, res=0, ul=(0.0, 0.0), dr=(0.0, 0.0), plane=False)

Note

Function Details

Celery Task to search an rHealPIX Surface DGGS for zones within a region.

Parameters:

  • dggs_specs (JSON, optional, default={}) –

    JSON/Dictionary object with the specifications for the selected Surface DGGS Instance. For example

    {'resolution_max':      15,
 'refinement_ratio':    9,
 'max_radius_multiple': 2,
 'shell_dggs_type':    'TerraNexus',
 'base_polyhedron':    'cube',
 'cell_type':          'square',
 'earth_model':        'GRS80',
 'a':                  6378137.0,
 'f':                  1.0,
 'ref_lon':            0.0,
 'ref_lat':            0.0}

  • res (int, optional, default=0) – The DGGS resolution to search and return zones for.

  • ul (tuple, optional, default=(0.0,0.0)) – Upper Left corner of the search region

  • dr (tuple, optional, default=(0.0,0.0)) – Lower Right corner of the search region

  • plane (boolean, optional, default=False) – Flag to select whether or not to perform and return the results on the planar view of rHealPIX.

Returns:

output_dict – JSON compatible dictionary object is returned with details of the created DGGS Zone.

Return type:

JSON

src.surface_dggs.scripts.surface_dggs_setup.rHealPIX_task_loader(task_type, dggs_specs={}, task_params={})

Note

Function Details

Celery Task to load and run a rHealPIX sub-task in parallel

Parameters:

  • task_type (str, required) – The name of the task to load and run.

  • dggs_specs (JSON, optional, default={}) –

    JSON/Dictionary object with the specifications for the selected Surface DGGS Instance. For example

    {'resolution_max':      15,
 'refinement_ratio':    9,
 'max_radius_multiple': 2,
 'shell_dggs_type':    'TerraNexus',
 'base_polyhedron':    'cube',
 'cell_type':          'square',
 'earth_model':        'GRS80',
 'a':                  6378137.0,
 'f':                  1.0,
 'ref_lon':            0.0,
 'ref_lat':            0.0}

  • task_params (JSON, optional, default={}) – JSON/Dictionary object with the specifications for the task to run.

Returns:

output_dict – JSON compatible dictionary object is returned with details of the created DGGS Zone.

Return type:

JSON