1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
<head>
<title>CODA GRIB Mapping Description</title>
<link rel="stylesheet" href="../css/codadoc.css" type="text/css" />
</head>
<body>
<div class="main">
<h1>CODA GRIB Mapping Description</h1>
<p>CODA provides access to GRIB-1 and GRIB-2 formatted data by creating a view on the GRIB files using the CODA <a href="codadef-format.html">data types</a>. Below we will describe how CODA maps the GRIB1/GRIB2 product structure to one that is based on the CODA data types. We assume you already have a decent understanding of the GRIB (edition 1 and 2) format and its details.</p>
<p>A file can contain one or more GRIB <i>messages</i>. CODA only supports files where GRIB messages are stored without any padding between the messages and where the file does not contain any non-GRIB header or footer information in the file. A file can contain a mix of messages with different GRIB edition numbers.</p>
<p>Since a file consists of a list of messages the root of the product is mapped to an <i>array</i> of <i>union</i> with each message being mapped to a <i>union</i>. The fields in the union reflect the edition number of the GRIB message and are called <i>grib1</i> and <i>grib2</i> (only one of the fields will be available, depending on the edition number of the GRIB message). The <i>grib1</i> and <i>grib2</i> fields contain <i>record</i> types for a GRIB1 and GRIB2 message respectively. The mapping for each is explained below.</p>
<p>CODA will try to provide as direct a mapping to the underlying data as possible. This means that code table indices will just be provided as indices and not be interpreted. You will have to consult the appropriate WMO code tables in order to interpret the data. The reason for this design choice was to eliminate as much as possible the dependency of CODA on the WMO tables. For certain structural information (such as the contents of the Grid Description Section or Product Definition Section) table information has been hard-coded in CODA.</p>
<p>There are a few exceptions to the 'direct mapping' approach. One is that CODA will already perform the decoding of the parameter values. The bit-packed data is already converted back to floating point values using the scale factors and reference value as described by the GRIB standard. The scale factors and reference values are still made accessible as fields in the GRIB message record, but they have the <i>hidden</i> property, since you should not need them to interpret the values that CODA will give back.</p>
<p>CODA will also perform the decoding of bitmap packed data (using the Bit Map Section). The data available in data/values[] will thus always contain the full grid, where <i>missing</i> grid points are given the 'referenceValue' as value.</p>
<p>In addition, for GRIB1, any IBM floating point values will be converted to IEEE754 floating point values.</p>
<p>CODA currently only supports to most common storage mechanism of GRIB which is the simple packing form. Data that is stored using complex packing or jpeg/png images is not supported. Also, CODA currently only supports grid definitions that use a lat/lon or Gaussian grid. Other grids, including Spherical Harmonic data, are currently not supported. If an unsupported feature is encountered, CODA will abort opening the product and return with an error.</p>
<h2>GRIB1</h2>
<p>A GRIB1 message consists of the following sections:</p>
<ul>
<li>(0) Indicator Section</li>
<li>(1) Product Definition Section (PDS)</li>
<li>(2) Grid Description Section (GDS) - optional</li>
<li>(3) Bit Map Section (BMS) - optional</li>
<li>(4) Binary Data Section (BDS)</li>
<li>(5) '7777' (ASCII Characters)</li>
</ul>
<p>The contents of the PDS are mapped directly as fields in the message <i>record</i>, but for the GDS and BDS sections separate sub-records are used. The Indicator, BMS, and '7777' sections are not mapped.</p>
<p>For the naming of fields CODA tries to stay as close as possible to the naming scheme that is used by the ECMWF GRIB API software.</p>
<p>The following table gives the list of parameters that are available via CODA for a GRIB1 message:</p>
<table class="fancy">
<tr><th>path to variable</th><th>type class</th><th>read type</th><th>notes</th></tr>
<tr><td>/[]/grib1/editionNumber</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/table2Version</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/centre</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/generatingProcessIdentifier</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/gridDefinition</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/indicatorOfParameter</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/indicatorOfTypeOfLevel</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/level</td><td>integer</td><td>uint16</td><td></td></tr>
<tr><td>/[]/grib1/yearOfCentury</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/month</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/day</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/hour</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/minute</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/unitOfTimeRange</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/P1</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/P2</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/timeRangeIndicator</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/numberIncludedInAverage</td><td>integer</td><td>uint16</td><td></td></tr>
<tr><td>/[]/grib1/numberMissingFromAveragesOrAccumulations</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/centuryOfReferenceTimeOfData</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/decimalScaleFactor</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/subCentre</td><td>integer</td><td>int16</td><td>(hidden field)</td></tr>
<tr><td>/[]/grib1/local</td><td>raw</td><td>bytes</td><td>optional; the originating center specific data at the end of the PDS is made available as raw data via this field if it is available</td></tr>
<tr><td>/[]/grib1/grid/numberOfVerticalCoordinateValues</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/grid/dataRepresentationType</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/grid/Ni</td><td>integer</td><td>uint16</td><td></td></tr>
<tr><td>/[]/grib1/grid/Nj</td><td>integer</td><td>uint16</td><td></td></tr>
<tr><td>/[]/grib1/grid/latitudeOfFirstGridPoint</td><td>integer</td><td>int32</td><td></td></tr>
<tr><td>/[]/grib1/grid/longitudeOfFirstGridPoint</td><td>integer</td><td>int32</td><td></td></tr>
<tr><td>/[]/grib1/grid/resolutionAndComponentFlags</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/grid/latitudeOfLastGridPoint</td><td>integer</td><td>int32</td><td></td></tr>
<tr><td>/[]/grib1/grid/longitudeOfLastGridPoint</td><td>integer</td><td>int32</td><td></td></tr>
<tr><td>/[]/grib1/grid/iDirectionIncrement</td><td>integer</td><td>int16</td><td></td></tr>
<tr><td>/[]/grib1/grid/jDirectionIncrement</td><td>integer</td><td>int16</td><td>optional</td></tr>
<tr><td>/[]/grib1/grid/N</td><td>integer</td><td>int16</td><td>optional</td></tr>
<tr><td>/[]/grib1/grid/scanningMode</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib1/grid/coordinateValues[]</td><td>real</td><td>float</td><td>optional</td></tr>
<tr><td>/[]/grib1/grid/listOfNumbers[]</td><td>integer</td><td>uint16</td><td>optional</td></tr>
<tr><td>/[]/grib1/data/bitsPerValue</td><td>integer</td><td>uint8</td><td>(hidden field)</td></tr>
<tr><td>/[]/grib1/data/binaryScaleFactor</td><td>integer</td><td>int16</td><td>(hidden field)</td></tr>
<tr><td>/[]/grib1/data/referenceValue</td><td>real</td><td>float</td><td>(hidden field)</td></tr>
<tr><td>/[]/grib1/data/values[]</td><td>real</td><td>float</td><td></td></tr>
</table>
<h2>GRIB2</h2>
<p>A GRIB2 message consists of the following sections:</p>
<ul>
<li>(0) Indicator Section</li>
<li>(1) Identification Section</li>
<li>(2) Local Use Section - optional</li>
<li>(3) Grid Definition Section</li>
<li>(4) Product Definition Section</li>
<li>(5) Data Representation Section</li>
<li>(6) Bit-Map Section</li>
<li>(7) Data Section</li>
<li>(8) End Section</li>
</ul>
<p>Within a message, sequences 3-7, 4-7, and/or 5-7 can be repeated several times.</p>
<p>The contents of the Identification Section are mapped directly as fields in the message <i>record</i>. For the Local Use, Grid Definition, and Data Sections special 'local', 'grid', and 'data' fields are available, with each being an array of the contents of each occurrence of the section. Each 'data' record will contain a 0-based index into the 'grid' array to reference the applicable grid for the parameter. Similary, for each 'grid' record a 0-based index into the 'local' array will be available. The visible content of the Product Definition and Data Representation Section are available in the 'data' record of the associated Data Section (Product Definition Section information can thus end up appearing replicated).</p>
<p>As for GRIB1, for the naming of fields, CODA tries to stay as close as possible to the naming scheme that is used by the ECMWF GRIB API software.</p>
<p>The following table gives the list of parameters that are available via CODA for a GRIB2 message:</p>
<table class="fancy">
<tr><th>path to variable</th><th>type class</th><th>read type</th><th>notes</th></tr>
<tr><td>/[]/grib2/editionNumber</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/discipline</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/centre</td><td>integer</td><td>uint16</td><td></td></tr>
<tr><td>/[]/grib2/subCentre</td><td>integer</td><td>uint16</td><td></td></tr>
<tr><td>/[]/grib2/masterTablesVersion</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/localTablesVersion</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/significanceOfReferenceTime</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/year</td><td>integer</td><td>uint16</td><td></td></tr>
<tr><td>/[]/grib2/month</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/day</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/hour</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/minute</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/second</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/productionStatusOfProcessedData</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/typeOfProcessedData</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/local[]</td><td>raw</td><td>bytes</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/localRecordIndex</td><td>integer</td><td>int32</td><td>index into /[]/local[] to find associated local use data. Will be -1 if no local use data is available</td></tr>
<tr><td>/[]/grib2/grid[]/sourceOfGridDefinition</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/numberOfDataPoints</td><td>integer</td><td>uint32</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/interpretationOfListOfNumbers</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/gridDefinitionTemplateNumber</td><td>integer</td><td>uint16</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/shapeOfTheEarth</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/scaleFactorOfRadiusOfSphericalEarth</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/scaledValueOfRadiusOfSphericalEarth</td><td>integer</td><td>uint32</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/scaleFactorOfEarthMajorAxis</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/scaledValueOfEarthMajorAxis</td><td>integer</td><td>uint32</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/scaleFactorOfEarthMinorAxis</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/scaledValueOfEarthMinorAxis</td><td>integer</td><td>uint32</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/Ni</td><td>integer</td><td>uint32</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/Nj</td><td>integer</td><td>uint32</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/basicAngleOfTheInitialProductionDomain</td><td>integer</td><td>uint32</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/subdivisionsOfBasicAngle</td><td>integer</td><td>uint32</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/latitudeOfFirstGridPoint</td><td>integer</td><td>int32</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/longitudeOfFirstGridPoint</td><td>integer</td><td>int32</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/resolutionAndComponentFlags</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/latitudeOfLastGridPoint</td><td>integer</td><td>int32</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/longitudeOfLastGridPoint</td><td>integer</td><td>int32</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/iDirectionIncrement</td><td>integer</td><td>uint32</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/jDirectionIncrement</td><td>integer</td><td>uint32</td><td>optional</td></tr>
<tr><td>/[]/grib2/grid[]/N</td><td>integer</td><td>uint32</td><td>optional</td></tr>
<tr><td>/[]/grib2/grid[]/scanningMode</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/grid[]/listOfNumbers</td><td>integer</td><td>uint32</td><td>optional</td></tr>
<tr><td>/[]/grib2/data[]/gridRecordIndex</td><td>integer</td><td>uint32</td><td>index into /[]/grid[] to find associated grid definition data</td></tr>
<tr><td>/[]/grib2/data[]/parameterCategory</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/data[]/parameterNumber</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/data[]/constituentType</td><td>integer</td><td>uint16</td><td>optional</td></tr>
<tr><td>/[]/grib2/data[]/typeOfGeneratingProcess</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/data[]/backgroundProcess</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/data[]/generatingProcessIdentifier</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/data[]/hoursAfterDataCutoff</td><td>integer</td><td>uint16</td><td></td></tr>
<tr><td>/[]/grib2/data[]/minutesAfterDataCutoff</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/data[]/indicatorOfUnitOfTimeRange</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/data[]/forecastTime</td><td>integer</td><td>uint32</td><td></td></tr>
<tr><td>/[]/grib2/data[]/typeOfFirstFixedSurface</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/data[]/firstFixedSurface</td><td>real</td><td>double</td><td></td></tr>
<tr><td>/[]/grib2/data[]/typeOfSecondFixedSurface</td><td>integer</td><td>uint8</td><td></td></tr>
<tr><td>/[]/grib2/data[]/secondFixedSurface</td><td>real</td><td>double</td><td></td></tr>
<tr><td>/[]/grib2/data[]/coordinateValues[]</td><td>real</td><td>float</td><td>optional</td></tr>
<tr><td>/[]/grib2/data[]/bitsPerValue</td><td>integer</td><td>uint8</td><td>(hidden field)</td></tr>
<tr><td>/[]/grib2/data[]/decimalScaleFactor</td><td>integer</td><td>int16</td><td>(hidden field)</td></tr>
<tr><td>/[]/grib2/data[]/binaryScaleFactor</td><td>integer</td><td>int16</td><td>(hidden field)</td></tr>
<tr><td>/[]/grib2/data[]/referenceValue</td><td>real</td><td>float</td><td>(hidden field)</td></tr>
<tr><td>/[]/grib2/data[]/values[]</td><td>real</td><td>float</td><td></td></tr>
</table>
<div class="footer">
<hr />
<p>Copyright © 2007-2022 <b>s<span class="soft-red">[</span>&<span class="soft-red">]</span>t</b>, The Netherlands.</p>
</div>
</div>
</body>
</html>
|
