Mission planning

Suggested workflows for the mission planning tools

This page is meant to provide some examples of how the mission planning piloting functions maybe be used ahead of a planned mission. The below sections include examples for creating a targets file, creating a planned mission map, plotting a bathymetry profile for the planned track, and summarizing total mission distance and duration.

All code on this page is compiled in the workflow_missionTrackPlanning.m in the agate\example_workflows folder.

Details for each function used below (inputs, outputs, etc) are available within the standard MATLAB-type documentation in the header of each function and include a detailed description, info on input and output arguments, and examples. These details can be pulled up by typing doc function or help function within the MATLAB Command Window.

Initialization

To run any of the agate functions, the toolbox must be initialized with a configuration file.

No configuration file yet? Go to the Configuration Guide. The examples on this page include some plotting, so the OPTIONAL - plotting section must be complete.

% make sure agate is on the path!

% initialize with specified configuration file, 'agate_config.cnf'
CONFIG = agate('agate_config.cnf');

% OR

% initialize with prompt to select configuration file
CONFIG = agate;

_{Back to top}

Create planned track using Google Earth Pro

Use Google Earth Pro (the desktop app) to plan a mission trackline and save it as a .kml.

• Create a path object by navigating to the Add menu and selecting Path
• A popup will appear where you can name the path
• While the popup is still the top window, the cursor will become a square; can click anywhere on the map to make a waypoint
• Continue to click to make the desired waypoints
• Waypoints can be moved by clicking and dragging
• Right-clicking on a given waypoint will delete it
• View the total track length under the Measurements tab
• Once you are happy with the track, hit Ok in the popup

The path must be saved as a .kml containing just a single path/track. To properly save:

• Within Google Earth, right-click on the path name in the panel on the left hand side
• Select Save place as
• Change the file type from .kmz to .kml and hit Save

An example is located in agate\example_workflows\exampleTrack.kml

Figure 1: Example path in Google Earth saved as a .kml and ready to be converted to a targets file.

Create targets file from .kml

The makeTargetsFile function will read in an existing .kml (that contains a single path) and use it to create a properly formatted Seaglider targets file. The generated targets file will be named targets_ plus the name of the .kml file (e.g., targets_exampleTrack). It will contain header information with the glider and mission information defined in CONFIG, the date it was created, and the specified radius.

/ Targets file for mission sgXXX_Location_Mon20XX
/ Created on YYYY-mm-dd HH:MM UTC
/ Deployment will take place at WP01, recovery at RECV
/ template WPxx lat=DDMM.MMMM lon=DDDMM.MMMM radius=XXXX goto=WPzz

Waypoint names can be generated one of three ways:

1. alphanumeric: specify a character string (alpha) prefix in the function call and alphanumeric names will be created automatically.

2. file: list the desired waypoint names within a simple .txt file, with one name per line and the number of waypoint names must equal the number of waypoints in the .kml; the function will prompt to select the file. An example can be found in agate\example_workflows\waypointNames.txt

3. manual: waypoint names are manually entered in the Command window within the function call

% specify file name to .kml path
kmlFile = fullfile(CONFIG.path.mission, 'exampleTrack.kml');
% OR
% leave empty and will prompt to select .kml path
kmlFile = []; 

% specify radius
radius = 2000;

% create targets file, 3 options to name waypoints
% (1) alphanumeric/prefix-based automated naming
alphaNum = 'WP'; % Any two letters make easy to reference and read options
targetsOut = makeTargetsFile(CONFIG, kmlFile, alphaNum, radius);
% OR
% (2) use a text file with list of waypoint names; will prompt to select .txt
targetsOut = makeTargetsFile(CONFIG, kmlFile, 'file', radius);
% OR
% (3) manually enter in command window when prompted
targetsOut = makeTargetsFile(CONFIG, kmlFile, 'manual', radius);

_{Back to top}

Plot planned track

The mapPlannedTrack function will create a simple map of the planned track with labeled waypoints. This function requires map extent (lat/lon limits) to be defined in the configuration file. Optionally, a north arrow and scale bar location can be defined in the configuration file. For more help setting those parameters, see the Map Help page. Bathymetry is optional and is toggled on or off with the bathyOn argument. This is useful for plotting a single track. If you want to plot multiple tracks in a single figure, use createBaseMap and add the tracks manually. See more on this on the Map Help page.

