seaplan

Seagoing mission planning based on station positions and occupation times

Overview

Reads in a parameter file (YAML format) containing variables and a list of actions to perform.

The parameter file can also specify a "station file" containing the names, latitudes and longitudes of the stations. All of these stations will be plotted on the map and if an action has the same name and no specified latitude and longitude, this station's position will be used.

Outputs a table of actions with predicted (or specified) times. The table is in MultiMarkdown format, it can be printed as is or converted to HTML, LaTeX etc for pretty printing.

Parameter file

The parameter file is divided into format_version, parameters (can also be called variables in v0.x) and events sections:

format_version

Just a string that you should set equal your version of seaplan. Used to check compatibility with newer/older versions

parameters

Run parameters:

Required

• description: Descriptive information to be printed in the HTML output file

  • title: title text
  • notes: an array of notes

• timing:

  • ship_speed.kn_i: Cruising speed of the ship in knots. Used to calculate transit times
  • ship_latency.h: Hours lost getting to speed from stopped. Added to distance/ship_speed to calculate transit times
  • ignore_depart_arrive_times: Ignore 'arrive_time' and 'depart_time' in events (allows you to test time predictions) [False]
  • action_times.h: Default hours for each action type, may further be specifed to an action at a given station. Structure is: action_times.h: "{action1}": "{station_or_type1}": *float* "{station_or_type2}": *float* default: *float* "{action_type2}": default: *float*

• printout: Controls what is printed in the output table:

  • show_comments : Print comments
  • show_waypoints : Print waypoints (events with hours=0)
  • print_past : Print past events

Optional

• station_file: The name of a CSV file containing station information.

  • name: Name of CSV file
  • field_separator: single character

• map:

  • bounds: plot bounds in Decimal degrees (MANDATORY unless you call `seaplan --no_map``)

  • grid: grid spacing in decimal degrees

  • coast_resolution:

    • '10m': 1/10,000,000 Natural Earth
    • '50m': 1/50,000,000 Natural Earth
    • '110m': 1/110,000,000 Natural Earth
    • 'auto': Automatic Global Self-consistent, Hierarchical, High-resolution Geography (GSHHG) coastline resolution
    • 'crude': GSHHG
    • 'low': GSHHG
    • 'intermediate': GSHHG
    • 'high': GSHHG
    • 'full': GSHHG

  • bathy_map: Map background image [False]. Three possibilities:

    • {string}: Name of a netCDF file to plot as background image on the map
    • True: Plot an etopo image as background
    • False: No background map

  • plot_past_tracks: Plot past ship tracks

  • show_plot: Plot the the screen as well as a file

events

A sequential list of "events". Each event can have the following parameters

• station (str): station name [MANDATORY]. If the name corresponds to a "Name" in the station file, then the station position, type and comments are read from there. If not, you must specify at least lat and lon the first time you name the station
• lat (float): station latitude [station.lat or 0.]
• lon (float): station longitude [station.lon or 0.]
• arrive_time (ISO): [previous depart_time + transit + latency]
• depart_time (ISO): [arrive_time + hours]
• hours (float): time spent on the operation. If zero, the event is considered to be a waypoint. Defaults are (from highest to lowest priority):
  • action_time.h['{action}']['{station}'],
  • action_time.h['{action}']['default'],
  • 0.
• comment (str): comment
• speed (float): speed between previous and given site [ship_speed.kn_i]

Station file

A CSV file whos first line is a header that specifies the field order, using the following names: - Name: station name - Lat: station latitude - Lon: station latitude - Type: used to define default times - Comment: station comment

Miscellaneous features

• Puts name of stations/actions on plot UNLESS they have no "hours" (just a waypoint)

• Crosses out stations that have already been visited (departure_time entered and before UTCDateTime.now()

• Changes the color of the ship's track every time you use the action name "NEWLEG"

Other subdirectories

seaplan/_examples/

Example files and scripts:

Use reStructuredText <http://docutils.sourceforge.net/rst.html>_ to modify this file.