Weatherfax

weatherfax

Author: Sean D’Epagnier, August 26, 2021, Version v1.0
Maintainers: Rick Gleason, Jon Gough and the Plugin Team
Development Details: PI Manager (PIM) Workflow uses the Testplugin Template

Purpose

Retrieves internet image files, reads image files or decodes audio and then Overlays the image on top of charts.

wx 0 retrieve internet overlaid on chart

Installation and Preparation

Using Plugin Manager (PIM)

Weatherfax is available as a managed plugin (PIM), which is the easiest way to install the plugin. The OpenCPN Manual has general information in Plugin Download, Install and Enable for installing this plugin. This is the preferred way.

In OpenCPN, go to the Options → Plugins and download, install and enable the Weatherfax plugin.

  1. In OpenCPN Click Tools-Options-Plugins

  2. First "Update" the master plugins catalog.

  3. Select the Weatherfax entry and "Install" the plugin.

  4. In the list of installed plugins "Enable" the Weatherfax plugin and "Apply".

  5. Use “Preferences” to set your preferences (should be self-explanatory). Then “Apply.

  6. After successful installation, the plugin should be available in the plugins tab of your OpenCPN options dialog box.

  7. Then close Options and the Weatherfax Icon should appear in the Toolbar.

  8. Then open it and explore the top menus.

  9. With an internet connection it is quite easy to select the “HF Radio Schedules” to select and set alarms for use with a receiver, or to select the Internet Schedules and then retrieve Weatherfaxes via the Internet and overlay on the chart. Audio Capture requires a connection.

wx 2 retrieve menu

Use Legacy Plugin Package Installer (PI)

The second way is to download a Legacy PI Package Installer (Windows .exe, Linux .deb or MacOS .pkg) from the OpenCPN website, to download Weatherfax

Retrieve Weatherfax Image files with an internet connection

If you have an internet connection, first Retrieve > All > HF Radio Schedules.
Then Retrieve > Internet > Select NOAA > Select Boston (for example) > Select 24hr 500mb Forecast
The Weatherfax image file will download and be overlaid directly onto a chart.

wx c0 ret inet menu 1 0

Lat 42 Long -70 –> Servers: Noaa —> Regions: Atlantic —→ Select Contents —→ Retrieve

wx c0 ret inet menu 1 0

Lat 42 Long -70 –> Servers: Passage —> Regions: N. Atlantic —→ Select Contents —→ Retrieve

It is a wonderful planning tool for cruises or passagemaking. There are several options, but * Select “Internet” to retrieve HF Radio Schedules via the internet. * Then Select “NOAA” Under “Servers” you will see “Stations” fill up. * Then select “Boston” and the Internet Retrieval choices are automatically listed in the menu area. * Select several faxes and pick “Retrieve Scheduled” or “Retrieve Selected”.

Internet Retrieval Summary

  • Retrieve…Internet

  • Select provider and region.

  • Select forecast you need.(X)

  • Highlight and use the 'Selected' button.

weatherfax inetpng

The plugin data directory contains an WeatherFaxInternetRetrieval.xml file that has database for meterological sites. The “Internet Retrieval” Option uses this schedule.

wx c1 ret inet aviation americas

Aviation Americas Forecast retrieved via the internet.

wx c2 ret inet passsage atlantic 012wind

Passage Weather Atlantic 012 Wind via internet.

wx c3 ret inet bermuda 3day

Bermuda 3 day via internet.

wx c4 ret inet noaa atlantic 24hr 500mb

NOAA Atlantic 24hr 500mb via internet.

wx c5 ret inet noaa atlantic 24hrsurf

NOAA Atlantic 24hr Surface via internet.

wx c6 ret inet passage ne

Passage Weather New England Wind 012

wx c7 ret inet passage novasoctia

Passage Weather Nova Scotia Wind 021


wx c8 ret inet downloaded list

List of Weatherfaxes downloaded. Highlighted one shows overlaid on charts.