% set up map configuration
bathyOn = 1; % plot bathymetry
col_track = 'red'; % set color for trackline

% use targetsOut file from above as input targets file
targetsFile = targetsOut;

% create plot
mapPlannedTrack(CONFIG, targetsFile, CONFIG.glider, bathyOn, col_track)
% the third argument sets the name of the track for the legend

% the title will default to CONFIG.glider and CONFIG.mission. To change:
title('Example Planned Track');

% get file name only for plot saving
[~, targetsName, ~] = fileparts(targetsFile);

% save as .png
exportgraphics(gcf, fullfile(CONFIG.path.mission, [CONFIG.glider '_' ...
    CONFIG.mission, '_plannedTrack_' targetsName, '.png']), ...
    'Resolution', 300)
% as .fig
savefig(fullfile(CONFIG.path.mission, [CONFIG.glider '_' CONFIG.mission, ...
    '_plannedTrack_' targetsName, '.fig']))

% save as .pdf or .eps - requires the export_fig toolbox available at
%  https://github.com/altmany/export_fig
export_fig(fullfile(CONFIG.path.mission, [CONFIG.glider '_' CONFIG.mission, ...
    '_plannedTrack_' targetsName, '.eps']), '-eps', '-painters');
export_fig(fullfile(CONFIG.path.mission, [CONFIG.glider '_' CONFIG.mission, ...
    '_plannedTrack_' targetsName, '.pdf']), '-pdf', '-painters');

Figure 2: Planned track map with each waypoint labeled.

_{Back to top}

Plot bathymetry profile

It can be useful to have a profile of the bathymetry the planned track will traverse, to highlight periods where the glider’s target dive depth may need to be adjusted more shallow, or can be extended deeper.

See Dependecies - Basemap rasters for more info on how to select and download bathymetry rasters.

An indicator line (dashed red line) will be plotted at 990 m as the default (max $D_TGT for Seagliders) but can be specified to a different value with the yLine argument.

NOTE: This function sets the arguments using name-value pairs because most of them are optional. So each is defined by the name of the argument in single quotes (e.g., 'bathyFile') followed by a comma and then the value for the argument (e.g., 'C:\bathyFile.tiff'). Use doc plotTrackBathyProfile to see all possible arguments.

% can specify bathymetry file
bathyFile = 'C:\GIS\etopo\ETOPO2022_bedrock_30arcsec_MHI.tiff';
plotTrackBathyProfile(CONFIG, 'targetsFile', targetsFile, 'bathyFile', bathyFile)
% OR 
% leave empty to prompt to select files
plotTrackBathyProfile(CONFIG)

% save as .png
exportgraphics(gcf, fullfile(CONFIG.path.mission, [CONFIG.glider '_' ...
    CONFIG.mission, '_targetsBathymetryProfile_' targetsName, '.png']), ...
    'Resolution', 300)

Figure 3: Bathymetry profile for set targets file which shows the seafloor depth at each target and in the straight line between each target. The 990 m depth limit is marked with a dashed line.

Summarize planned track

The below code reads in an existing (or newly created!) targets file and will loop through to calculate the distance between each waypoint and then print out the total planned track distance. If an estimate of glider speed (in km/day) is available, that can be used to estimate mission duration.

% if no targetsFile specified, will prompt to select
[targets, targetsFile] = readTargetsFile(CONFIG);
% OR specify targetsFile variable from above
[targets, targetsFile] = readTargetsFile(CONFIG, targetsFile);

% loop through all targets (expect RECV), calc distance between waypoints
for f = 1:height(targets) - 1
    [targets.distToNext_km(f), ~] = lldistkm([targets.lat(f+1) targets.lon(f+1)], ...
        [targets.lat(f) targets.lon(f)]);
end

% specify expected avg glider speed in km/day
avgSpd = 15; % km/day

% print out summary
[targetsPath, targetsName, ~] = fileparts(targetsFile);
fprintf(1, 'Total tracklength for %s: %.0f km\n', targetsName, ...
    sum(targets.distToNext_km));
fprintf(1, 'Estimated mission duration, at %i km/day: %.1f days\n', avgSpd, ...
    sum(targets.distToNext_km)/avgSpd);

The output will look something like this:

Total tracklength for targets_exampleTrack: 54 km
Estimated mission duration, at 15 km/day: 3.6 days

_{Back to top}