BLUEWATER RACING is a set of tools for tactical and strategic planning of long-distance boat racing and voyaging. I originally wrote Bluewater when I was a navigator for the 2007 TransPac race.

What we do:

· Display and edit routes.

· Interface to GPS units.

· Support a selection of chart formats, including: a built-in highly-detailed global planning chart; BSB format charts (freely available from NOAA); arbitrary raster images (JPEG, GIF, etc., assuming the image uses a standard map projection); arbitrary vector charts in a simple text format.

· Display, examine, and manipulate multiple GRIB weather files.

· Display weather images, and track your route across them.

· Examine and manipulate boat performance "polar" files.

· Combine polar performance data with forecast winds to estimate travel time along routes.

· Compute optimal routes, combining boat performance with multiple wind forecast files of varying precision.

· Track competitors.

What we don't do:

· Interface to your boat's instruments for windspeed, boatspeed, wind angle, heel angle, etc. to give real-time tactical planning.

· Provide moving map services.

· Use propriety information from various commercial services.

· Claim to be the greatest racing software available, used by the world’s best professional racers. But we do claim some advantages:

Advantages

Routes, waypoints, and polar data are stored as XML files or text files that you can examine and edit directly with your favorite text editor.

You can view the forecast time it will take to sail any given route you have constructed. Most other programs will only give you one approximate “best route,” and won’t tell you how long it will take to sail a different route of your choosing.

Besides giving you an estimated best route, the Bluewater Racing optimizer gives you additional information, such as a “routing tree”, which tells you the best time to all the points in your travel region, and a “sensitivity analysis,” which gives you an idea of how far afield from the best route you can sail, and still arrive in close to the fastest time. Use it when you are considering issues besides minimal travel time, such as tactics against competitors, safety of navigation, or uncertainty of forecasts.

You can work with multiple Grib files simultaneously, to generate a complete wind picture that combines extremely accurate, short-range, small-scale forecasts at the start of your race, with long range, larger scale forecasts for weeks later at the end of your race. The Grib display options are highly editable.

Boat polar files can include data for motor sailing, allowing travel time estimation for power boats, or yachts that will use power when the winds are light.

BLUEWATER uses high quality, free, publicly available data from academic and government sources, including:

· The Global Self-consistant Hierarchical High-resolution Shorelines database from the University of Hawaii.

· Grib format weather files available for free from multiple sources, such as Saildocs, NOAA, and sailflow.com.

· Magnetic declination data from the World Magnetic Model, developed by the National Geophysical Data Center at NOAA.

The GUI is written in Tcl/Tk, a popular and powerful scripting language. If you have some programming skill and inclination, you can directly manipulate Grib and Route files via simple Tcl scripts, using a command shell connected to BLUEWATER. For example, you can construct a new Grib file that averages the values in several existing files, or construct a Grib data set at lower density and then take a look at it with the program.

Curious about the competition? Check out Expedition, Deckman, or Advantage.

Fundamental Concepts

Input Files

BLUEWATER RACING uses the following input files:

· Route files: Each route file defines a "race": a collection of marks and routes. Route files are stored in GPX format.

· GriB files: These contain weather data in Gridded Binary (GriB) format, and are usually downloaded from Internet weather sites.

· Polar files. These contain performance data for boats. A selection of polar files are provided with the program. They can also be acquired from your yacht vendor, or from USSailing.

· Chart files. These contain chart data in vector or raster form.

· The magnetic declination file, "WMM.COF". Every five years a new one must be downloaded from NOAA. The program will tell you when to do it.

· The configuration file, bluewater.pref. It describes the state of the customizable features of Bluewater Racing.

Routes

A route is a sequence of geographic positions called route points. A route is displayed as little squares, one per route point, connected by great-circle lines. Conceptually, a boat sails along a route, but what exactly a route means is up to you. It can be a course you've already sailed, or a course some competitor is sailing, or a course you plan to sail, or a combination of these things.

Suppose you are a navigator in the middle of a five-day race. You have a paper chart, on which you have marked a sequence of fixes – the route you have sailed so far. Each fix is labeled with the time of arrival. If the race committee is transmitting position reports, you have also marked down the routes that your competitors have sailed.

Looking ahead, you want to plot a fast route to the finish. You mark down some waypoints: positions you think you should sail through because they are likely to have favorable winds or put you into a good strategic position. You also try to guess the routes that your competitors will follow. You don’t know for sure when you will arrive at your waypoints, but you can estimate the arrival times based on wind forecasts and your boat performance. These estimates, along with estimates of your competitors’ progress, may cause you to change your planned route.

BLUEWATER RACING is designed to automate these tasks. Each route point has a latitude, a longitude, and a time. If the route point is marked read-only, then these values cannot be changed. This is intended for fixes that have already occurred, where the time records the actual time of arrival at the route point (ATA). A route with only read-only points is also called a track.

On the other hand, if the route point is not marked read-only, then it is treated as a planning fix. You can move it around with the graphical editor, and the program will estimate the time that you will reach it. In this case, the time is an estimated time of arrival (ETA) at the route point. Making this estimate is called a performance computation. (More on performance computations below.)

Each route has a "Start Time", used in performance computations. The start time can be specified in the GPX file, or from the route options window. (Tools® Route Manager®Options). The start time is either a hard time (e.g., "07/19/2007 13:00Z"), or one of the special values "@now" or "@grib". @now means that the start time for the route is always equal to the current ship's time. @grib means the start time is set to the time of the first forecast period in the primary wind data (Grib) file.

The time of a non-read only route point is the decimal hours it will take to reach that point, given that:

you depart the first route point (point zero) at the "start time", and
you sail exactly along the route at your best speed, and
the winds are specified by the Grib wind data. If no wind data has been loaded, no times are computed, unless they were stored from a previous computation.

When the GPS is connected and enabled, it appends route points to a special route named “GPS_track”. The frequency that track points are added is every 60 seconds by default. The frequency can be modified from “Tools®Preferences.” If GPS_track does not exist, it is created.

