Ocean Voyage Appraisal using Searoute and Folium
Co-authored by Aurora Thomas.
Ocean passage appraisal is conducted by vessel and shoreside operations personnel to determine the viability of an ocean passage. One element of appraisal is finding an oceangoing route from an origin port to a destination port. In the past, distance tables were used to assist in the appraisal stage. The employment of Searoute combined with Folium is proposed as an alternative.
Introduction
Typically during the ocean planning appraisal stage (Whiterbys, 2018), the suitability of a voyage is determined. Parameters such as voyage distance, time, and route are evaluated. The National Geospatial Agency’s publication Distances Between Ports is used today by maritime professionals to extract tabulated distances between origin and destination ports worldwide during the appraisal process.
Searoute (Halili, 2022) is a Python package based on Eurostat Searoute (Gaffuri, 2021), which is deployed by the statistical office of the European Union. A gridded network is combined with Dijkstra’s algorithm to determine economical routes. The outcomes may present similar values to the published tabulated values within the National Geospatial Agency’s Publication 151 with the added benefit of route visualization using Folium (Story, n.d.).
Method
Step 1: Package Import
import searoute as sr
import foliumStep 2: Define Origin and Destination Coordinates
For this example, an ocean passage from Rotterdam to Houston is used. The latitude and longitude is obtained from Google Maps by right clicking on the map and selecting the topmost coordinate. The origin and destination coordinates are then applied as entering parameters to Searoute.
origin = [52.04, 3.91]
destination = [29.21, -94.64]Step 3: Change (latitude, longitude) to (longitude, latitude).
Typically latitude precedes longitude when expressing coordinates (Bowditch, 2019; GISGeography, 2023) however Searoute inexplicably swaps the values. Therefore, the coordinate elements must be swapped.
origin[0], origin[1] = origin[1], origin[0]
destination[0], destination[1] = destination[1], destination[0]Step 4: Instantiate the Route Object
For this example, we use a speed that is typical for an oil tanker: 12.5 knots (Agarwal, 2019). The unit distance is nautical miles which is a widely used unit of measurement within marine navigation (Chapman, 2021).
route = sr.searoute(origin, destination, speed_knot=12.5, units="naut")Step 5: Obtain the Route from the Object
coordinates = route['geometry']['coordinates']Step 6: Change (longitude, latitude) to (latitude, longitude)
The coordinates are then changed back to accommodate Folium.
coordinates = [[coord[1], coord[0]] for coord in coordinates]Step 7: Create a Map Object
m = folium.Map(location=coordinates[0], zoom_start=6)Step 8: Add a Marker for each Coordinate
A marker is created for each coordinate. A black circle is used to conform with modern voyage appraisal iconography.
for coord in coordinates:
folium.CircleMarker(location=coord, radius=1, fill_color='black', color='black').add_to(m)Step 9: Create a Line between the Coordinates
A line is created between points and is reflective of a trackline within marine navigation.
folium.PolyLine(locations=coordinates, color='black', weight=1).add_to(m)Step 10: Save the Map
The map is then saved as an html file within the localized directory. The file can be viewed by opening with a browser within an integrated development environment.
m.save('map.html')The final map will appear as so:
Step 11: Obtain the Distance and Time Required for Passage
The distance and time can be obtained from the resultant dictionary created by the route object.
properties=route["properties"]In the above example the voyage distance is 4,961 nautical miles with a total transit time of 16 days 13 hours.
Final Code Example
import searoute as sr
import folium
# Define origin and destination points
origin = [52.04, 3.91]
destination = [29.21, -94.64]
# Change (latitude, longitude) to (longitude, latitude)
origin[0], origin[1] = origin[1], origin[0]
destination[0], destination[1] = destination[1], destination[0]
# Instantiate the route object
route = sr.searoute(origin, destination, speed_knot=12.5, units="naut")
# Obtain the route from the object
coordinates = route['geometry']['coordinates']
# Change (longitude, latitude) to (latitude, longitude)
coordinates = [[coord[1], coord[0]] for coord in coordinates]
# Create a map object
m = folium.Map(location=coordinates[0], zoom_start=6)
# Add a marker for each coordinate
for coord in coordinates:
folium.CircleMarker(location=coord, radius=1, fill_color='black', color='black').add_to(m)
# Create a line between coordinates
folium.PolyLine(locations=coordinates, color='black', weight=1).add_to(m)
# Save the map object as an HTML file
m.save('map.html')
# Obtain the distance and time required for passage
properties=route["properties"]Conclusion
As stated by Halili in the package’s github page Searoute is not intended for actual routing. What is suggested here is use of Searoute for the appraisal stage of the voyage planning process. Once the preferred route is agreed upon, then the planning, execution, and monitoring stage can be conducted by a licensed marine navigator using, in part, government-sourced reference materials and electronic chart and information display systems (ECDIS).
References
Story, R. (n.d.). Folium. Retrieved August 15, 2023, from https://pypi.org/project/folium/
Eurostat. (n.d.). European Commission. Retrieved August 15, 2023, from https://ec.europa.eu/eurostat
Gaffuri, J. (2021). Eurostat/Searoute: Compute shortest maritime routes between ports. GitHub. Retrieved August 20, 2023, from https://github.com/eurostat/searoute
Distance Between Ports. (2023). National Geospacial Agency. Retrieved August 15, 2023, from https://msi.nga.mil/Publications/DBP
Halili, G. (2022). Searoute. Retrieved August 15, 2023, from https://pypi.org/project/searoute/
Salmon, D. R. (2014). Passage Planning Guidelines. Witherby Seamanship International.
