@momsfriendlydevco/bom

Tools to pull in, manipulate and cache Australian Bureau of Meteorology (BOM) Weather Radars.

Retrieving your local area ID.

Go to the BOM website and type in the approximate area name. The code will be listed to the left. For example "Wollongong" mid-range radar has the code IDR032 so supply the ID 032 to retrieve data from this radar.

Example

Create an animated Radar image for the Radar over Sydney:

var Bom = require('@momsfriendlydevco/bom');

new Bom()
	.set('id', '032')
	.set('composite.format', 'mp4')
	.composite(function(err, path) {
		console.log('MP4 video created at:', path);
	})

Debugging

This module uses the Debug NPM to output debugging information to the console. Simply set DEBUG=bom when running whatever upstream library this module is contained in to see debugging information.

API

BOM (class)

The main class instance.

Construct this with optional settings to initialize.

var bom = new Bom({id: '032'}); // Sydney

bom.settings (object)

Object used to store all settings for this instance. These can be set during the constructor, via calls to set(key, val) or directly in this object.

Supported settings:

Setting	Type	Default	Description
id	Number	032	The ID of the weather radar to use (see the README file for how to retrieve this
host	String	"ftp.bom.gov.au"	The FTP host to communicate with to retrieve data
framePath	String	"/anon/gen/radar"	The path on the FTP host where the radar frames are located
backgroundsPath	String	"/anon/gen/radar_transparencies"	The path on the FTP host where the background layers are located
cachePath	String	"${os.tmpdir()}/bom-cache"	Where to locally store cached resources
getThreads	Number	1	How many FTP GET operations to support at once
fetch	Object	See below	Options for fetching data during a call to refresh()
fetch.frames	Boolean	true	Whether to attempt to refresh frame data
fetch.backgrounds	Boolean	true	Whether to attempt to refresh background layer data
backgrounds	Object	{background:true,locations:true,topography:true}	An object specifying which background layers to fetch / render
clean	Object	See below	Options for cleaning resources
clean.olderThan	Number	60*60*24*1000 (24 hours)	The time (in milliseconds) from now which is used to expire resources
composite	Object	See below	Options for compositing an animated Radar file via composite()
composite.autoClean	Boolean	true	Automatically try to clean out expired radar images, disable if you are calling this manually
composite.autoRefresh	Boolean	true	Automatically try to refresh data, disable this if you are calling this manulally
composite.cache	Boolean	true	Attempt to provide the composite radar animation from a local resource instead of generating
composite.cacheFileExpiry	Number	60*60*100 (1 hour)	How long the cached version of the composite should be allowed before expiry
composite.cacheFile	Function or String	IDR{CODE}.composite.{EXT}	How to calculate the cache file name
composite.delay	Number	50	Default delay (in milliseconds) between frames when compositing
composite.format	String	gif	An ImageMagick compatible multi-image file format to render
composite.method	String	"path"	What to actually return from composite(). Can be "path", "buffer", "stream"
composite.removeAttribution	Boolean	false	Whether to remove the 15px header bar added by the feed. Only set this to true if you are attributing the BOM elsewhere
composite.arguments	Array	Complex, see source code	The operations to perform via ImageMagick to output the composite file

bom.set(key, value)

Convenience function to quickly set an option. Dotted or array notation are both supported.

bom
	.set('fetch.frames', true)
	.set(['composite', 'format'], 'mp4')
	.composite(()=> ...)

bom.refresh([options], callback)

Attempt to refresh BOM radar data from the FTP site.

The callback will be called as (err, {backgrounds, frames}).

bom.cached([options], callback)

Retrieve the files we have stored locally on disk. This operates the same as bom.refresh() and has the same return but does not connect to the FTP - only using local data.

bom.clean([options], callback)

Cleans out older radar images.

The callback is called as (err, arrayOfImagesRemoved).

bom.composite([options], callback)

Create a composite image based on the cached data from bom.refresh() This function creates a single GIF / MP4 / Any multi-image file which has a background + animated radar layers.

You can see a list of compatible multi-image files by running convert -list format and searching for any format with '+' in its Mode flags.

The callback is called as (err, output) where output is the format requested in bom.settings.composite.method which can be "path" (default), "buffer" or "stream".

bom.utils.nameToDate(path)

Translate a BOM filename into a JavaScript Date.