Volumetric DGGS Scripts Package

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

Volumetric DGGS Scripts Submodules

The following submodules are defined by this package.

volumetric_dggs.scripts.file_handler module

Created on 16Jul.,2017

@author: Dr. Matthew B.J. Purss

src.volumetric_dggs.scripts.file_handler.handle_uploaded_file(dggs_type, file_type, upload_dir, f)

volumetric_dggs.scripts.volumetric_dggs_operations module

volumetric_dggs.scripts.volumetric_dggs_setup module

Note

Module Details

Volumetric 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 surface_dggs.scripts.surface_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.volumetric_dggs.scripts.volumetric_dggs_setup.DGGS_Voxel(dggs_params, mongodbname, cell_id, shell_id, voxel_id='0', equalise_cells_flag=False)

Bases: object

Note

Class Details `DGGS_Voxel Class Structure`

Each Voxel is constructed from an extension of a surface DGGS along the radial expansion from a lower ellipsoid shell to an upper ellipsoid shell.

Note

Key defining elements of a Voxel are:

  • cell_id = surface DGGS cell id

  • shell_id = the id of the upper ellipsoid shell bounding this voxel

    shell_id comprises the shell reference + the resolution level (e.g. -1_3 = shell “-1” for a refinement resolution of “3”)

  • voxel_id = the ellipsoidal morton code for this voxel

  • upper_cell = vertices and edge specifications of the upper bounding DGGS cell

  • lower_cell = vertices and edge specifications of the lower bounding DGGS cell

  • voxel_centroid = the ECEF coordinates of the voxel centroid

Parameters:

  • dggs_params (JSON, required) –

    The key parameters of this Voluemtric DGGS instance in JSON format. 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}

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

  • cell_id (str, required) – The Surface DGGS Zone Identifier - this is the OGC API - DGGS {zoneID}

  • shell_id (str, required) –

    The ellipsoidal shell that this Voxel (i.e. Volumetric DGGS Zone) will be instantiated on.

    This is defined as the id of the upper ellipsoid shell bounding this voxel

    shell_id comprises the shell reference + the resolution level (e.g. -1_3 = shell “-1” for a refinement resolution of “3”)

  • voxel_id (str, optional, default='0') – The ellipsoidal morton code for this voxel

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.

get_shell_dggs(a)

Note

Function Details

Internal function to get the Surface DGGS for a specific ellipsoidal shell

Parameters:

a (float, required) – The semi-major ellipsoidal radius of the virtual Earth Model. For ellipsoids of rotation (like the Earth Model) this is equivalent to the Equatorial Radius from the centre of the Earth. This application of this parameter is used to define larger or smaller ellipsoids that are scaled versions of the fundamental Earth Model.

Returns:

shell_dggs – The Surface DGGS Class Object for the DGGS instance on the specified ellipsoidal shell.

Return type:

Class-Object

load_voxel()

Note

Function Details

Internal function to load the this voxel into memory.

load_voxel_mesh()

Note

Function Details

Internal function to load the 3D mesh of this voxel into memory.

store_voxel()

Note

Function Details

Internal function to store this voxel into the MongoDB database.

voxel_verts_df

#=================================================================== # get voxel centroid #===================================================================

class src.volumetric_dggs.scripts.volumetric_dggs_setup.VolumetricDGGS(resolution_max=28, refinement_ratio=9, max_radius_multiple=2, shell_dggs_type='rHealPIX', 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_volume_threshold=1e-06, equal_volume_percentError_Limit=1.0, a_min=0.0, a_max=12756274.0)

Bases: object

Note

Class Details `VolumetricDGGS Class Structure`

This Class handles the creation and management of Volumetric 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.

  • shell_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_volume_threshold (float, optional, default= 0.000001) – The maximum DGGS zone volume uncertainty (relative to the nominal reference zone volume) in m^3 that is acceptible between DGGS Zones at a given refinement level. The default value of 0.000001 is equivalent to 1 cm^3.

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

  • a_min (float, optional, default=1.0) – The minimum semi-major ellipsoidal axis radius of the earth model in metres to define the voxels of this Volumetric DGGS instance within

  • a_max (float, optional, default=1.0) – The maximum semi-major ellipsoidal axis radius of the earth model in metres to define the voxels of this Volumetric DGGS instance within

add_resolution(new_res)

Note

Function Details

Internal function to add a new level in the DGGS resolution hierarchy.

Parameters:

new_res (int, required) – the new resolution level to add to this DGGS instances resolution hierarchy.

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

auth_radius

initialise the dggs parameters

get_shell_dggs(a)

Note

Function Details

Internal function to get the Surface DGGS for a specific ellipsoidal shell

Parameters:

a (float, required) – The semi-major ellipsoidal radius of the virtual Earth Model. For ellipsoids of rotation (like the Earth Model) this is equivalent to the Equatorial Radius from the centre of the Earth. This application of this parameter is used to define larger or smaller ellipsoids that are scaled versions of the fundamental Earth Model.

Returns:

shell_dggs – The Surface DGGS Class Object for the DGGS instance on the specified ellipsoidal shell.

Return type:

Class-Object

get_voxel(voxel_id, parallel_job=False)

Note

Function Details

Internal function to add a new level in the DGGS resolution hierarchy.

Parameters:

  • voxel_id (str, required) – The ellipsoidal morton code for this voxel

  • parallel_job (boolean, optional, default=False) – Flag to select whether or not to run this process as a serial, or parallel, job.

Returns:

selected_voxel – The Selected Voxel Object.

Return type:

Class-Object

initialise_referenceframe()

Note