Note: BLUEWATER’s behavior is undefined for routes that cross the International Date Line, ±180°. If you wish to cross the date line, you must split the route in two at the date line.

Marks

A mark is a named geographic point with a latitude and longitude. It is displayed as a little blue circle and pennant. Typically, a mark represents a temporary or permanent buoy, or some other fixed point important for navigation. You can create marks in two ways: by using any text or XML editor to create a GPX file, and then loading it into the program; or selecting "Edit" mode in the program and right-clicking on the chart where you want the mark to be located. You can move an existing mark by selecting Edit mode and then either left-clicking-and-dragging it, or right-clicking on it to bring up a position-editing window.

There are two special marks: "GPS_Pos" and "Finish". GPS_Pos is maintained by the program whenever GPS downloading is enabled (Tools®Enable GPS). When a GPS is connected, the program will read the GPS data and constantly move GPS_Pos so that it always marks the current location.

If you create a mark named "Finish", it can be used by a quick shortcut routing function, "Route To Finish", available from the Route Manager.

The "Current Race" file

Open a race file from the "File®Open" menu item. This will load all the routes and marks from the file. File®Save writes the active set of routes and marks to the last opened race file. File®Save As writes to a new file.

To add routes and marks from some other race file into your current race use File®Import Routes. You can also import and export routes and waypoints to and from a multitude of other formats, such as Google Earth’s KML. BLUEWATER uses gpsbabel to handle format conversions. Consult www.gpsbabel.org for documentation about available formats.

You can also import positions of boats in your race from a simple text file of position information (such as a race committee might transmit) using File®Import Positions.

Polar Files

Polar files specify the performance characteristics of boats. Performance and routing calculations depend on polar files. They can be viewed and modified from Tools®Polar Manager. Each route has one associated polar file, corresponding to a boat that is sailing that course. Polar files are loaded automatically from the polar file directory specified in your preferences file.

Grib Files

Grib files contain weather forecast data such as wind, waves, and sea-level pressure at points on a latitude-longitude grid. They are produced by various national weather services, and made available either for free or for pay from various on-line sites. In Bluewater Racing, you can view data from any number of Grib files simultaneously. In addition, wind data from Grib files is used for performance and routing calculations. The router generates special Grib files as part of its output. Use Tools®Grib Manager to control how Grib data is displayed and used.

Performance Calculations

Whenever polar and wind data is available, the program automatically calculates how long it will take to sail along each route. The results can be viewed in the Route Manager and Route Details windows. The arrival time is computed for each route point. The arrival time at point zero, the first point, is set equal to the start time specified in the route options (Tools®Route Manager®right-click on a route®Route Options). When you mouse over a route point, the calculated arrival time is displayed in a popup. Saving a route saves the arrival times. If you don’t want these arrival times to be subsequently overwritten (when a different wind file or polar file is used) then check the “read only” box in the route options window.

If the arrival time of a route point falls within the current Grib period, (selected in the upper right toolbar area), the route point is highlighted with a green box. So, as you click through Grib periods, you will see highlighted the route points that are reached during that time period.

Performance calculations make use of two parameters, “Time Resolution” and “Distance Resolution”. They can be modified via the route options window. The smaller the time and distance resolutions, the more accurate the computed arrival times, but the lengthier the computation.

“Time Resolution” is specified in decimal hours, and determines how finely a forecast wind period is interpolated. For example, if the wind forecast period is 12 hours, and the time resolution is 2, then wind values will be interpolated every two hours within the period. Within each two hour window, the wind will be assumed constant.

“Distance Resolution” is specified in decimal nautical miles, and controls the fineness of a flat-earth approximation used in the performance calculation. Each route segment is divided into subsegments of length given by the distance resolution. The region of the Earth’s curved surface containing each subsegment is projected onto a flat surface, in which the boat travels along a straight line of constant heading. This projection results in slight inaccuracies, which increase closer to the poles. However, a distance resolution value of 60 NM gives errors less than 0.1% anywhere between 80N and 80S.

Wind and polar data can be used to compute optimal routes between points. When such a routing computation is performed, up to five internal data sets are generated: isochrones, reverse isochrones, the forward routing tree, the reverse routing tree, and a routing sensitivity map. You can choose which will be generated using Tools®Route Manager®right-click on a route®Route Options. These new data sets are treated as internal Gribs, and can be accessed via the Grib Manager.

Charts

Two type of charts can be viewed, vector and raster. BLUEWATER cannot handle charts that span the dateline, ±180°.

The built-in planning chart is a vector chart constructed from the “Global Self-consistent Hierarchical High-resolution Shorelines” (GSHHS) data set. This is in turn constructed from the World Vector Shoreline (WVS) database (U.S. NGA) and the CIA database. The planning chart includes rivers and national/state/provincial boundaries, but these are not displayed unless requested using Tools®Preferences. The planning chart also displays port data from the World Port Index. Only some of the available port data is stored in the chart, but you can use the port index number to get the full information from the Port Index, which you can either buy or get online for free from the Maritime Safety Information division of U.S. National Geospatial-Intelligence Agency (the same people that put the maps into the cruise missiles).

The planning chart can be zoomed arbitrarily down to a maximum resolution of one micro-degree. This does not mean the shorelines should be considered accurate to that level. NGA estimates that errors in the WVS may be as much as 250 m. MARINERS ARE CAUTIONED NOT TO TRUST THE PLANNING CHART FOR SAFETY OF NAVIGATION.

Arbitrary vector files (in which shorelines are described as polygons) can be used as a chart, after the file has been converted to a simple text format.

Raster charts are images in JPEG, BSB, PNG, TIFF, etc. format. They are limited in the amount of zoom, depending on the image’s pixel resolution. Bluewater racing detects the image format based on the file extension and uses the TK Img library to load the image, so any format loadable by Img can be handled, as long as an appropriate file extension is used.

