8.4.1. Mesh Construction - Classes

This section describes the main classes of the Mesh Construction module in detail. For an overview of the abstractions behind the Mesh Construction module, see the Mesh Construction - Overview section of the documentation.

8.4.1.1. MeshBuilder

The MeshBuilder object is the main class of the Mesh Construction module. It is used to build the EnvironmentalMesh object from a collection geospatial data. Features of the created EnvironmentalMesh as be set using a configuration file passed to the MeshBuilder object. For more information on the format of the configuration file, see the Configuration - Mesh Construction section of the documentation.

In this section we will discuss the usage of the MeshBuilder functionality of meshiphi.

Example

An example of how to run this code can be executed by running the following in an ipython/Jupyter Notebook:

from meshiphi.mesh_generation.mesh_builder import MeshBuilder

import json
with open('./config.json', 'r') as f:
    config = json.load(f)['config']

mesh_builder = MeshBuilder(config)
mesh_builder.build_environmental_mesh()

class meshiphi.mesh_generation.mesh_builder.MeshBuilder(config)

A class resposible for building an environment mesh based on a provided config file.

__init__(config)

Constructs a Mesh from a given config file.

Parameters:

config (dict) –

config file which defines the attributes of the Mesh to be constructed. config is of the form:

{

“region”: {

“lat_min”: (real),

”lat_max”: (real),

”long_min”: (real),

”long_max”: (real),

”start_time”: (string) ‘YYYY-MM-DD’,

”end_time”: (string) ‘YYYY-MM-DD’,

”cell_width”: (real),

”cell_height” (real),

”split_depth” (int)

},

”data_sources”: [

{

“loader”: (string)

”params” (dict)

}

],

”splitting”: {

“split_depth”: (int),

”minimum_datapoints”: (int)

}

}

NOTE: In the case of constructing a global mesh, the longtitude range should be -180:180.

”j_grid” (bool): True if the Mesh to be constructed should be of the same format as the original Java CellGrid, to be used for regression testing.

add_dataloader(Dataloader, params, bounds=None, name='myDataLoader', min_dp=5)

Adds a dataloader to a pre-existing mesh by adding to the metadata

Parameters:

Dataloader (ScalarDataLoader or VectorDataLoader) – Dataloader object to add to metadata
params (dict) – Parameters to initialise dataloader with
bounds (Boundary) –
name (str) – Name of the dataloader used in config

Returns:

Original MeshBuilder object (self) with added metadata for new dataloader

Return type:

MeshBuilder

build_environmental_mesh()

splits the mesh then goes through the mesh cellboxes and builds an evironmental mesh that contains the cellboxes aggregated data

Returns:: an object that represents the constructed nonunifrom mesh and contains the aggregated cellboxs and neighbour graph
Return type:: EnvironmentMesh

split_and_replace(cellbox)

Replaces a cellbox given by parameter ‘cellbox’ in this grid with 4 smaller cellboxes representing the four corners of the given cellbox. A neighbours map is then created for each of the 4 new cellboxes and the neighbours map for all surrounding cell boxes is updated.

Parameters:: cellbox (CellBox) – the CellBox within this Mesh to be split into 4 smaller CellBox objects.

split_to_depth(split_depth)

splits all cellboxes in this grid until a maximum split depth is reached, or all cellboxes are homogeneous.

Parameters:: split_depth (int) – The maximum split depth reached by any CellBox within this Mesh after splitting.

8.4.1.2. EnvironmentMesh

The EnvironmentMesh object is a collection of geospatial boundaries containing an aggregated representation of the data contained within the boundaries (AggregatedCellBox objects). The EnvironmentMesh object is created by the MeshBuilder object, though the object is mutable and can be updated after construction.

class meshiphi.mesh_generation.environment_mesh.EnvironmentMesh(bounds, agg_cellboxes, neighbour_graph, config)

a class that defines the environmental mesh structure and contains each cellbox aggregate information

bounds

the boundaries of this mesh

Type:: Boundary

agg_cellboxes

a list of aggregated cellboxes

Type:: AggregatedCellBox[]

neighbour_graph

an object contains each cellbox neighbours information

Type:: NeighbourGraph

config

conatins the initial config used to build this mesh

Type:: dict

