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.

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.

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

Constructs a Mesh from a given config file.

Parameters:

Name	Type	Description	Default
`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.	required

`build_environmental_mesh()` ¶

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

Returns:

Name	Type	Description
`EnvironmentMesh`		an object that represents the constructed nonunifrom mesh and contains the aggregated cellboxs and neighbour graph

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

Name	Type	Description	Default
`cellbox`	`CellBox`	the CellBox within this Mesh to be split into 4 smaller CellBox objects.	required

`split_to_depth(split_depth)` ¶

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

Parameters:

Name	Type	Description	Default
`split_depth`	`int`	The maximum split depth reached by any CellBox within this Mesh after splitting.	required

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

Name	Type	Description	Default
`Dataloader`	`ScalarDataLoader or VectorDataLoader`	Dataloader object to add to metadata	required
`params`	`dict`	Parameters to initialise dataloader with	required
`bounds`	`Boundary`		`None`
`name`	`str`	Name of the dataloader used in config	`'myDataLoader'`

Returns:

Name	Type	Description
`MeshBuilder`		Original MeshBuilder object (self) with added metadata for new dataloader

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.

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

Attributes:

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

Parameters:

Name	Type	Description	Default
`bounds`	`Boundary`	the boundaries of this mesh	required
`agg_cellboxes`	`AggregatedCellBox[]`	a list of aggregated cellboxes	required
`neighbour_graph`	`NeighbourGraph`	an object contains each cellbox neighbours information	required
`config`	`dict`	conatins the initial config used to build this mesh.	required

`load_from_json(mesh_json)` `classmethod` ¶

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

Parameters:

Name Type Description Default

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": [

    {


    },

    ...,

    {...}

]

}

required

Returns:

Name	Type	Description
`EnvironmentMesh`		object that contains all the json file mesh information.

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

Name	Type	Description	Default
`index`	`int`	the index of the cellbox to be updated	required
`values`	`dict`	a dict contains perf. metrics names and values	required

`to_json()` ¶

Returns this Mesh converted to a JSON object.

Returns:

Name Type Description

json

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,

"meshiphi_version": the version of MeshiPhi.

}

`to_geojson(params_file=None)` ¶

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

Returns:

Name	Type	Description
`geojson`		The cellboxes of this mesh in a geoJSON format

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_tif(params_file, path)` ¶

generates a representation of the mesh in geotif image format.

Parameters:

Name Type Description Default

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

required

path

string

the path to save the generated tif image.

required

`save(path, format='JSON', format_params=None)` ¶

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

Parameters:

Name	Type	Description	Default
`path`	`String`	The file location the mesh will be saved to.	required
`format`	`String) (optional`	The format the mesh will be saved in. If not format is given, default is JSON. Supported formats are `- JSON - GEOJSON`	`'JSON'`

`merge_mesh(mesh2)` ¶

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

Parameters:

Name	Type	Description	Default
`mesh2`	`EnvironmentMesh`	the mesh to be merged with this mesh	required

`split_and_replace(cellbox_id)` ¶

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

Parameters:

Name	Type	Description	Default
`cellbox_id`	`string`	the id of the cellbox to be split	required

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.

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

Attributes:

Name Type Description

neighbour_graph

dict

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

            ...

        }

    }

}

`initialise_neighbour_graph(cellboxes, grid_width)` ¶

initialize the neighbour graph

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

Name	Type	Description	Default
`cellbox_a`	`CellBox`	starting CellBox	required
`cellbox_b`	`CellBox`	destination CellBox	required

Returns:

Name Type Description

int

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

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

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

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.

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.

Attributes:

Name	Type	Description
`Bounds`	`Boundary`	object that contains the latitude and logtitute range and the time range
`id`	`int`	the id of the cellbox

Parameters:

Name	Type	Description	Default
`bounds`	`Boundary`	encapsulates latitude, longtitude and time range of the CellBox	required
`id`	`int`	the id of the cellbox	required

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