BSB is a standard raster format used by NOAA for marine charts. It includes geocoding information internally, so BLUEWATER can read and display them without any work on your part. BSB charts are available for free download online.

To make an arbitrary image into a chart, you have to "geocode" it, meaning you have to tell the program the chart's base latitude and longitude and its scale. BLUEWATER can only geocode images that are drawn in the Equidistant or Mercator projections. Geocoding is easy: just click on a couple of points in the image at known positions (say, the intersections of lat/lon lines in the image). Then type in their latitude and longitude, and tell BLUEWATER the projection type. (Most NOAA weather images are drawn in Mercator projection).

Latitude, Longitude, Time and Direction

Input Formats

At various times you may want to enter latitude, longitude, and time values into the program, or have it read such data from text files.

BLUEWATER works with latitude and longitude in the ranges [-90°, 90°] and
[-180°,180°], respectively, with South and West latitudes and longitudes being negative. However, it does its best to understand a variety of other ways of specifying latitude or longitude. Please do not type in latitude or longitude values in the form DD.MMSSS (e.g.: 22.13561, meaning 22° 13' 56.1") or DD.MMM (e.g.: 22.13561, meaning 22° 13.561'), because the program cannot tell them apart from the DD.DDD format (e.g.: 22.13561, meaning 22.13561°). You will be safe entering latitudes or longitudes in the forms DD.DDD, DD:MM.MMM, or DD:MM:SS.SSS. (E.g., for S 22° 13' 56.1" enter -22.23225, -22:13.935, or -22:13:56.1. Or just type in S 22d 13' 56.1"; BLUEWATER will be perfectly happy with that.)

BLUEWATER uses the underlying Tcl facilities to parse dates and times. These are very powerful and can make sense of a lot of tings. However, to be really safe you can always specify dates and times in U.S. format as MM/DD/YYYY HH:MM:SS Z (e.g. 05/12/2007 19:45:00 Z, meaning March 12 2007 at 7:45 PM GMT), or International format as YYYY/MM/DD HH:MM:SS Z (e.g. 2010/04/10 02:15:00 Z). Most times are displayed in Zulu (a.k.a UTC or GMT), indicated by a "Z" after the time, because that is how Grib files are encoded. US Eastern Standard time is GMT -5 hours, US PST is GMT -8 hours. When a time without a date is encountered in a file or an entry field, the date defaults to “today.” A date without a time defaults to 00 Z. A time without a Z is interpreted as being in the time zone of the computer (ship's time).

Display Formats

Using the Preferences menu item, you can :

Specify the format for display of latitude/longitude values.
Change the display font.
Choose whether to display courses and wind directions in degrees true or magnetic. The magnetic variation at the start point of the course leg is used to compute magnetic course. The same rule is applied to bearings given in "dist" mode. The magnetic variation is displayed in degrees, positive for east variation, negative for west variation. Therefore, magnetic heading equals true heading minus variation.
Choose to display time in Zulu (a.k.a. GMT or UTC) or Local, meaning the computer's time zone and daylight savings settings.

The Main Window

The main window shows a chart and route information. By default, the chart is the GSHHS planning chart.

Mode Buttons

The four right-hand radio buttons specify the current operation mode on the chart. You are either moving around the chart with left mouse clicks, zooming with left clicks, estimating distance and heading between points with left clicks, or adding and moving route points with left clicks.

Map Mode:

Left-button and motion scrolls map.
Right-button displays weather values at that point for the time shown in the Grib Periods dropdown box.

Zoom Mode:

Left-button and motion sweeps out a zoom area.
Ctrl-left-button re-centers map at cursor.
Right-button displays weather values, as above.

Dist mode:

Left-button and drag to show distance, true course and magnetic course between start point and end point. A temporary mark is made on the screen. To convert the temporary mark to a new waypoint or new route, right click on it. The temporary mark disappears with next left click.
Right-button displays weather values, as above.

Edit Mode:

Left-button in a route/mark point selects it to move
Left-button in a route edge inserts a new point into the edge.
Left-button near a route endpoint adds a new endpoint to the route.
Right-button in a route/mark point brings up an edit menu
Right-button elsewhere creates a new route with a single point, or new mark.
Ctrl-Z undo last map edit

All modes:

z/Z keys zoom in/zoom out
up-arrow/down_arrow advance to next/previous GRIB period

Zoom Buttons

Zoom dropdown box: with Mercator projection, sets width of main window in degrees. With Equidistant or Plate Carree, sets height of main window in degrees.

Route: zoom to show all visible routes.

Grib: zoom to show all visible Grib data.

Chart: zoom to show the entire current chart.

Grib Periods dropdown box

Grib files normally contain forecast sequences: weather forecasts for a series of increasing times in the future. Each time is called a forecast period. The Grib Periods box contains the list of available forecast times. Select a time to display forecast data for that period. The keyboard up and down arrows provide a shortcut to move you up and down the list. For example, if the selected date-time is “2001-01-01 1200Z”, then for each weather parameter (e.g., wind or pressure), the data for the forecast period starting at 01/01/01 at 12Z is displayed.

When multiple Grib files are loaded, the Grib Periods list contains the union of all forecast times in all Grib records. It is possible that some forecast sequences will not contain forecasts at the precise time selected in the Grib Periods box. In this case, the forecast period that contains the selected time is used. If there is no such forecast period, no data is displayed.

To override this automatic behavior, use the Grib Manager. You can choose a specific forecast period for each weather sequence. The data for this period will be displayed regardless of what is going on with the Grib Periods box.

As you cycle through periods in the Grib Periods box, any route point whose arrival time falls within the selected period will be highlighted with a green box. This allows you to see where the boat will be along the route during that time period.

Routes and Marks

Information about routes and marks is accessed through the "Tools→Route Manager" window.

From the Route Manager, you can also modify the options for each route. Tools®Route Manager®right-click on a route®Route Options. The most important options are the start time of the route and the associated polar data file.

The Route Manager lists the routes and their lengths in nautical miles. In addition, if wind data has been loaded that covers the start time for the route, then the estimated time of arrival (ETA) at the last route point is displayed, and the corrected handicap time enroute (ETE) is shown. The handicap formula can be modified from the options window. The handicap formula is any formula using two variables, "$time" and "$dist". The former refers to the uncorrected ETE (in decimal hours) and the latter the distance in nautical miles. So for a distance handicap formula given by, say, +1/2 a minute per nautical mile, your corrected time formula would be "$time + (0.5/60)*$dist", giving corrected time in hours.

You may choose to see detailed information for each route, by double-clicking on a route in the list, or using the "details" button. This gives heading, time, distance and more info for each leg of the course.

In the route details window, GC Course means the initial course if the leg is to be sailed as a great circle. The GC course will change as you progress along the leg, but presumably you are using a GPS to sail the course, and the GPS will automatically adjust. "Rhumb course" means the constant course you would use to sail that leg along the rhumb line. The rhumb line is the straight line drawn on a Mercator projection chart. (Pre-GPS, a navigator would divide a great circle course into a sequence of short constant-heading rhumbline legs.)

Additional route options:

Visible: if unchecked, the route will not be displayed.
Nondestructive: if checked, optimization will create a new route. If unchecked, it will overwrite the old route.

Making a Route Point Refer to a Mark

You can make a route point be located at a mark by entering Edit mode, right-clicking on the route point, and changing the mark field to be the desired mark. This is called a mark reference. The advantage of a mark reference is that if the mark is moved, then all route points that reference that waypoint will also be moved. Also, if it’s a course mark, you don’t need to keep typing in the coordinates, or carefully moving the point on the chart. Just edit the point to set the mark reference, and it instantaneously moves to the mark’s location.

Importing Position Reports

Race committees often provide the positions of all competitors by email. BLUEWATER includes a means to import these reports and append the positions to existing routes. For example, here is a position report for competitors in division 2 of the 2007 Transpac race.

From: "Dave Lee" <dlee@w6zl.com>

To: wdc3829, undisclosed-recipients:

Subject: Transpac Daily Position Report

Date: 23 Jul 2007 16:57:00 -0000

Follows 0600 positions as taken at 0800 SSB roll call by Alaska Eagle;

2A,HOLUA,97656,7/23/2007 06:00,22.5667,-145.2833

2B,HUGOBOSS II,GBR 3055L,7/23/2007 06:00,24.3167,-146.0167

2C,LUCKY,USA 52152,7/23/2007 06:00,23.6333,-143.5167

2D,MORNING LIGHT,USA 52007,7/23/2007 06:00,22.5333,-145.3667

2E,PEGASUS OP-50,101,7/23/2007 06:00,24.0167,-145.3833

2F,SAMBA PA TI,USA13131,7/23/2007 06:00,22.1833,-145.3833

2G,SKYLARK,US 540,7/23/2007 06:00,22.8000,-145.2000

2H,TRADER,52111,7/23/2007 06:00,21.9500,-142.4833

2I,WESTERLY,18997,7/23/2007 06:00,23.7667,-144.7000

AE,ALASKA EAGLE,US 59707,7/23/2007 06:00,22.4333,-155.6833

ANNA KATARINA has retired, motor sailing to Honolulu

If you wish to discontinue receiving this daily report, send an email to dlee@w6zl.com with REMOVE in the subject line.

Suppose you are sailing on HOLUA and you are keeping track of your competitors in division 2. You have created routes for HUGOBOSS II, LUCKY, etc. that mark their daily positions up till now. You want to include the July 23 positions.

Select FileàImport Positions. You will be asked for an import file, an import field specification, and the import field separator character(s). The import specification describes the layout of a position data, such as in this line:

2A,HOLUA,97656,7/23/2007 06:00,22.5667,-145.2833

The fields necessary for BLUEWATER are the route ID (which should match the name of an existing route in your race), the latitude, longitude, and the date-time fields. All other fields in the line are junk. The import specification is a list of keywords taken from the set {id, date, time, datetime, lat, lon, junk}. So for Transpac 2007 position reports, the import spec reads: "junk id junk datetime lat lon". The field separator character is ",".

The position file is scanned, and any line that does not look like a position report line (e.g. mail header line) is ignored. For any ID that can be matched to a loaded route, the position is appended to the route. For unmatched ids, you are offered a choice of creating a new route with that ID, or ignoring them.

The import function can only handle positions that are provided as a single line of text fields separated by some consistent characters (such as commas, spaces, or tabs). The scanning is not guaranteed to be perfect, and you may need to delete email headers etc. before trying to import. But the above example imports just fine as is, so with any luck you'll be mostly okay.

You can add a default import file spec to your bluewater.pref file.

If the import file contains multiple positions with the same id, then each successive position is added in order to the end of the route. This gives yet another way to create a route -- simply write a little text file of positions with the same route id, and then import it.

Weather Data and Grib Files

A Brief Introduction to Gridded Binary (Grib) Files

DISCLAIMER: This interface was built to handle weather data useful to mariners. The Grib format by itself is very general. I've made no attempt to handle all possible cases, or even a majority of possible cases. BLUEWATER has handled Grib files from SAILDOCS, SAILFLOW, and ZYGRIB. It provides general support for the standard WMO weather parameters on simple latitude/longitude grids, and custom support for weather parameters like surface winds, temperatures, waves, cloud cover, sea-level pressure, and 500mb chart information. The Grib interface is built on top of the freeware MEL library developed by the US Navy.

Please see the WMO Manual on Codes, or see "A Guide to Grib Version 1" for more info (for example, http://badc.nerc.ac.uk/help/formats/grib/gribdoc.txt). (WMO = World Meteorological Organization.)

"Gridded Binary" is an international format for the exchange of numeric data specified at some set of grid points. It was designed for weather data at points on the earth’s surface, but in principle one can encode anything in Grib format. The simplest possible Grib file would contain exactly one record (also called a message). A record gives the grid values for a single weather parameter (e.g., sea-level pressure) at a single forecast time (e.g., 72 hours from the computation time.) The record has a header section that describes the weather parameter, the grid layout, the reference time of the record (roughly, when it was created), and a multitude of other stuff.

Typically, a weather file you download from a source such as Saildocs.com will contain multiple parameter types (perhaps winds, sea level pressure, and 500mb heights.) Furthermore, for each parameter there will be multiple forecast times. BLUEWATER (like pretty much every other Grib display program) aggregates all the records for a single parameter into a "forecast sequence". You view and manipulate sequences.

BLUEWATER also produces various special-purpose Grib sequences that are accessed through the Grib Manager. These contain data produced during optimization runs, and can be viewed like any other Grib record.

What Kinds of Grib Files Can Be Loaded?

The program supports only Grib Version 1 files. The Grib file must be a simple Lat/Lon grid. It cannot be Gaussian, Lambert Conformal, or any other special projection. A GDS (Grid Descriptor Section) must be present. (The program does not know about the WMO’s standard grids that can be specified without a GDS). The grid cannot be thinned or quasi-regular. Vector data must contain both U and V data. If the data spans the International Date Line, it will be broken into two subsets, one for each hemisphere.

Fortunately, it seems that most of the weather data you can download satisfies these restrictions.

The program will only display parameter types given in WMO Table 2. The parameters that people use most often, such as wind or pressure, have been given specific support. (The parameters with specific support can be seen by examining the file “gribDescription.tcl”.) They include all the parameters accessible through Saildocs, (10m and surface winds, 500mb heights, sea-level pressure), the Wave Watch 3 parameters (sea-level winds, significant wave height, wave directions and wave periods), surface temperatures, and cloud cover. Beyond that, the program makes a best effort to display the parameter in a reasonably sensible fashion. There are no promises.

Various weather centers employ local extensions to WMO Table 2, using indices higher than 127 to indicate additional custom parameters. Bluewater Racing knows nothing about those extensions, and in addition it has its own custom local parameters. If you attempt to load a Grib file containing parameter indices higher than 127, the program behavior is undetermined but probably bad.

The program supports “missing values” indicated in the BMS (Bit Map Section). I strongly recommended, however, that you do not use wind data sets with missing values for performance calculations.

Contour lines for Sea Level pressure are labeled by the last two digits of their value in millibars. E.g., 1016 becomes "16" and 986 is shown as "86". Contour lines for 500 mb charts are labeled by meter heights divided by 10. E.g. the 5640 m contour line is labeled 564. (The special 5640 line is also shown bold.) These display choices match standard NOAA style. Wind barbs follow the convention that feathers are drawn pointing towards low pressure.

Grib Manager

The Grib Manager window ("Tools®Grib Manager) allows you to load Grib format files into BLUEWATER, to examine Grib header data, and to modify various options for the imported Grib sequences. Grib data is displayed on the chart in one of several formats. Scalar data, such as pressure or wind speeds, can be displayed as contour lines or a color map. Vector data, such as wind velocity, can be displayed as a scaled arrow or a wind barb.

The data can be “decluttered”. This is primarily useful for vector data such as winds. Decluttering reduces the number of wind barbs or arrows that are displayed in the window. Decluttering also makes the program faster. Decluttering is selected by default for wind data. For scalar data such as pressure, it is not used by default, since contour lines are not usually clutter-y.

By default, a wind sequence is usable in the computation of sailing times and optimum routes. To make it unusable for such purposes, uncheck the "routable" box. Even if a wind data set is decluttered for display purposes, the full data set is used for performance computations.

The selection of forecast period to display can be controlled through the “periods” drop-down box. If auto is selected, then the period to be displayed is determined by the value in the toolbar “Grib Periods” box. As that value is cycled, the displayed period changes accordingly. If number h is selected, then the forecast for hour h is shown, regardless of the value in the Grib Periods box. (This is the forecast for h hours after the sequence’s reference date and time, i.e., the time the forecast was created.) The “forecast” at hour zero (if it exists) is not a forecast at all -- it is the actual observed data used to generate the forecast.

If you know TCL and/or feel brave, you can adjust display styles for various parameter types by messing with the file "gribDescriptions.tcl" in the installation directory. The file contains some basic documentation.

Optimization

The optimization button on the Route Manager window allows you to optimize legs of the selected routes.

When you select one or more routes in the Route Manager window and push "Optimize," for each selected route the following actions occur:

The chart area covered by wind data from loaded Gribs is subdivided into a 2D grid of points, the optimization grid. The horizontal and vertical distance, in nautical miles, between adjacent grid points is determined by the Grid Size route option.

Each old route leg listed in the "Optimize Legs" route option is optimized to minimize the travel time between its endpoints. The old leg is replaced by a bunch of new legs as determined by the router. Each new leg goes between grid points in the optimization grid.

The optimizer assumes that you will sail at best VMG along each new leg. This may require tacking or gybing. The optimizer charges zero time for tacks and gybes. This simplifies the calculations, but obviously you won’t be tacking and gybing every minute that you sail along a leg. You should plan to tack or gybe so that you stay within the same grid squares as the leg you are following. This will be around after traveling a distance equal to one half the Grid Size value. So if the Grid Size value is 60 nautical miles, you should tack or gybe every 30 nautical miles.

The "optimization" is only an approximation. It is the best route traveling only great circle lines between optimization grid points. As you reduce the grid size, the grid becomes denser and denser, and the route gets closer and closer to the true optimum. But the time required to perform the optimization also increases. The running time is proportional to the number of grid points. Thus a 20x20 grid will take 4 times longer to solve than a 10x10 grid. All known planning programs (Deckman, Expedition, etc.) compute some kind of approximation to the true analytical function. We like our approximation better.

Optimization is controlled by various parameters that can be changed through the Route Options window. The Legs to be optimized are specified in the same way you specify pages to print in Windows: "1,4,6-10,12" would mean legs 1, 4, 6 through 10, and 12. The single entry "-" means all legs. Legs are counted starting at zero: leg zero is the leg from the first route point to the second route point, and so on.

The parameter “Max Range” determines the maximum length of a new leg in the optimized route. Smaller Max Range makes the computation faster but less accurate. The parameters “Distance Resolution” and “Time Resolution” control the accuracy of the estimated travel times, as discussed in the performance section.

The optimizer computes the wind at each grid point from the most detailed wind data available at that point in space and time. If the grid point is covered by multiple Grib wind sequences (that are marked "usable for routing"; see Grib Manager) then the “best available” wind data is used. Precisely, the wind sequence that has the maximum grid density and is also valid at the time of departure from the grid point is used.

For example, you might load a long-range GFS wind Grib, with 14 days’ worth of forecasts covering the entire 2000 nautical mile route you expect to sail along, but only defined at grid points 2° (120 nautical miles) apart. You might simultaneously load a SAILFLOW Grib, defined at grid points every 4 km, but only providing 2 days’ worth of wind forecasts after the race start time, over a 60 nm area around your starting mark. The wind calculation will use the SAILFLOW data when possible, in the region of the start, but fall back to the GFS data at later times further down the course. Thus you can use the most detailed wind available at the start, and go to the less-refined, longer range values only when you have to.

Any number of wind forecasts can be stacked up in this manner. In practice, however, you’ll probably only want three: a very local SAILFLOW-type forecast, a larger-scale COAMPS forecast, and a hemisphere-scale GFS forecast.

The optimizer will not compute a route that goes outside the latitude and longitude boundaries of the largest wind Grib. But when the arrival time at a route point falls after the valid time ranges for all wind data, then the last available time for the coarsest wind set is used. Therefore, if you only have wind data for five days, but the optimizer tells you that the minimum travel time is ten days, you should be suspicious. For the last five days of the trip, the optimizer has assumed that the wind is constant at the values given in the last forecast period. ALWAYS TRY TO GET WIND FORECAST DATA THAT COVERS THE ENTIRE TRIP TIME.

If the endpoint of an old leg is not marked "read only", then the ETA for that endpoint is updated and used as the start time when optimizing the next leg. If it is marked read-only, then the ETA at that endpoint is not updated, and the existing time at that point is used as the start for the next leg. If intermediate legs are skipped, then the old arrival time is used. If no old arrival time is available, optimization is skipped.

So, to compute an optimization for an entire route, make sure the read-only flag is cleared for all points, set the "at time" route option to the start time of the race, set "optimize legs" to "-", and push optimize.

To only optimize the last leg of the route (say the nth leg), set legs to "n-1" and the time for second-to-last route point to your desired start time.

The optimizer will not create a route that crosses land. If it cannot complete the route without crossing land, it will fail. This is likely to occur with a large Grid Size value and an endpoint inside a tight bay, or when there is a narrow neck of water to pass through, as in the Chicago-Mackinac race, at the Mackinac straits. (The technical problem is that the optimizer only considers great circle legs between grid points, and the land is blocking all such legs.) The way around this is to either make the Grid Size smaller, or to add route points that guide the boat through the constricted areas of the voyage without optimization.

Analyzing the Quality of the Optimized Route

When optimization is completed, several data sets are created in Grib format and added to your set of loaded Gribs. You can work with them via the Grib Manager. These data sets allow you to analyze the quality of the routing solution. You can control which data sets are created through the “route options” window. The data sets are:

1. Isochrones. The arrival time for each grid point is determined by the optimization. An isochrone is simply a contour line in this data set. A contour line labeled t is the set of positions that can be reached (by sailing as fast as possible) for t hours.

2. Routing Tree. The best route to arrive at each grid point is displayed. This always takes the form of a tree rooted at the starting point.

3. Reverse Isochrones: The maximum time that a grid point can be left while still ensuring that the boat arrives at the finish point at most 10% later than the optimized time is computed. Reverse isochrones are the contour lines of this data set. A line labeled -t is the set of positions that can be left t hours before the optimal finish time plus 10%, and arrive exactly at the finish time plus 10%.

4. Reverse Routing Tree. Same as the routing tree, except shows minimum time paths inbound to the finish, assuming you arrive 10% later than the fastest time from start to finish.

5. Sensitivity. This is computed from isochrones and reverse isochrones, and is intended to give you a rough idea of how far you can sail away from the computed optimal route and still arrive within 10% of your estimated optimal time. Roughly, if you sail a course anywhere inside the contour labeled x, then with probability x you should get to the finish no more than 10% later than the optimal time. (i.e., your ETE will be no more than 1.1 times the computed optimal ETE).

The intent of sensitivity analysis is to provide you, the navigator, with some notion of how flexible the optimal route is. If you have other tactical or strategic considerations, such as maintaining a controlling position on competitors, or a different sense of how the weather will develop, then sensitivity analysis gives you an idea how far you can wander from the optimal route and still be pretty close to the optimal time.

Obviously, you cannot sail arbitrarily inside a sensitivity contour -- sailing back and forth is unlikely to be successful. The technical definition: for any grid point within the contour labeled x, if you sail to that grid point optimally, and then sail from that grid point to the finish optimally, it will take you no more than
(1 + .1*(1-x)) times the optimal time. For example, sailing within the .80 contour region should get you to the finish within 2% of the minimum time.

To get isochrones and the forward routing tree, check “Isochrones” in the route options window. To get Reverse Isochrones and the reverse routing tree, check “Rev. Isochrones”. To get Sensitivity, both boxes must be checked.

Route File Format

Race files are stored in the GPX format. GPX (the GPS Exchange Format) is a light-weight XML data format for the interchange of GPS data (waypoints, routes, and tracks) between applications and Web services on the Internet. Files have the suffix “.gpx”. The GPX schema and documentation can be viewed at http://www.topografix.com/gpx.asp.

Prior to version 1.10, BLUEWATER used the "waypoint+" format, with the file suffix ".wp+". BLUEWATER will still read race files in waypoint+ format, but it only saves files in GPX format. GPX, being an XML format, is very wordy, but it is more portable.

You can edit GPX files directly with your favorite text editor (e.g., NotePad or Emacs). You can also view them with any web browser, and edit them with an XML editor. Figure 1 shows a sample race file.

The first section is header information required by XML format files.

Next, two marks named “Start” and “Finish” are defined, using the <wpt>,</wpt> tags.

Next, a single route is defined using the <rte>,</rte> tags. GPX allows for application-specific extensions via the <extensions> tag. BLUEWATER adds all the non-default route options between tags of the form <bwr:option-name>. In the example, options include the route name, <bwr:name>SydHob</bwr:name>, the route polar data file, <bwr:polar>J120</bwr:polar>, and the start time <bwr:attime>@grib</bwr:attime>.

Within each route, route points are given using the <rtept> tag. The <type> of the point is either 0 or 1. A 1 means the point is read-only. Any time prior to 1/1/1970 is taken to mean “time not available,” i.e., a valid time has not been added or computed for this point. (“Why this date?” you ask. It is an internal standard that refers to the magical date that UNIX was invented at Bell Labs.)

A GPX format extension is added to the second route point: a “mark reference” <bwr:wpp>Finish</bwr:wpp>.

Route Point by Reference to a Mark:

If a <rtept> entry contains a mark reference, then that route point is defined to be located at the mark whose name occurs between the <bwr:wpp> tags. In the example, it’s the “Finish” mark. The mark must have been previously defined with a <wpt> entry. As race files are read and imported, discovered marks are loaded into the program’s mark database. The mark reference is checked at the time the route point is processed; the referenced waypoint must be in the waypoint database, or an error occurs. The latitude and longitude specified in the <rtept> tag are

Figure 1: Sample race file in GPX format

ignored, and route point is set to the position of the mark. If the mark does not exist, then a warning message is generated and the route point is placed at the lat/lon coords in the <rtept> tag. The advantage of using a mark reference is that if the mark is moved, then all route points that reference that waypoint will also be moved.

You can add a mark reference to a route point by selecting Edit mode, right-clicking on the route point, and setting the mark field appropriately.

Polar Files

Polar files describe the expected speed of a given boat for various values of wind heading and speed. The data in a polar file is a collection of triples (ws, wh, bs) where ws is the windspeed, wh is the true wind angle, and bs is the expected boatspeed. BLUEWATER uses this data to interpolate (by cubic splines) the general function bs(ws,wh). This function is required by the routines which compute performance and routing. Each route must be assigned a polar file before any performance can be computed. The assigned polar file can be changed using the “route options” window. (Right-click on a route in the Route Manager or on the chart.) It is specified by its file name, minus the extension “.pol”. Thus, “J120.pol” is entered as “J120” in the route options field. Names are case sensitive.

You can specify a collection of polar files to preload automatically in the preferences menu (Tools®Preferences), or by editing the file bluewater.pref and adding files to the field “initpolar”. When the program encounters a route with a polar that has not yet been loaded, it attempts to load it from the polar directory specified in the preferences file. This can be modified from Tools®Preferences.

Polar data is called that because it is typically presented as a series of curves of constant windspeed drawn on a polar chart. You can use the Polar Manager (Tools®Polar Manager) to view or modify the polar curves. Left-click and drag a polar control point to change the curve. Polar data is stored in simple text files with one line corresponding to a constant windspeed. The format is described below; it is compatible with Expedition format.

You are allowed to have a polar curve for zero windspeed giving non-zero boatspeed. This would, for example, describe a cruising yacht able to use its motor. You can build polar files for one boat in different configurations (cruising, racing, high seas, flat water, etc), but each route can have only one polar file at a time.

Polar data for a few boat types is included with the program. You can get polar data from boat manufacturers or US Sailing.

Polar file format

A polar file is a sequence of lines. Each line describes the curve for one windspeed, ws. Optionally, the first line may begin with the string "pol", in which case it is treated as a comment line. This klunky format is not my idea; it is for compatibility with Expedition.

Each curve is described on one line of the text file by a windspeed, followed by a sequence of pairs of True Wind Angle and boatspeed. (TWA in degrees, BSP in knots)

eg:

10 30 0 45 6 90 8.1 160 7 180 5

15 30 0 40 8 90 12 150 10 165 9 170 5

This gives two curves, one for windspeed 10, one for windspeed 15. Different curves may have different TWA points, and different numbers of points. The line for windspeed 10 specifies a boatspeed of zero knots at a true wind angle of 30 degrees, a boatspeed of six knots at TWA 45, 8.1 knots at 90, seven knots at 160 degrees, and five knots at 180 degrees.

There can be a zero windspeed curve with non-zero boatspeed, i.e., “when the wind is gone, the motor's on.”

Rules for the data in polar files:

1) One windspeed curve per line.

2) The curves must be listed in increasing order of windspeed.

3) There must be a least 3 points per curve.

4) There must be at least one non-zero windspeed curve.