__init__(bounds, agg_cellboxes, neighbour_graph, config)

Parameters:

bounds (Boundary) – the boundaries of this mesh
agg_cellboxes (AggregatedCellBox[]) – a list of aggregated cellboxes
neighbour_graph (NeighbourGraph) – an object contains each cellbox neighbours information
config (dict) – conatins the initial config used to build this mesh.

classmethod load_from_json(mesh_json)

Constructs an Env.Mesh from a given env-mesh json file to be used by other modules (ex.Vessel Performance Modeller).

Parameters:

mesh_json (dict) –

a dictionary loaded from an Env-mesh json file of the following format -

{

“mesh_info”: {

“region”: {

“lat_min”: (real),

”lat_max”: (real),

”long_min”: (real),

”long_max”: (real),

”start_time”: (string) ‘YYYY-MM-DD’,

”end_time”: (string) ‘YYYY-MM-DD’,

”cell_width”: (real),

”cell_height” (real),

”split_depth” (int)

},

”data_sources”: [

{

“loader”: (string)

”params” (dict)

},

…,

{…} ],

”splitting”: {

“split_depth”: (int),

”minimum_datapoints”: (int)

}

},

”cellboxes”: [

{

},

…,

{…}

],

”neighbour_graph”: [

{

},

…,

{…}

]

}

Returns:

object that contains all the json file mesh information.

Return type:

EnvironmentMesh

merge_mesh(mesh2)

merges the given mesh with this mesh. The given mesh is not modified.

Parameters:: mesh2 (EnvironmentMesh) – the mesh to be merged with this mesh

save(path, format='JSON', format_params=None)

Saves this object to a location in local storage in a specific format.

Parameters:

path (String) – The file location the mesh will be saved to.
format (String) (optional) –
The format the mesh will be saved in. If not format is given, default is JSON. Supported formats are
- JSON
- GEOJSON

split_and_replace(cellbox_id)

splits the cellbox with the given id and replaces it with the new cellboxes

Parameters:: cellbox_id (string) – the id of the cellbox to be split

to_geojson(params_file=None)

Returns the cellboxes of this mesh converted to a geoJSON format.

Returns:: The cellboxes of this mesh in a geoJSON format
Return type:: geojson

Note

geoJSON format does not contain all the data included in the standard .to_json() format. geoJSON meshes do not contain the configs used to build them, or the neighbour-graph which details how each of the cellboxes are connected together.

to_json()

Returns this Mesh converted to a JSON object.

Returns:

a string representation of the CellGird parseable as a JSON object. The JSON object is of the form -

{

“config”: the config used to initialize the Mesh,

”cellboxes”: a list of CellBoxes contained within the Mesh,

”neighbour_graph”: a graph representing the adjacency of CellBoxes within the Mesh.

}

Return type:

json

to_tif(params_file, path)

generates a representation of the mesh in geotif image format.

Parameters:

params_file (string) (optional) –
a path to a file that contains a dict of the folowing export parameters (If not given, default values are used for image export). The file should be of the following format -

{

“data_name”: “elevation”,

”sampling_resolution”: [

150,

150

],

”projection”: “3031”,

}

Where data_name (string) is the name of the mesh data that will be included in the tif image (ex. SIC, elevation), if it is a vector data (e.g. fuel) then the vector mean is calculated for each pixel, sampling_resolution ([int]) is a 2d array that represents the sampling resolution the geotiff will be generated at (how many pixels in the final image), projection (int) is an int representing the ESPG sampling projection used to create the geotiff image (default is 4326), and colour_conf (string) contains the path to color config file, which is a text-based file containing the association between data_name values and colors. It contains 4 columns per line: the data_name value and the corresponding red, green, blue value between 0 and 255, an example format where values range from 0 to 100 is -

0 240 250 160

30 230 220 170

60 220 220 220

100 250 250 250
path (string) – the path to save the generated tif image.

update_cellbox(index, values)

method that adds values to the dict of a cellbox at certain index (to be used by the vessel perf. module to add the perf. metrics to the cellbox)

Parameters:

index (int) – the index of the cellbox to be updated
values (dict) – a dict contains perf. metrics names and values

8.4.1.3. NeighbourGraph

