Route Calculation¶

Route Calculation Overview¶

This section describes the code used for the evaluation of user-defined routes through a mesh constructed by the methods described in previous sections. This mesh should include all the relevant vessel performance parameters needed to calculate the fuel and time cost of the route.

Route Calculation¶

`case_from_angle(start, end)` ¶

Determine the direction of travel between two points and return the associated case

Parameters:

Name	Type	Description	Default
`start`	`ndarray`	the coordinates of the start point within the cell	required
`end`	`ndarray`	the coordinates of the end point within the cell	required

Returns:

Name	Type	Description
`case`	`int`	the case to use to select variable values from a list

`find_intersections(df, mesh)` ¶

Find crossing points of the route and the cells in the mesh Args: df (DataFrame): Route info in dataframe format mesh (GeoDataFrame): Mesh in GeoDataFrame format

Returns:

Name	Type	Description
`track_points`	`dict`	Dictionary of crossing points and cell ids

`load_mesh(mesh_file)` ¶

Load mesh from file into GeoDataFrame Args: mesh_file (str): Path to mesh with vehicle information

Returns:

Name	Type	Description
`mesh`	`GeoDataFrame`	Mesh in GeoDataFrame format

`load_route(route_file)` ¶

Load route information from file

Parameters:

Name	Type	Description	Default
`route_file`	`str`	Path to user defined route in json, csv or gpx format	required

Returns:

Name	Type	Description
`df`	`Dataframe`	Dataframe with route info
`from_wp`	`str`	Name of start waypoint
`to_wp`	`str`	Name of end waypoint
`route_type`	`str`	Type of route, either 'smoothed' or 'dijkstra'

`order_track(df, track_points)` ¶

Order crossing points into a track along the route Args: df (DataFrame): Route info in dataframe format track_points (dict): Dictionary of crossing points and cell ids

Returns:

Name	Type	Description
`user_track`	`DataFrame`	DataFrame of ordered crossing points and cell ids

`route_calc(df, from_wp=None, to_wp=None, mesh=None, route_type=None)` ¶

Function to calculate the fuel/time cost of a user defined route in a given mesh

Parameters:

Name	Type	Description	Default
`df`	`DataFrame or dict`	Route info in dataframe format, or a route geojson (either a FeatureCollection with a "features" key, or a full pipeline output containing a "paths" key with a nested FeatureCollection). When a geojson is supplied, `from_wp`, `to_wp` and `route_type` are read from its properties and any values passed for those arguments are ignored.	required
`from_wp`	`str`	Name of start waypoint (ignored when `df` is a geojson)	`None`
`to_wp`	`str`	Name of end waypoint (ignored when `df` is a geojson)	`None`
`mesh`	`json`	A Mesh with encoded vehicle information	`None`
`route_type`	`str`	Type of route being calculated, either 'dijkstra' or 'smoothed' (ignored when `df` is a geojson)	`None`

Returns:

Name	Type	Description
`user_path`	`dict`	User defined route in geojson format with calculated cost information

Raises:

Type	Description
`ValueError`	If route_type is not 'dijkstra' or 'smoothed'

`route_geojson_to_df(route_json)` ¶

Convert a route geojson into the DataFrame format used internally by route_calc.

Parameters:

Name	Type	Description	Default
`route_json`	`dict`	Route in geojson format, either a FeatureCollection with a "features" key, or a full pipeline output containing a "paths" key with a nested FeatureCollection.	required

Returns:

Name	Type	Description
`df`	`DataFrame`	Dataframe with route info (Long, Lat columns)
`from_wp`	`str`	Name of start waypoint
`to_wp`	`str`	Name of end waypoint
`route_type`	`str`	Type of route, either 'smoothed' or 'dijkstra'

`traveltime_distance(cellbox, wp, cp, speed='speed', vector_x='uC', vector_y='vC', case=0, dijkstra=False)` ¶

Calculate travel time and distance for two points.

Parameters:

Name	Type	Description	Default
`cellbox`	`dict`	the cell containing the line segment	required
`wp`	`ndarray`	the start point	required
`cp`	`ndarray`	the end point	required
`speed`	`str`	the key for speed	`'speed'`
`vector_x`	`str`	the key for the x vector component	`'uC'`
`vector_y`	`str`	the key for the y vector component	`'vC'`
`case`	`int`	case giving the index of the speed array	`0`

Returns:

Name	Type	Description
`traveltime`	`float`	the time to travel the line segment
`distance`	`float`	the distance along the line segment

Route Calculation¶