5) In each line, the TWA's must be increasing down the list.

6) The minimum TWA is zero, and the maximum is 180.

7) The 2nd TWA in a line is the best VMG upwind angle for that windspeed. The 2nd to last TWA is the best VMG downwind angle for that windspeed

8) The first TWA should be less than any 2nd TWA in any curve. Ideally, zero.

9) The last TWA should be greater than any 2nd-to-last TWA in any curve. Ideally, 180

If these rules are broken, the behavior of the program is undetermined.

GPS Support

BLUEWATER provides GPS support through a helper program, gpsbabel. Please visit www.gpsbabel.org for more information about this program.

Select Tools®Enable GPS to connect the program to a GPS unit. Position and course information will be displayed on the upper toolbar. In addition, the GPS_pos waypoint will be created and updated, and positions will be added to GPS_track.

You must specify a connection port for the GPS, and a download format. Select Tools®Preferences to modify these values. For Windows, it will be a serial port such as “com1:”, or a usb port such as “usb:” It will depend on your unit and computer. See the gpsbabel manual for more information.

You can connect to the GPS in one of two modes: Garmin proprietary (obviously only useful for Garmin units) or NMEA. Garmin proprietary mode supports uploading and downloading of routes and waypoints in addition to position reporting. NMEA only allows position reporting. You need to set your GPS to the appropriate download protocol.