The NeighbourGraph object is used to store the connectivity information between the cells of the EnvironmentMesh. The NeighbourGraph object is created by the MeshBuilder object and is encoded into the EnvironmentalMesh.

class meshiphi.mesh_generation.neighbour_graph.NeighbourGraph(cellboxes=None, grid_width=0)

A NeighbourGraph is a class that defines the graphical representation of the adjacency relationship between CellBoxes in the Mesh.

neighbour_graph

a dictionary that contains cellboxes ids along with their adjacent neighbours in the following form

{

<CellBox id_1>: {

“1”: [id_1,…,id_n],

“2”: [id_1,…,id_n],

“3”: [id_1,…,id_n],

“4”: [id_1,…,id_n],

“-1”: [id_1,…,id_n],

“-2”: [id_1,…,id_n],

“-3”: [id_1,…,id_n],

“-4”: [id_1,…,id_n],

},

…,

{

<CellBox id_n>: {

…

}

}

}

Type:: dict

get_neighbour_case(cellbox_a, cellbox_b)

Given two cellboxes (cellbox_a, cellbox_b) returns a case number representing where the two cellboxes are touching.

Parameters:

cellbox_a (CellBox) – starting CellBox
cellbox_b (CellBox) – destination CellBox

Returns:

an int representing the direction of the adjacency between input cellbox_a and cellbox_b. The meaning of each case is as follows -

case 0 -> CellBoxes are not neighbours

case 1 -> cellbox_b is the North-East corner of cellbox_a

case 2 -> cellbox_b is East of cellbox_a

case 3 -> cellbox_b is the South-East corner of cellbox_a

case 4 -> cellbox_b is South of cellbox_a

case -1 -> cellbox_b is the South-West corner of cellbox_a

case -2 -> cellbox_b is West of cellbox_a

case -3 -> cellbox_b is the North-West corner of cellbox_a

case -4 -> cellbox_b is North of cellbox_a

Return type:

int

initialise_neighbour_graph(cellboxes, grid_width): initialize the neighbour graph

update_neighbours(cellbox_indx, new_neighbours_indx, direction, cellboxes)

method that updates the neighbour of a certain cellbox in a specific direction. It removes cellbox_indx from the neighbour_map of its neighbours in a specific direction and add new_neighbour_indx

Parameters:

cellbox_index (int) – index of the cellbox that its neighbour will be updated
new_neighbour_indx (int) – the index of the new neighbour that will replace cellbox_index
direction (int) – an int that represents the direction of the neighbours that will get updated (e.g. north, south ,..)
cellboxes (list<CellBox>) – the list that contains all the cellboxes of the mesh

8.4.1.4. CellBox

The CellBox object is used to store the data contained within a geospatial boundary in the MeshBuilder. The CellBox object is created by the MeshBuilder object and transformed into an AggregatedCellBox object when the MeshBuilder returns the EnvironmentalMesh object.

Outlined in this section we will discuss the usage of the CellBox functionality of the meshiphi package. In this series of class distributions we house our discrete representation of input data. In each CellBox, we represent a way of accessing the information governing our numerical world, this includes and is not limited to: Ocean Currents, Sea Ice Concentration and Bathymetric depth.

Example:

An example of running this code can be executed by running the following in a ipython/Jupyter Notebook:
from meshiphi.mesh_generation.cellbox import cellbox

....
Note:

CellBoxes are intended to be constructed by and used within a Mesh object.
The methods provided are to extract information for CellBoxes contained within a Mesh.

class meshiphi.mesh_generation.cellbox.CellBox(bounds, id)

A CellBox represnts a geo-spatial/temporal boundary that enables projecting to information within. Information about any given value of a CellBox is calculated from aggregating all data points of within those bounds. CellBoxes may be split into smaller CellBoxes and the data points within distributed between the newly created CellBoxes so as to construct a non-uniform mesh of CellBoxes, such as within a Mesh.

Bounds

object that contains the latitude and logtitute range and the time range

Type:: Boundary

id

the id of the cellbox

Type:: int

__init__(bounds, id)

Parameters:

bounds (Boundary) – encapsulates latitude, longtitude and time range of the CellBox
id (int) – the id of the cellbox

aggregate()

aggregates CellBox data using the associated data_sources’ aggregate type (ex. MEAN, MAX) and returns AggregatedCellBox object

