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.
Links
-
Maintenance Source: https://github.com/rgleason/weatherfax_pi
-
Release: Windows Releases
-
Download: https://opencpn.org/OpenCPN/plugins/weatherfax.html
-
Forum: http://www.cruisersforum.com/forums/f134/weatherfax-97533.html
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.
-
In OpenCPN Click Tools-Options-Plugins
-
First "Update" the master plugins catalog.
-
Select the Weatherfax entry and "Install" the plugin.
-
In the list of installed plugins "Enable" the Weatherfax plugin and "Apply".
-
Use “Preferences” to set your preferences (should be self-explanatory). Then “Apply.
-
After successful installation, the plugin should be available in the plugins tab of your OpenCPN options dialog box.
-
Then close Options and the Weatherfax Icon should appear in the Toolbar.
-
Then open it and explore the top menus.
-
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.
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.
Lat 42 Long -70 –> Servers: Noaa —> Regions: Atlantic —→ Select Contents —→ Retrieve
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.
The plugin data directory contains an WeatherFaxInternetRetrieval.xml file that has database for meterological sites. The “Internet Retrieval” Option uses this schedule.
Aviation Americas Forecast retrieved via the internet.
Passage Weather Atlantic 012 Wind via internet.
Bermuda 3 day via internet.
NOAA Atlantic 24hr 500mb via internet.
NOAA Atlantic 24hr Surface via internet.
Passage Weather New England Wind 012
Passage Weather Nova Scotia Wind 021
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.
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
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.
Weather Sources - David Burch Navigation Blog
-
How to Load Weather Maps into OpenCPN — The Hard Way! - Blog 2016
-
Satellite Cloud Images - Underway Sources - Blog 2018 ASCAT Grib (low orbit) and GOES (high orbit)
-
[Weather Maps—Where To Get Them and What We Get? - Blog 2016
-
High Seas Forecasts and Tropical Cyclone Alerts by Email Request - Blog 2015 Metarea for Saildocs.
Weatherfax Image File Sources
FTP Websites
FTP WeatherFax Most recent synoptic time, or near.
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”
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.
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
File Export as KAP, File Open KAP
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.
-
Remove the %localappdata%/opencpn/plugins/weatherfax/data files Use Options > Plugins > Uninstall the plugin.
-
Remove the local user directory data, in particular coordinateSets.xml Manually remove this directory "C:\ProgramData\opencpn\plugins\weatherfax" or empty it.
-
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
-
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.
-
WeatherfaxInternetRetrieval.xml is dependent on many MET website services worldwide, and users who contribute xml files.
-
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)
-
WeatherFaxInternetRetrieval_PWx_Pacific.xml Passageweather Pacific
-
WeatherFaxInternetRetrieval_PWx_India.xml Passageweather India
-
WeatherFaxInternetRetrieval_PWx_Euro_Atl.xml Passageweather European
-
WeatherFaxInternetRetrieval_PWx_Amer_Atl.xml Passageweather American Atlantic
-
WeatherFaxInternetRetrieval_NOAA_OPC.xml NOAA Ocean Prediction Center
-
WeatherFaxInternetRetrieval_NOAA.xml NOAA
-
WeatherFaxInternetRetrieval_Navy.xml Navy Gulf Stream
-
WeatherFaxInternetRetrieval_Misc.xml Bermuda, French Polynesia, Chile, South Africa
-
WeatherFaxInternetRetrieval_LaMMA.xml Ligurian, Mediterranean, Adriatic, Ionian, Sardinia, Ionian, etc.
-
WeatherFaxInternetRetrieval_Europe.xml German Weather DWD, ECMWF, GFS, UK MET, Arpege, Arome, all of Europe
-
WeatherFaxInternetRetrieval_Aviation.xml Sat Images, Infra-red
-
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
Download the IBM White Paper June 26 2009 https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/strdate-wstrdate?view=msvc-170
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!