In Garmin mode, you may right-click on a route and upload it to the GPS. In addition, under Tools you can download all routes and waypoints from the GPS into BLUEWATER or you may upload all routes and waypoints in the current race to the GPS.

The TCL Console

Tools→Console brings up a TCL console. This will give you access to the internal data structures of the program. If you know TCL, good luck, have fun.

Manipulating Gribs from the console

You can view raw Grib numeric data at the appropriate grid points for the sequence identified by <internal id> at period <period> by opening the console and typing:

gm::draw_raw_data $c raw <internal id> <period>

Remove the raw data by typing:

$c delete raw

<internal id> has the form “gnn” for some digits nn. It can be found for each sequence from the Grib Manager. <period> is the integer index of the desired forecast period.

Additional functions are available to manipulate Grib data files directly from the console. They are currently undocumented. Please email the author if you are interested in learning more.

Manipulating Routes from the Console

A collection of functions are available to manipulate Routes directly from the console. They are currently undocumented. Please email the author if you are interested in learning more.

The Deprecated Waypoint+ Text File Format

The basic waypoint+ format was developed by Brent Hildebrand. Please see:

http://www.tapr.org/~kh2z/Waypoint/OverviewInfo.htm

http://www.tapr.org/~kh2z/Waypoint/ReleaseHistory.htm

