Module grib2 

GRIB edition 2, the World Meteorological Organization’s binary format for gridded weather: the fields NOAA’s NOMADS grib filter cuts from GFS and RAP, and whole GFS files.

A GRIB2 file is a run of messages. Each holds one or more fields: a grid (section 3), what the values are and at which level and time (section 4), how they are packed (section 5), which grid points have a value (section 6, the bitmap) and the packed values (section 7). parse reads the headers of every field and keeps the packed values borrowed, so reading a file costs memory in proportion to the number of fields, not their grids; Field::value unpacks one grid point, Field::values all of them. The layout is the WMO’s Manual on Codes, WMO-No. 306, Volume I.2, FM 92 GRIB edition 2, and its code and flag tables.

What is read, which covers what the grib filter serves from GFS and RAP, and NCEP’s whole GFS files:

section	templates read
3, grid	3.0 latitude/longitude; 3.30 Lambert conformal, on a sphere, tangent cone, north pole on the plane
4, product	4.0, a field at a level at one time; 4.8, the same over a time interval (one time range)
5, packing	5.0, simple packing; 5.2, complex packing; 5.3, complex packing with spatial differencing; 5.40, JPEG 2000, lossless, to 21 bits, as NCEP codes it
6, bitmap	none, one given, or the one before it in the message

Anything else is refused with Grib2Error::Unsupported, naming the template, never read wrongly.

Values. Simple packing stores each value as an integer X of a fixed number of bits, with a reference value R (a 32-bit float), a binary scale factor E and a decimal scale factor D shared by the field (WMO-No. 306, Regulation 92.9.4):

Y = (R + X · 2^E) / 10^D

evaluated in f64 with exact powers of two and ten. A field of 0 bits is R / 10^D at every point with a value. Signed integers in GRIB2 are sign and magnitude (the first bit is the sign), not two’s complement (Regulation 92.1.5).

Complex packing (5.2, 5.3) splits the values into groups, each with its own reference and width, and may pack differences between neighbouring values instead of the values; the integers it rebuilds unpack by the same regulation. ComplexPacking has the details. Its values can only be read in order, so Field::value reads the field up to the point asked for; Field::values_at reads several points in one pass.

JPEG 2000 (5.40) codes the integers X as a greyscale image in a JPEG 2000 codestream, decoded by hayro-jpeg2000; Jpeg2000Packing has the limits. The image is decoded whole each time values are read, so read a field’s values once with Field::values or Field::values_at.

Grids. Grid::point_deg gives a grid point’s latitude and longitude, and Grid::index_at the (fractional) grid indices of a place. On a Lambert conformal grid both use the spherical Lambert conformal conic projection of Snyder, Map Projections: A Working Manual, USGS Professional Paper 1395 (1987): eqs. 14-1, 14-2, 14-4, 15-1 and 15-2, and for the inverse 14-9 to 14-11 and 15-5, with a tangent cone’s n = sin φ₁ (the one-parallel case of eq. 15-3). Winds on such a grid may be given along the grid’s axes rather than east and north (flag table 3.3, bit 5, Grid::winds_grid_relative); Grid::earth_relative_wind turns them by the angle between the grid’s y axis and true north, θ = n (λ − λ₀).

Checked against: ecCodes 2.49.0, run as an outside decoder, on recorded GFS and RAP cuts (crates/hpr-net/tests/nomads.rs): every value, and every grid point’s latitude and longitude; on eight whole messages of a whole GFS file (crates/hpr-io/tests/grib2_gfs.rs); and, by a script run outside CI, on every value of that file, all 746,770,303 within 4.4e-16 of ecCodes’ (validation/oracles/grib2/gfs-whole-file.json); and on four RAP messages in JPEG 2000 (rap_messages_in_jpeg2000_decode_to_eccodes_values).

Structs

ComplexPacking

Complex packing’s parameters: data representation templates 5.2 and 5.3.

Field

One field of a GRIB2 file: its headers, with its bitmap and packed values borrowed from the file’s bytes.

Grid

A field’s grid: its size, its projection and how its points are ordered.

Jpeg2000Packing

JPEG 2000 packing’s parameters: data representation template 5.40.

Product

What a field holds, and at which level and time: product definition template 4.0.

ReferenceTime

When a field’s data starts: section 1’s reference time, in UTC as written.

SimplePacking

Simple packing’s parameters: data representation template 5.0.

SpatialDifferencing

Template 5.3’s spatial differencing.

Statistics

A statistic over a time interval: product definition template 4.8, with one time range.

Surface

A surface a field is on (code table 4.5), such as an isobaric level.

Enums

Earth

The figure of the Earth a grid is defined on (code table 3.2).

Grib2Error

Why a GRIB2 file was refused.

Packing

How a field’s values are packed: data representation template 5.0, 5.2, 5.3 or 5.40.

Projection

How a grid’s points map to the Earth.

Constants

MAX_JPEG2000_BITS

The most bits per value read: the 5/3 wavelet’s sums in hayro-jpeg2000’s f32 stay below 2^24, and so exact, for samples of at most 21 bits (see the module’s documentation).

MAX_JPEG2000_SIDE

hayro-jpeg2000 refuses an image wider or taller than this. NCEP codes a field with a bitmap as one row of its packed values, so such a field of more values is refused by name.

MAX_POINTS

The most grid points a field may have: 2²⁴, about 16.8 million. The largest common grids are well inside it (GFS at 0.25°, about 1.04 million; ECMWF at 0.1°, about 6.5 million). A field of 0 bits has no packed data to bound its grid, so this bounds what Field::values allocates: 16 bytes a point, up to 256 MiB for one field, whatever the file’s size. Field::value reads one point of a simple-packed field and allocates nothing.

Functions

parse

Reads every field of a GRIB2 file.