The weatherfax will be overlayed generally in the proper location provided the weather service has not changed their fax formats. (The user can modify the associated WeatherFaxInternetRetrieval.xml file appropriately to add or modify the actions.) Users should please post changes to this file to the Weatherfax Thread for the next release.

Memory Use

Please note tht all the loaded maps stay in RAM until OpenCPN is closed. RAM occupation depends on the maps size. The number of weatherfax charts that can be stored in memory is dependent on the amount of memory available. When weatherfax_pi runs out of available memory, it will stop downloading weatherfaxes. As soon as you close WxFax and restart this memory is cleared, however the previous images then no longer have active georeferencing, so you will need to download them again for automatic georeferencing. Weatherfax_pi keeps all downloaded images connected to its coordinates and georeferenced until that session of weatherfax is closed.

For exemple on OpenCPN linux flatpak: Load 96 maps in Arome/France: 887MB Load 57 maps in Arpege/Europe: 2250MB

The limit seems to be the system RAM. I loaded 213 maps, more than 6GB and still okay and responsive.

HF Radio Weather Faxes

The plugin has a builtin database (WeatherFaxSchedules.xml) for HF Radio Weather Service Fax transmissions, which when used properly can automatically alert the user and begin decoding these faxes.

This schedule is updated from time to time using schedules and frequencies of all the official fax services worldwide from https://www.weather.gov/media/marine/rfax.pdf The detailed DWD schedule is also useful https://www.dwd.de/EN/specialusers/shipping/broadcast_en/broadcast_fax_102020.pdf?__blob=publicationFile&v=1

Retrieve > RF Radio Schedule Menu on the Filter Tab.

wx b1 ret hfradiosch filtertab menu

Retrieve > RF Radio Schedule Menu on the 1 minute Alarm Tab.

Retrieve > RF Radio Schedule Menu on the Capture Options Tab.

Retrieve > RF Radio Schedule Menu on the Information Tab.

Decoding Sound via SSB

Select Retrieve → Audio Capture (Ctrl+A)

A line from the SSB radio to the audio input of the sound card should be attached, and the radio tuned to the appropriate frequency (1.9khz below listed frequency and SSB mode) The SSB BFO must be adjusted correctly.

Retrieve > Audio Capture shown while recieving

image

The images decoded can then be calibrated and overlayed on charts. The resulting image can be exported to a chart, so the plugin also works as a general purpose conversion tool to make charts from images.

Weatherfax Image Wizard

Working with Files

The plugin can read and open numerous common image files, and audio files, and can save Kap files. The next step in development is to have it read Kap for ease of use with respect to coordinates being recorded and reused.

image

How to use Weatherfax files and the Image Wizard:

  • Save the files in a new directory on your hard drive in the same directory as your Charts. (I called the directory FaxWx).

  • Open the Plugin and a fax file and use the Weatherfax Image Wizard

  • From OpenCPN select the Weatherfax Icon, a window pops up.

  • Select Open and browse to the FaxWx directory and select a fax file.

  • Open the file.

Objective:

The objective is to set the x/y coordinates and lat/long properly so that the image will map directly over the proper area on the charts/globe. The Image Wizard allows user control over the necessary settings in a step by step process which ends in a successful chart overlay or not, depending on the skill of the user. If it does not work properly the first time, simply try it again. There are two basic types of projections the wizard can handle.

Mercator Projections

If the fax is a Mercator projection (orthogonal, not polar), click through the next screen that comes up and at the second screen set the coordinates and lat/long properly. (Screenshots will be added later) and click on through to see the fax overlaid on the charts.

Note: It is very difficult to test for poor coordinate and lat/long input, so it is best to have your lat long correct, otherwise strange things may happen with the overlay in Opencpn.

I first use a separate image viewer with the selected fax image, to zoom in and to write down the Lat/long and coordinates that I will be using. If you plan to export to a chart file then you should select “Get Aspect Ratio”

weatherfax inetpng

Polar Projections

There are other techniques used to modify a Polar fax onto a Mercator projection chart which are reviewed on the forum and will be more fully described later. Review the posts following this Cruiser’s Forum Post in the Weatherfax Thread in the Forums.

