@weacast/grib2json

A command line utility that decodes GRIB2 files as JSON.

This utility uses the netCDF-Java GRIB decoder, part of the THREDDS project by University Corporation for Atmospheric Research/Unidata.

It has been embedded in a NPM package and provides the same features as a Node.js CLI or module.

Installation

This requires Java 8 to be installed on your system and the JAVA_HOME environment variable to be positioned and point to your local Java root directory.

Java CLI

git clone <this project>

The project contains a bin folder with the latest version. The bin folder contains a grib2json CLI script for Linux-based and Windows-based OS, you should add this folder to your PATH.

Node.js CLI

npm install -g @weacast/grib2json

Usage

As CLI

The grib2json CLI can be used similarly from the native OS CLI or from Node.

> grib2json --help (or node bin.js --help)
Usage: grib2json (or node bin.js) [options] <file>
  -V, --version                    output the version number
  -d, --data                       Print GRIB record data
  -c, --compact                    Enable compact Json formatting
  -fc, --filter.category <value>   Select records with this numeric category
  -fs, --filter.surface <value>    Select records with this numeric surface type
  -fp, --filter.parameter <value>  Select records with this numeric parameter
  -fv, --filter.value <value>      Select records with this numeric surface value
  -n, --names                      Print names of numeric codes
  -o, --output <file>              Output in a file instead of stdout
  -p, --precision <precision>      Limit precision in output file using the given number of digits after the decimal point (default: -1)
  -v, --verbose                    Enable logging to stdout
  -bs, --bufferSize <value>        Largest amount of data in bytes allowed on stdout or stderr
  -h, --help                       output usage information

For example, the following command outputs to stdout the records for parameter 2 (U-component_of_wind), with surface type 103 (Specified height level above ground), and surface value 10.0 meters from the GRIB2 file gfs.t18z.pgrbf00.2p5deg.grib2. Notice the optional inclusion of human-readable xyzName keys and the data array:

> grib2json --names --data --fp 2 --fs 103 --fv 10.0 gfs.t18z.pgrbf00.2p5deg.grib2

[
    {
        "header":{
            "discipline":0,
            "disciplineName":"Meteorological products",
            "gribEdition":2,
            "gribLength":27759,
            "center":7,
            "centerName":"US National Weather Service - NCEP(WMC)",
            "parameterNumber":2,
            "parameterNumberName":"U-component_of_wind",
            "parameterUnit":"m.s-1",
            "surface1Type":103,
            "surface1TypeName":"Specified height level above ground",
            "surface1Value":10.0,
            ...
        },
        "data":[
            -2.12,
            -2.27,
            -2.41,
            ...
        ]
    }
]

Using Node.js

The CLI version has in this case an additional option --bufferSize <value>, or -bs <value> in short, specifying the largest amount of data in bytes allowed on stdout (defaults to 8 MB). Indeed, because in this case the Java CLI version is called from the Node.js process using child_process, output is retrieved from stdout.

Using the Docker container

When using the tool as a Docker container the arguments to the CLI have to be provided through the ARGS environment variable, with the data volume required to make input accessible within the container and get output file back the previous example becomes:

docker run --name grib2json --rm -v /mnt/data:/usr/local/data -e "ARGS=--names --data --fp 2 --fs 103 --fv 10.0 --output /usr/local/data/output.json /usr/local/data/gfs.t18z.pgrbf00.2p5deg.grib2" weacast/grib2json

As module

Just call the grib2json default export function in your code:

const grib2json = require('@weacast/grib2json')
// First arg is the input file path, second arg is CLI options as JS object
grib2json('gfs.grib', {
  data: true,
  output: 'output.json'
})
.then(function (json) {
  // Do whatever with the json data, same format as output of the CLI
})

Like with the CLI version you can use the additional bufferSize option to specify the largest amount of data in bytes allowed on stdout (defaults to 8 MB), notably if you deal with large files. You can also process data only in-memory without writing any file by omitting the output:

grib2json('gfs.grib', {
  data: true,
  bufferSize: 128 * 1024 * 1024 // 128 MB
})
.then(function (json) {
  // Do whatever with the json data, same format as output of the CLI
})

Warning: the precision option only applies when writing an output, in-memory data will remain floating point values without any precision loss

Build

This requires Maven to be installed on your system.

git clone <this project>
mvn package

This creates a .tar.gz in the target directory. Unzip and untar the package in a location of choice. The package contains a bin/lib folders that should be at the same hierarchical level (e.g. in /usr). The lib folder contains all dependent libraries and the execution script set it as current LIB_PATH before executing the main jar.

A single grib2json.jar file is also generated using the maven plugin for one-jar. This is the one used to provide the CLI as a stand-alone archive in the bin directory of the project. It is up to you to pick the one you prefer.

A Docker file is also provided to get the tool ready to work within a container, from the project root run:

docker build -t weacast/grib2json .