Returns:: object contains the aggregated data within cellbox bounds.
Return type:: AggregatedCellbox

set_data_source(data_source)

a method that sets the data source of the cellbox ( which includes the data loaders,: splitting conditions and aggregation type)

Parameters:: data_source (List <MetaData>) – a list of MetaData objects, each object represents a source of this CellBox data (where the data comes from, how it is spitted and aggregated)

set_parent(parent): set the parent CellBox, which is the bigger CellBox that conains this CellBox :param CellBox: the bigger Cellbox object that got splitted to produce this cellbox

should_split(stop_index)

determines if a cellbox should be split based on the homogeneity condition of each data type contained within. The homogeneity condition of values within this cellbox is calculated using the method ‘get_hom_cond’ in each DataLoader object inside CellBox’s metadata

if ANY data returns ‘HOM’:: do not split
if ANY data returns ‘MIN’:: do not split
if ALL data returns ‘CLR’:: do not split
else (mixture of CLR & HET):: split

Parameters:

stop_index – the index of the data source at which checking the splitting conditions stops.
splitting. (Implemented like this to perform depth-first) –
splitting (Should be deprecated once we switch to breadth-first) –

Returns:

True if the splitting_conditions of this CellBox: will result in the CellBox being split.

Return type:

bool

split(start_id)

splits the current cellbox into 4 corners, returns as a list of cellbox objects.

Parameters:: start_id – represenst the start of the splitted cellboxes ids, usuallly it is the number of the existing cellboxes
Returns:: The 4 corner cellboxes generated by splitting the cellbox uniformly.
Return type:: list<CellBox>

8.4.1.5. MetaData

The Metadata object is used to store the metadata associated with a CellBox object within the MeshBuilder. This includes associated DataLoaders, the depth of the CellBox within the MeshBuilder, and the parent CellBox of the CellBox among others.

class meshiphi.mesh_generation.metadata.Metadata(data_loader, splitting_conditions=None, value_fill_type='', data_subset=None)

A Metadata is a class that defines the datasource for a certain Cellbox and the assocated splitting conditions.

data_loader: object of the DataLoader class that enable projecting to the cellbox data

splitting_conditions: list of conditions that determine how to split the data accessed by data_loader

value_fill_type

indicates how to fill a CellBox if it has void data (ex. use the data in the parent cellbox or assign 0 to the data)

Type:: string

__init__(data_loader, splitting_conditions=None, value_fill_type='', data_subset=None)

Parameters:

data_loader (DataLoader) – object of the DataLoader class that enables projecting to the cellbox data
splitting_conditions (List<dict>) – list of conditions that determine how to split CellBox
value_fill_tyep (string) – represents the way the data of a cellbox will be filled in case it has void data (ex. parent , 0 )

8.4.1.6. AggregatedCellBox

An aggregated representation of the data contained within a geospatial boundary. The AggregatedCellBox object is created by the CellBox object when the MeshBuilder returns the EnvironmentalMesh.

class meshiphi.mesh_generation.aggregated_cellbox.AggregatedCellBox(boundary, agg_data, id)

a class represnts an aggrgated information within a geo-spatial/temporal boundary.

Attributes:

Note

All geospatial boundaries of a CellBox are given in a ‘EPSG:4326’ projection

__init__(boundary, agg_data, id)

Parameters:

boundary (Boundary) – encapsulates latitude, longtitude and time range of the CellBox
agg_data (dict) – a dictionary that contains data_names and agg values
id (string) – a string represents cellbox id

contains_point(lat, long)

Returns true if a given lat/long coordinate is contained within this cellbox.

Parameters:

lat (float) – latitude of a given point
long (float) – longitude of a given point

Returns:

True if this CellBox contains a point given by: parameters (lat, long)

Return type:

contains_points (bool)

to_json()

convert cellbox to JSON

The returned object is of the form -

{

“geometry” (String): POLYGON(…),

“cx” (float): …,

“cy” (float): …,

“dcx” (float): …,

“dcy” (float): …,

“agg_value_1” (float): …,

…,

“agg_value_n” (float): …

}

Returns:: A JSON parsable dictionary representation of this AggregatedCellBox
Return type:: cell_json (dict)