wx polarsu1

Coordinate 1 (Red) -Select a high latitude which must also lie on the vertical meridian running through the pole (N or S)
Coordinate 2 (Blue) - Select an opposing corner (either side) with lower latitude. Then hit Get Map, the Blue circles should follow the latitudes of respective coords. Adjust the left/right location with the PoleX value and adjust the circle radius with the PoleY value. Set the True Width Ratio value to 1.0.

From here, it should be possible to click “get mapping”

True width Ratio - Adjusts the width of the blue circles (a fraction like .8 makes the circles wider, and 1.2 makes them narrower). Adjust the true width ratio such that the blue circles align with the associated latitude lines, otherwise the “Apply” transformation will not render straight lat/long lines or will fail.

Pole X - Moves the center of the blue circles left and right. The blue circles should be centered on the vertical meridian which goes through the pole.

Pole Y - Moves the center of the blue circles up and down. The blue circles should be centered on the pole. Hit get mapping to see how this is working, because the blue rings change in width, and sometime the ring closest to the pole flips if the value is too far out of whack.

Equator Y - This does not appear to do much when you change the value, more about this value later.

If you are starting fresh with a Polar, and the blue rings are too wide after hitting Get Mapping, first check the lat/long entered and reset coords to be sure they are hit, then Hit 'get mapping again' then adjust the “True width ratio” so the blue rings align with the latitude lines. Once that is done don’t hit “Get Mapping” again, hit “Apply” the lines should be straight and orthogonal.

Here is an example of a WxFax overlay in Opencpn

wx overlay

File Export as KAP, File Open KAP

File Export as KAP

Image files that are downloaded and overlaid onto charts with specific coordinates, can now be saved as Kap files that save long/lat and coordinates with the file.

wx export open kap files

File Open KAP (Next Improvement)

Hopefully the plugin will also be made to read Kap files so that they can be automatically overlaid on charts without having to use the WeatherFax Image Wizard.

XML File Update - User Powered

Weatherfax URL’s and Coordinates and Schedules

It is the User’s job to update this information, by sending newly updated files of their area of the world. We cannot devote programming resources to this location specific task which changes regularly.

Note that the file weatherfaxinternetretrieval.xml has been separated into world region xml files, to make this task easier. We need voluteers to take a region and send in updates every six months to a year. Github pull requests to the maintainer for these changes are easiest, but emailed files are accepted too.

The critical files are: . WeatherfaxInternetRetrieval_(Region).xml’s (Multiple Regional files) . CoordinateSets.xml (installed in the program directory and saved in the User writable directory) . WeatherfaxSchedule.xml - For capture of sound.

Operational Notes

To start out with a clean slate, no previous weatherfax xml files.

  1. Remove the %localappdata%/opencpn/plugins/weatherfax/data files Use Options > Plugins > Uninstall the plugin.

  2. Remove the local user directory data, in particular coordinateSets.xml Manually remove this directory "C:\ProgramData\opencpn\plugins\weatherfax" or empty it.

  3. Not necessary, but you can manually remove all weatherfax_pi tarballs from "C:\ProgramData\opencpn\plugins\cache\tarballs". For more information about the location of installation files see the Development Manual - Installation Paths https://opencpn-manuals.github.io/main/plugin-installer/Installation-paths.html

  4. Use search "CoordinateSets.xml" in your files to determine where the Opencpn local user (writable) files are stored if you don’t know already.

When weatherfax_pi tarballs are installed, updated %localappdata%/opencpn/plugins/weatherfax/data files are installed. After internet weatherfax files are retrieved using Retrieve > Update Data Files and when weatherfax or opencpn is closed, the coordinateSets.xml in memory is saved to the User writable directory C:\ProgramData\opencpn\plugins\weatherfax with any Image Wizard coordinate changes made by the User. If the original coordinate name is use the changes are save to the new CoordinateSets.xml file ( instead of the installation coordinateSets.xml file at %localappdata%/opencpn/plugins/weatherfax/data). If New Coordinates is selected from the dropdown menu in the upper left (or New Coordinates 2 or 3) then those are saveed in a new User_CoordinateSets.xml file also located in the user writable directory C:\ProgramData\opencpn\plugins\weatherfax and which is used for the image in future downloads.