Name	Type	Description	Default
`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)	required

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

Name	Type	Description	Default
`stop_index`		the index of the data source at which checking the splitting conditions stops.	required

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

`split(start_id)` ¶

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

Parameters:

Name	Type	Description	Default
`start_id`		represenst the start of the splitted cellboxes ids, usuallly it is the number of the existing cellboxes	required

Returns: list: The 4 corner cellboxes generated by splitting the cellbox uniformly.

`set_parent(parent)` ¶

set the parent CellBox, which is the bigger CellBox that conains this CellBox Args: CellBox: the bigger Cellbox object that got splitted to produce this cellbox

`aggregate()` ¶

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

Returns:

Name	Type	Description
`AggregatedCellbox`		object contains the aggregated data within cellbox bounds.

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.

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

Attributes:

Name	Type	Description
`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`	`string`	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)

Parameters:

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

`get_data_loader()` ¶

returns the data loader

`get_data_subset()` ¶

gets the data subset

`get_splitting_conditions()` ¶

returns a list of the splitting conditions

`get_value_fill_type()` ¶

returns thevalue fill type

`set_data_loader(data_loader)` ¶

sets the data loader

`set_data_subset(data_subset)` ¶

sets the data subset

`set_splitting_conditions(splitting_conditions)` ¶

sets the splitting conditions

`set_value_fill_type(value_fill_type)` ¶

sets the value fill type

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.

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

Parameters:

Name	Type	Description	Default
`boundary`	`Boundary`	encapsulates latitude, longtitude and time range of the CellBox	required
`agg_data`	`dict`	a dictionary that contains data_names and agg values	required
`id`	`string`	a string represents cellbox id	required

`contains_point(lat, long)` ¶

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

Parameters:

Name	Type	Description	Default
`lat`	`float`	latitude of a given point	required
`long`	`float`	longitude of a given point	required

Returns:

Name	Type	Description
`contains_points`	`bool`	True if this CellBox contains a point given by parameters (lat, long)

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

Name	Type	Description
`cell_json`	`dict`	A JSON parsable dictionary representation of this AggregatedCellBox

Mesh Construction - Classes¶

MeshBuilder¶

build_environmental_mesh() ¶

split_and_replace(cellbox) ¶

split_to_depth(split_depth) ¶

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

EnvironmentMesh¶

load_from_json(mesh_json) classmethod ¶

update_cellbox(index, values) ¶

to_json() ¶

to_geojson(params_file=None) ¶

to_tif(params_file, path) ¶

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

merge_mesh(mesh2) ¶

split_and_replace(cellbox_id) ¶

NeighbourGraph¶

initialise_neighbour_graph(cellboxes, grid_width) ¶

get_neighbour_case(cellbox_a, cellbox_b) ¶

update_neighbours(cellbox_indx, new_neighbours_indx, direction, cellboxes) ¶

CellBox¶

set_data_source(data_source) ¶

should_split(stop_index) ¶

split(start_id) ¶

set_parent(parent) ¶

aggregate() ¶

MetaData¶

get_data_loader() ¶

get_data_subset() ¶

get_splitting_conditions() ¶

get_value_fill_type() ¶

set_data_loader(data_loader) ¶

set_data_subset(data_subset) ¶

set_splitting_conditions(splitting_conditions) ¶

set_value_fill_type(value_fill_type) ¶

AggregatedCellBox¶

contains_point(lat, long) ¶

to_json() ¶

`build_environmental_mesh()` ¶

`split_and_replace(cellbox)` ¶

`split_to_depth(split_depth)` ¶

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

`load_from_json(mesh_json)` `classmethod` ¶

`update_cellbox(index, values)` ¶

`to_json()` ¶

`to_geojson(params_file=None)` ¶

`to_tif(params_file, path)` ¶

`save(path, format='JSON', format_params=None)` ¶

`merge_mesh(mesh2)` ¶

`split_and_replace(cellbox_id)` ¶

`initialise_neighbour_graph(cellboxes, grid_width)` ¶

`get_neighbour_case(cellbox_a, cellbox_b)` ¶

`update_neighbours(cellbox_indx, new_neighbours_indx, direction, cellboxes)` ¶

`set_data_source(data_source)` ¶

`should_split(stop_index)` ¶

`split(start_id)` ¶

`set_parent(parent)` ¶

`aggregate()` ¶

`get_data_loader()` ¶

`get_data_subset()` ¶

`get_splitting_conditions()` ¶

`get_value_fill_type()` ¶

`set_data_loader(data_loader)` ¶

`set_data_subset(data_subset)` ¶

`set_splitting_conditions(splitting_conditions)` ¶

`set_value_fill_type(value_fill_type)` ¶

`contains_point(lat, long)` ¶

`to_json()` ¶