From those pages:

A route is described by a Route Name entry, followed by one or more RoutePoint entries.

RN, route number, route description

RP, latlonformat, routepoint name, latitude, longitude, date, time, waypoint description.

Example

RP,D,TRAIL2, 34.085984230,-116.8862808589,11/19/1995,06:01:00,FALLS

A mark is described by a single Waypoint entry.

WP, latlonformat, waypoint name, latitude, longitude, date , time , waypoint description.

Example:

WP,D,A,34.064531,-117.295950,11/23/1995,19:29:00,I10 X1215

WP,DM,B,34.06548,-117.80632,11/23/1995,19:29:00,I10 X I215

WP,DMS,C,34.06453,-117.29595,11/23/1995,19:29:00,I10 X I215

D=decimal degrees; ddd.dddddddd (34.064531922)

DM=degrees minutes; ddd.mmmmmmm = ddd mm.mmmmmmm (34.06548 = 34 6.548')

DMS=degrees minutes seconds; ddd.mmsssssss = ddd mm ss.sssss (34.06453 = 34 6' 4.53")

Brent Hildebrand writes: "I'm changing the general format of my TXT files. The program will still read the old files, but write only the new files. The new format will only change the line definition word. These can be in upper or lower case, or any combination."

Waypoint WP

RoutePoint RP

RouteName RN

Datum Datum

Enhanced WAYPOINT+ format for BLUEWATER.

The RN route description field can contain any number of option-argument pairs, such as “-name MYROUTE,” separated by whitespace.

If the RP description field contains the text "-ronly" (separated by white space) then the immediately following text item is taken as a boolean indicator. If true (in any acceptable TCL boolean form, e.g. “-ronly 1’ or “-ronly True”) then this waypoint cannot be modified by the program. It cannot be moved or deleted or have its date and time fields changed.

The RP date and time fields can be left empty. Unless -ronly True is specified in the record or the RN record, the date and time are ignored. When -ronly is true:

If the RP time field has no specified time zone (e.g. “PST” or “Pacific Standard Time”), then Zulu (GMT) is assumed.
The date, time, and time zone fields can be given in any format acceptable by TCL, however they will be written out in standard WAYPOINT+ format.
If date is empty, it defaults to the current date.
If time is empty, it defaults to 00:00 Z.

e.g

RP,D,N01,33.512645,-117.897051,01/01/2001,20:45:29,-ronly 1

RP,,,34.06453,-117.29595,,,

Waypoint by Reference:

If the RP description field contains the text “-mark <wp-name>”, it is treated as a reference to a waypoint named <wp-name> that must have been previously defined with a WP entry. As race files are read and imported, discovered waypoints are loaded into the program’s waypoint database. The waypoint reference is checked at the time the RP is processed; the referenced waypoint must be in the waypoint database, or an error occurs. The position of the route point is set to the position of the waypoint.

Example:

RP,D,1,,,,,-mark Start

If a waypoint is moved, all route points that reference that waypoint will also be moved.

Acknowledgements

The GNU project for emacs and the gcc compiler. http://www.gnu.org

The MinGW project for Windows development environment and C runtime libraries. http://www.mingw.org

ActiveTcl for Tcl/Tk 8.5 http://www.activestate.com/tcl

Vector shoreline data from GSHHS: Global Self-consistant Hierarchical High-resolution Shorelines. Copyright © 1996-2004 by P. Wessel and W. H. F. Smith. (pwessel@hawaii.edu) (http://www.soest.hawaii.edu/pwessel)

The World Port Index database from the U.S. National Geospatial-Intelligence Agency. http://www.nga.mil/portal/site/maritime/

WMO translation tables, W.Ebisuzaki et. al, National Center for Environmental Prediction, NOAA. (wgrib.c).

The National Geophysical Data Center, U.S NOAA, for the World Magnetic Model, WMM.COF, and associated software, http://www.ngdc.noaa.gov/geomag/WMM/soft.shtml.