We also notice that the empty WeatherfaxInternetRetrieval.xml file and WeatherfaxSchedule.xml are copied to this directory as well. Is this so that users can customize them? I am not sure what is happening here. Should all the WeatherfaxInternetRetrieval_(Regional).xml files be copied there? Which files are actually being used by the program?

Maintenance of XML Files

The weatherfaxinternetretrieval.xml and weatherfaxschedules.xml files must be maintained and updated by all the USERS! Contribute your special url’s and schedules for the benefit of all.

  1. WeatherfaxInternetRetrieval.xml is dependent on many MET website services worldwide, and users who contribute xml files.

  2. WeatherfaxSchedules.xml is created from NOAA’s current Worldwide RF Radio Schedule https://www.weather.gov/nwr&in_desc=NOAA+Weather+Radio/ and https://www.nhc.noaa.gov/radiofax.shtml

Users are asked to submit error reports and updated xml files through github.com/rgleason/weatherfax_pi using "Issues" and attaching files or make a pull request.

WeatherFaxInternetRetrieval Files (12 Regional Files)

  1. WeatherFaxInternetRetrieval_PWx_Pacific.xml Passageweather Pacific

  2. WeatherFaxInternetRetrieval_PWx_India.xml Passageweather India

  3. WeatherFaxInternetRetrieval_PWx_Euro_Atl.xml Passageweather European

  4. WeatherFaxInternetRetrieval_PWx_Amer_Atl.xml Passageweather American Atlantic

  5. WeatherFaxInternetRetrieval_NOAA_OPC.xml NOAA Ocean Prediction Center

  6. WeatherFaxInternetRetrieval_NOAA.xml NOAA

  7. WeatherFaxInternetRetrieval_Navy.xml Navy Gulf Stream

  8. WeatherFaxInternetRetrieval_Misc.xml Bermuda, French Polynesia, Chile, South Africa

  9. WeatherFaxInternetRetrieval_LaMMA.xml Ligurian, Mediterranean, Adriatic, Ionian, Sardinia, Ionian, etc.

  10. WeatherFaxInternetRetrieval_Europe.xml German Weather DWD, ECMWF, GFS, UK MET, Arpege, Arome, all of Europe

  11. WeatherFaxInternetRetrieval_Aviation.xml Sat Images, Infra-red

  12. WeatherFaxInternetRetrieval_Australia.xml Australia BOM

Use of STRDATE

Date and Time Manipulation using DATE and STRDATE Functions https://www.ibm.com/support/pages/date-and-time-manipulation-using-date-and-strdate-functions

Format Specifier Description %8 ISO-8601 date format. Valid format is YYYYMMDD’T’HHMMSS'.'sssZ Note This date format cannot be combined with any other format specifier. %a Abbreviated weekday name. %A Full weekday name. %b Abbreviated month name. %B Full month name. %d Day of the month as a decimal number (01 - 31). %H Hour in 24-hour format (00 - 23). %I Hour in 12-hour format (01 - 12). %j Day of the year as a decimal number (001 - 366). %m Month as a decimal number (01 - 12). %M Minute as a decimal number (00 - 59). %S Second as a decimal number (00 - 59) %U Week of the year as a decimal number, with Sunday as the first day of the week (00 - 51). %w Weekday as a decimal number (0 - 6, with Sunday as "0"). %W Week of the year as a decimal number, with Monday as the first day of the week (00 - 51). %y Year without the century as a decimal number (00 - 99). %Y Year with the century as a decimal number. %% Percent sign.

For more examples and discussion about the use of strdate please see https://github.com/seandepagnier/weatherfax_pi/issues/58

Examples and Use

David Burch’s Blog has made some videos which help to explain how to update the world regional xmls and the coordinateset.xml file. How to update file souces for OpenCPN weatherfax plugin

Thanks to Sean for a great Plugin!