Function Details

Internal function to initialise the DGGS Reference Frame

origin_xyz_df

get DGGS shell radii - makes operation of the Solid Earth DGGS more efficient to pre-compute the all shell radii

synchronise_dggs(results_filename='', search_box='', ref_location=[], search_radius=0.0, resolution_range=[], min_radius=0.0, max_radius=1000000.0, chunk_size=1000, search_type='cellID', get_all_cells_flag=False, equalise_cells_flag=True, construct_cells_flag=True, full_sync=False)

Note

Function Details Internal function to synchronise the volumetric and surface DGGS instances as per the searchbox for the given resolution check that there is a corresponding Voxel/Volumetric DGGS Zone for every Surface DGGS Zone.

Parameters:

  • results_filename (str, optional default='') – Results Filename

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

  • ref_location (array-like, optional, default=[]) – The Reference Location in Earth Centred Earth Fixed (ECEF) Geodetic XYZ coordinates

  • search_radius (float, optional, default=0.0) – The search radius from the Reference Location in metres

  • resolution_range (array-like, optional, default=[]) – The Resolution Range to search over.

  • min_radius (float, optional, default=0.0) – The minimum ellipsoidal radius to search over

  • max_radius (float, optional, default=0.0) – The maximum ellipsoidal radius to search over

  • 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.

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

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

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

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

  • full_sync (boolean, optional, default=False) – A Flag to select whether or not to conduct a full synchronisation of this Volumentric DGGS instance.

src.volumetric_dggs.scripts.volumetric_dggs_setup.construct_ellipsoid_shells_callback(task_id, task_result)

Note

Function Details

callback function that recieves and manages the output from the construct_ellipsoid_shells_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.volumetric_dggs.scripts.volumetric_dggs_setup.create_voxel_callback(task_id, task_result)

Note

Function Details

callback function that recieves and manages the output from the create_voxel_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.volumetric_dggs.scripts.volumetric_dggs_setup.get_voxel_verts_callback(task_id, task_result)

Note

Function Details

callback function that recieves and manages the output from the get_voxel_verts_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

volumetric_dggs.scripts.tesseract_dggs_setup module

volumetric_dggs.scripts.volumetric_dggs_setup tasks

src.volumetric_dggs.scripts.volumetric_dggs_setup.create_voxel_task(dggs_store, cell_id, shell_id, dggs_params)

Note

Function Details

Celery Task to Create Volumetric DGGS Zones in parallel.

Parameters:

  • dggs_store (str, required) – MongoDB database to store the dggs structure in. This is automatically generated to ensure the dggrsID is unique.

  • cell_id (str, required) – Surface DGGS Zone Identifier.

  • shell_id (str, required) – Volumetric DGGS Ellipsoidal Shell Identifier.

  • dggs_params (JSON, required) –

    JSON representation of DGGS instance specification. 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}

Returns:

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

Return type:

JSON

src.volumetric_dggs.scripts.volumetric_dggs_setup.get_registered_voxels_task(dggs_specs, dggs_store, test_voxels)

Note

Function Details

Celery Task to Retrieve Registered Volumetric DGGS Zones from the database in parallel.

Parameters:

  • dggs_specs (JSON, required) –

    JSON representation of DGGS instance specification. 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}

  • dggs_store (str, required) – MongoDB database to store the dggs structure in. This is automatically generated to ensure the dggrsID is unique.

  • test_voxels (array-like, required) – Array/List containing the test voxel identifiers.

Returns:

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

Return type:

JSON

src.volumetric_dggs.scripts.volumetric_dggs_setup.get_voxel_verts_task(dggs_params, voxel_id)

Note

Function Details Celery Task to Get the Vertices of the specified Volumetric DGGS Zone in parallel.

Parameters:

  • dggs_params (JSON, required) –

    JSON representation of DGGS instance specification. 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}

  • voxel_id (str, required) – The ellipsoidal morton code for this voxel

Returns:

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

Return type:

JSON

src.volumetric_dggs.scripts.volumetric_dggs_setup.construct_ellipsoid_shells_task(mongodbname, res=0, a_min=0.0, a_max=12756274.0, shell_chunk=[], n_shells=1, dggs_params={})

Note

Function Details

Celery Task to contruct the ellipsoidal shells for the specified Volumetric DGGS instance in parallel.

Parameters:

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

  • res (int, optional, default=0) – The DGGS resolution to construct the ellipsoidal shell tree on.

  • a_min (float, optional, default=1.0) – The minimum semi-major ellipsoidal axis radius of the earth model in metres to define the voxels of this Volumetric DGGS instance within

  • a_max (float, optional, default=1.0) – The maximum semi-major ellipsoidal axis radius of the earth model in metres to define the voxels of this Volumetric DGGS instance within

  • shell_chunk (array-like, optional, default= []) – The chunk of shells to create - this is a throttling and memory management parameter.

  • n_shells (int, optional, default=1) – The number of shells to construct.

  • dggs_params (JSON, required) –

    The key parameters of this Voluemtric DGGS instance in JSON format. 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}

Returns:

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

Return type:

JSON

src.volumetric_dggs.scripts.volumetric_dggs_setup.celery_task_loader(task_type, dggs_specs={}, test_voxels=[], voxel_params=[], ellipsoid_shell_params={}, chunk_size=1000)

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}

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

  • voxel_params (array-like, optional, default=[]) – The array/list of parameters for the voxels to work on.

  • ellipsoid_shell_params (array-like, optional, default=[]) – The array/list of ellipsoid_shell_params for the task to work on.

  • 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:

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

Return type:

JSON