@momsfriendlydevco/bom

@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:

``javascript
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.

`javascript
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 | 606024*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 | 6060100 (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.

`javascript
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.