1.. _raster.grib: 2 3================================================================================ 4GRIB -- WMO General Regularly-distributed Information in Binary form 5================================================================================ 6 7.. shortname:: GRIB 8 9.. built_in_by_default:: 10 11GDAL supports GRIB1 (reading) and GRIB2 (reading and writing) format 12raster data, with support for common coordinate system, georeferencing 13and other metadata. GRIB format is commonly used for distribution of 14Meteorological information, and is propagated by the World 15Meteorological Organization. 16 17The GDAL GRIB driver is based on a modified version of the degrib 18application which is written primarily by Arthur Taylor of NOAA NWS NDFD 19(MDL). The degrib application (and the GDAL GRIB driver) are built on 20the g2clib grib decoding library written primarily by John Huddleston of 21NOAA NWS NCEP. 22 23There are several encoding schemes for raster data in GRIB format. Most 24common ones should be supported including PNG encoding. JPEG2000 encoded 25GRIB files will generally be supported if GDAL is also built with 26JPEG2000 support via one of the GDAL JPEG2000 drivers. 27 28GRIB files may a be represented in GDAL as having many bands, with some 29sets of bands representing a time sequence. GRIB bands are represented 30as Float64 (double precision floating point) regardless of the actual 31values. GRIB metadata is captured as per-band metadata and used to set 32band descriptions, similar to this: 33 34:: 35 36 Description = 100000[Pa] ISBL="Isobaric surface" 37 GRIB_UNIT=[gpm] 38 GRIB_COMMENT=Geopotential height [gpm] 39 GRIB_ELEMENT=HGT 40 GRIB_SHORT_NAME=100000-ISBL 41 GRIB_REF_TIME= 1201100400 sec UTC 42 GRIB_VALID_TIME= 1201104000 sec UTC 43 GRIB_FORECAST_SECONDS=3600 sec 44 45GRIB2 files may also include an extract of other metadata, such as the 46`identification 47section <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_sect1.shtml>`__, 48`product 49definition <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_sect4.shtml>`__ 50template number (GRIB_PDS_PDTN, octet 8-9), and the product definition 51template values (GRIB_PDS_TEMPLATE_NUMBERS, octet 10+) as metadata like 52this: 53 54:: 55 56 GRIB_DISCIPLINE=0(Meteorological) 57 GRIB_IDS=CENTER=7(US-NCEP) SUBCENTER=0 MASTER_TABLE=8 LOCAL_TABLE=1 SIGNF_REF_TIME=1(Start_of_Forecast) REF_TIME=2017-10-20T06:00:00Z PROD_STATUS=0(Operational) TYPE=1(Forecast) 58 GRIB_PDS_PDTN=32 59 GRIB_PDS_TEMPLATE_NUMBERS=5 7 2 0 0 0 0 0 1 0 0 0 0 1 0 31 1 29 67 140 2 0 0 238 217 60 GRIB_PDS_TEMPLATE_ASSEMBLED_VALUES=5 7 2 0 0 0 0 1 0 1 31 285 17292 2 61145 61 62GRIB_DISCIPLINE was added in GDAL 2.3.0 and is the 63`Discipline <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table0-0.shtml>`__ 64field of the Section 0 of the message. 65 66GRIB_IDS was added in GDAL 2.3.0 and is the `identification 67section <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table0-0.shtml>`__ 68/ Section 1 of the message. 69 70GRIB_PDS_TEMPLATE_ASSEMBLED_VALUES was added in GDAL 2.3.0, and use 71template definitions to assemble several bytes that make a template item 72into a 16 or 32 bit signed/unsigned integers, whereas 73GRIB_PDS_TEMPLATE_NUMBERS expose raw bytes 74 75Driver capabilities 76------------------- 77 78.. supports_georeferencing:: 79 80.. supports_virtualio:: 81 82Configuration options 83--------------------- 84 85This paragraph lists the configuration options that can be set to alter 86the default behavior of the GRIB driver. 87 88- GRIB_NORMALIZE_UNITS=YES/NO : Default to YES. Can be 89 set to NO to avoid gdal to normalize units to metric. By default 90 (GRIB_NORMALIZE_UNITS=YES), temperatures are reported in degree 91 Celsius (°C). With GRIB_NORMALIZE_UNITS=NO, they are reported in 92 degree Kelvin (°K). 93 94GRIB2 write support 95------------------- 96 97GRIB2 write support is available since GDAL 2.3.0, through the 98CreateCopy() / gdal_translate interface. 99 100Each band of the input dataset is translated as a GRIB2 message, and all 101of them are concatenated in a single file, conforming to the usual 102practice. 103 104The input dataset must be georeferenced, and the supported projections 105are: Geographic Longitude/Latitude, Mercator 1SP/2SP, Transverse 106Mercator, Polar Stereographic, Lambert Conformal Conic 1SP/2SP, Albers 107Conic Equal Area and Lambert Azimuthal Equal Area. 108 109A number of creation options are available as detailed in below 110sections. Those creation options are valid for all bands. But it is 111possible to override those global settings in a per-band way, by 112defining creation options that use the same key and are prefixed by 113BAND_X\_ where X is the band number between 1 and the total number of 114bands. For example BAND_1_PDS_PDTN 115 116Product identification and definition 117~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 118 119Users are strongly advised to provide necessary information to 120appropriately fill the `Section 0 / 121"Indicator" <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_sect0.shtml>`__, 122`Section 1 / "Identification 123section" <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_sect1.shtml>`__ 124and `Section 4 / "Product definition 125section" <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_sect4.shtml>`__ 126with the following creation options. Otherwise, GDAL will fill with 127default values, but readers might have trouble exploiting GRIB2 datasets 128generating with those defaults. 129 130- **DISCIPLINE**\ =integer: sets the Discipline field of Section 0. 131 Valid values are given by `Table 132 0.0 <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table0-0.shtml>`__: 133 134 - 0: Meteorological Products. Default value 135 - 1: Hydrological Products 136 - 2: Land Surface Products 137 - 3, 4: Space Products 138 - 10: Oceanographic Product 139 140- **IDS**\ =string. String with different elements to fill the fields 141 of the Section 1 / Identification section. The value of that string 142 will typically be retrieved from the GRIB_IDS metadata item of an 143 existing GRIB product. For example "IDS=CENTER=7(US-NCEP) SUBCENTER=0 144 MASTER_TABLE=8 SIGNF_REF_TIME=1(Start_of_Forecast) 145 REF_TIME=2017-10-20T06:00:00Z PROD_STATUS=0(Operational) 146 TYPE=1(Forecast)". More formally, the format of the string is a list 147 of KEY=VALUE items, with space separator. The accepted keys are 148 CENTER, SUBCENTER, MASTER_TABLE, SIGNF_REF_TIME, REF_TIME, 149 PROD_STATUS and TYPE. Only the numerical part of the value is taken 150 into account (the precision between parenthesis will be ignored). It 151 is possible to use both this IDS creation option and a specific 152 IDS_xxx creation option that will override the potential 153 corresponding xxx key of IDS. For example with the previous example, 154 if both "IDS=CENTER=7(US-NCEP)..." and "IDS_CENTER=8" are define, the 155 actual value used with be 8. 156- **IDS_CENTER**\ =integer. Identification of originating/generating 157 center, according to `Table 158 0 <http://www.nco.ncep.noaa.gov/pmb/docs/on388/table0.html>`__. 159 Defaults to 255/Missing 160- **IDS_SUBCENTER**\ =integer. Identification of originating/generating 161 center, according to `Table 162 C <http://www.nco.ncep.noaa.gov/pmb/docs/on388/tablec.html>`__. 163 Defaults to 65535/Missing 164- **IDS_MASTER_TABLE**\ =integer. GRIB master tables version number, 165 according to `Table 166 1.0 <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table1-0.shtml>`__. 167 Defaults to 2 168- **IDS_SIGNF_REF_TIME**\ =integer. Significance of reference time, 169 according to `Table 170 1.2 <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table1-2.shtml>`__. 171 Defaults to 0/Analysis 172- **IDS_REF_TIME**\ =datetime as YYYY-MM-DD[THH:MM:SSZ]. Reference 173 time. Defaults to 1970-01-01T00:00:00Z 174- **IDS_PROD_STATUS**\ =integer. Production status of processed data, 175 according to `Table 176 1.3 <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table1-3.shtml>`__. 177 Defaults to 255/Missing 178- **IDS_TYPE**\ =integer. Type of processed data, according to `Table 179 1.4 <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table1-4.shtml>`__. 180 Defaults to 255/Missing 181- **PDS_PDTN**\ =integer. Product definition template number, according 182 to `Table 183 4.0 <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table4-0.shtml>`__. 184 Defaults to 0/Analysis or forecast at a horizontal level or in a 185 horizontal layer at a point in time. If this default template number 186 is used, and none of PDS_TEMPLATE_NUMBERS or 187 PDS_TEMPLATE_ASSEMBLED_VALUES is specified, then a default template 188 definition is also used, with most fields set to Missing. 189- **PDS_TEMPLATE_NUMBERS**\ =string. Product definition template raw 190 numbers. This is a list of byte values (between 0 and 255 each), 191 space separated. The number of values and their semantics depends on 192 the template number specified by PDS_PDTN, and you have to consult 193 the template structures pointed by `Table 194 4.0 <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table4-0.shtml>`__. 195 It might be easier to use the GRIB_PDS_TEMPLATE_NUMBERS reported by 196 existing GRIB2 products as the value for this item. If the template 197 structure is known by the reading side of the driver, an effort to 198 validate the number of template numbers against the template 199 structure is made (with warnings if more elements than needed are 200 specified, and error if less are specified). It is also possible to 201 define a template that is not or partially implemented by the reading 202 side of the driver. 203- **PDS_TEMPLATE_ASSEMBLED_VALUES**\ =string. Product definition 204 template assembled values. This is a list of values (with the range 205 of signed/unsigned 1, 2 or 4-byte wide integers, depending on the 206 item), space separated. The number of values and their semantics 207 depends on the template number specified by PDS_PDTN, and you have to 208 consult the template structures pointed by `Table 209 4.0 <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table4-0.shtml>`__. 210 It might be easier to use the GRIB_PDS_TEMPLATE_ASSEMBLED_VALUES 211 reported by existing GRIB2 products as the value for this item. 212 PDS_TEMPLATE_NUMBERS and PDS_TEMPLATE_ASSEMBLED_VALUES are exclusive. 213 To use this creation option, the template structure must be known by 214 the reading side of the driver. 215 216Data encoding 217~~~~~~~~~~~~~ 218 219In GRIB2, a number of data encoding schemes exist (see `Section 5 / 220"Data representation 221section" <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_sect5.shtml>`__). 222By default, GDAL will select an appropriate data encoding that will 223preserve the range of input data. with the **DATA_ENCODING**, **NBITS**, 224**DECIMAL_SCALE_FACTOR**, **JPEG200_DRIVER**, **COMPRESSION_RATIO** and 225**SPATIAL_DIFFERENCING_ORDER** creation options. 226 227Users can override those defaults with the following creation options 228are: 229 230- **DATA_ENCODING**\ =AUTO / SIMPLE_PACKING / COMPLEX_PACKING / 231 IEEE_FLOATING_POINT / PNG / JPEG2000: Choice of the `Data 232 representation template number. Defaults to 233 AUTO. <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_table5-0.shtml>`__ 234 235 - In AUTO mode, COMPLEX_PACKING is selected if input band has a 236 nodata value. Otherwise if input band datatype is Float32 or 237 Float64, IEEE_FLOATING_POINT is selected. Otherwise SIMPLE_PACKING 238 is selected. 239 - `SIMPLE_PACKING <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-0.shtml>`__: 240 use integer representation internally, with offset and decimal 241 and/or binary scaling. So can be used for any datatype. 242 - COMPLEX_PACKING: evolution of SIMPLE_PACKING with nodata handling. 243 By default, a `non-spatial differencing encoding is 244 used <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-2.shtml>`__, 245 but if SPATIAL_DIFFERENCING_ORDER=1 or 2, `complex packing with 246 spatial 247 differencing <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-3.shtml>`__ 248 is used 249 - `IEEE_FLOATING_POINT <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-4.shtml>`__: 250 store values as IEEE-754 single or double precision numbers. 251 - `PNG <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-41.shtml>`__: 252 uses the same preparation steps as SIMPLE_PACKING but with PNG 253 encoding of the integer values. 254 - `JPEG2000 <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/grib2_temp5-40.shtml>`__: 255 uses the same preparation steps as SIMPLE_PACKING but with 256 JPEG2000 encoding of the integer values. 257 258- **NBITS**\ =integer between 1 to 31. Bit width for each sample value. 259 Might be only loosely honored by some DATA_ENCODING. If not 260 specified, the bit width is computed automatically from the range of 261 input values for integral data types, or default to 8 for 262 Float32/Float64. 263- **DECIMAL_SCALE_FACTOR**\ =integer_value. Input values are multiplied 264 by 10^DECIMAL_SCALE_FACTOR before integer encoding (and automatically 265 divised by this value at decoding, so this only affect precision). 266 For example, if the type of the data is a temperature, with floating 267 point data type, DECIMAL_SCALE_FACTOR=1 can be used to specify that 268 the data has a precision of 1/10 of degree. The default is 0 (no 269 premultiplication) 270- **SPATIAL_DIFFERENCING_ORDER**\ =0/1/2. Only used for 271 COMPLEX_PACKING. Defines the order of the spatial differencing. 0 272 means that the values are encoded independently, 1 means that the 273 difference of consecutive values is encoded and 2 means that the 274 difference of the difference of consecutive values is encoded. 275 Defaults to 0 276- **COMPRESSION_RATIO**\ =integer_value between 1 and 100. Defaults to 277 1 for lossless JPEG2000 encoding. Only used for JPEG2000 encoding. If 278 a value greater than 1 is specified, lossy JPEG2000 compression is 279 used. The value indicates the desired compression factor with 280 respected to uncompressed data. For example a value of 10 means that 281 the desired JPEG2000 codestream should be 10 times smaller than the 282 corresponding uncompressed file (with NBITS bits per pixel). 283- **JPEG2000_DRIVER**\ =JP2KAK/JP2OPENJPEG/JPEG2000/JP2ECW (possible 284 values depend on the actually available JPEG2000 driver in the GDAL 285 build). To specify which JPEG2000 driver should be used. If not 286 specified, drivers are searched in the order given in the 287 enumeration. 288 289Data units 290~~~~~~~~~~ 291 292Internally GRIB stores values in the units of the international system 293(ie Metric system). So temperatures must be stored as Kelvin degrees. 294But on the reading side of the driver, fields with temperatures are 295exposed in Celsius degrees (unless the GRIB_NORMALIZE_UNITS 296configuration option is set to NO). For consistency, the writing side of 297the driver also assumed that temperature (detected if the first value of 298a product definition template, ie the *Parameter category* is 2990=Temperature) values in the input dataset will be in Celsius degrees, 300and will automatically offset them to Kelvin degrees. It is possible to 301control that behavior by setting the **INPUT_UNIT** creation option to 302C (for Celsius) or K (for Kelvin). The default is C. 303 304GRIB2 to GRIB2 conversions 305~~~~~~~~~~~~~~~~~~~~~~~~~~ 306 307If GRIB2 to GRIB2 translation is done with gdal_translate (or 308CreateCopy()), the GRIB_DISCIPLINE, GRIB_IDS, GRIB_PDS_PDTN and 309GRIB_PDS_TEMPLATE_NUMBERS metadata items of the bands of the source 310dataset are used by default (unless creation options override them). 311 312DECIMAL_SCALE_FACTOR and NBITS will also be attempted to be retrieved 313from the GRIB special metadata domain. 314 315Examples 316~~~~~~~~ 317 318:: 319 320 gdal_translate in.tif out.grb2 -of GRIB \ 321 -co "IDS=CENTER=8(US-NWSTG) SIGNF_REF_TIME=1(Start_of_Forecast) REF_TIME=2008-02-21T17:00:00Z PROD_STATUS=0(Operational) TYPE=1(Forecast)" \ 322 -co "PDS_PDTN=8" \ 323 -co "PDS_TEMPLATE_ASSEMBLED_VALUES=0 5 2 0 0 255 255 1 43 1 0 0 255 -1 -2147483647 2008 2 23 12 0 0 1 0 3 255 1 12 1 0" 324 325See Also: 326--------- 327 328- `NOAA NWS NDFD "degrib" GRIB2 329 Decoder <https://www.weather.gov/mdl/degrib_archive>`__ 330- `NOAA NWS NCEP g2clib grib decoding 331 library <http://www.nco.ncep.noaa.gov/pmb/codes/GRIB2/>`__ 332- `WMO GRIB1 Format 333 Documents <http://www.wmo.int/pages/prog/www/WDM/Guides/Guide-binary-2.html>`__ 334- `NCEP WMO GRIB2 335 Documentation <http://www.nco.ncep.noaa.gov/pmb/docs/grib2/grib2_doc/>`__ 336 337Credits 338------- 339 340Support for GRIB2 write capabilities has been funded by Meteorological 341Service of Canada. 342