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
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!--Converted with LaTeX2HTML 99.2beta8 (1.46)
original version by: Nikos Drakos, CBLU, University of Leeds
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>4.17 Embedded grdfile format specifications</TITLE>
<META NAME="description" CONTENT="4.17 Embedded grdfile format specifications">
<META NAME="keywords" CONTENT="GMT_Docs">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="Generator" CONTENT="LaTeX2HTML v99.2beta8">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="GMT_Docs.css">
<LINK REL="next" HREF="node33.html">
<LINK REL="previous" HREF="node31.html">
<LINK REL="up" HREF="node15.html">
<LINK REL="next" HREF="node33.html">
</HEAD>
<BODY bgcolor="#ffffff">
<!--Navigation Panel-->
<A NAME="tex2html1400"
HREF="node33.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.gif"></A>
<A NAME="tex2html1394"
HREF="node15.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.gif"></A>
<A NAME="tex2html1388"
HREF="node31.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.gif"></A>
<A NAME="tex2html1396"
HREF="node1.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.gif"></A>
<A NAME="tex2html1398"
HREF="node149.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.gif"></A>
<BR>
<B> Next:</B> <A NAME="tex2html1401"
HREF="node33.html">4.18 Binary table i/o</A>
<B> Up:</B> <A NAME="tex2html1395"
HREF="node15.html">4. General features</A>
<B> Previous:</B> <A NAME="tex2html1389"
HREF="node31.html">4.16 Character escape sequences</A>
  <B> <A NAME="tex2html1397"
HREF="node1.html">Contents</A></B>
  <B> <A NAME="tex2html1399"
HREF="node149.html">Index</A></B>
<BR>
<BR>
<!--End of Navigation Panel-->
<H1><A NAME="SECTION0012170000000000000000"></A>
<A NAME="4494"></A>
<A NAME="4495"></A>
<A NAME="4496"></A>
<A NAME="4497"></A>
<A NAME="4498"></A>
<A NAME="4499"></A>
<A NAME="4500"></A>
<A NAME="4501"></A>
<A NAME="4502"></A>
<A NAME="4503"></A>
<BR>
4.17 Embedded grdfile format specifications
</H1>
<P>
<A NAME="tex2html278"
HREF="http://www.soest.hawaii.edu/gmt"><B>GMT</B></A> has the ability to read more than one grdfile
format. As distributed, <A NAME="tex2html279"
HREF="http://www.soest.hawaii.edu/gmt"><B>GMT</B></A> now recognizes 12 predefined file
formats. These are
<P>
<DL>
<DT><STRONG> 0.</STRONG></DT>
<DD><A NAME="tex2html280"
HREF="http://www.soest.hawaii.edu/gmt"><B>GMT</B></A> netCDF 4-byte float format [Default]
</DD>
<DT><STRONG> 1.</STRONG></DT>
<DD>Native binary single precision floats in scanlines with leading grd header
</DD>
<DT><STRONG> 2.</STRONG></DT>
<DD>Native binary short integers in scanlines with leading grd header
</DD>
<DT><STRONG> 3.</STRONG></DT>
<DD>8-bit standard Sun rasterfile (colormap ignored)
</DD>
<DT><STRONG> 4.</STRONG></DT>
<DD>Native binary unsigned char in scanlines with leading grd header
</DD>
<DT><STRONG> 5.</STRONG></DT>
<DD>Native binary bits in scanlines with leading grd header
</DD>
<DT><STRONG> 6.</STRONG></DT>
<DD>Native binary ``surfer'' grid files
</DD>
<DT><STRONG> 7.</STRONG></DT>
<DD>netCDF 1-byte byte format
</DD>
<DT><STRONG> 8.</STRONG></DT>
<DD>netCDF 1-byte char format
</DD>
<DT><STRONG> 9.</STRONG></DT>
<DD>netCDF 2-byte int format
</DD>
<DT><STRONG>10.</STRONG></DT>
<DD>netCDF 4-byte int format
</DD>
<DT><STRONG>11.</STRONG></DT>
<DD>netCDF 8-byte double format
</DD>
</DL>
<P>
In addition, users with some C-programming experience may add
their own read/write kernels and link them with the <A NAME="tex2html281"
HREF="http://www.soest.hawaii.edu/gmt"><B>GMT</B></A> library
to extend the number of predefined formats. Technical information
on this topic can be found in the source file <U>gmt_customio.c</U>.
<P>
Because of these new formats it is sometimes necessary to provide more
than simply the name of the file on the command line. For instance,
a short integer file may use a unique value to signify an empty node
or NaN, and the data may need translation and scaling prior to use.
Therefore, all <A NAME="tex2html282"
HREF="http://www.soest.hawaii.edu/gmt"><B>GMT</B></A> programs that read or write grdfiles will decode
the given filename as follows:
<P>
<BR>
<P>
name[=<I>id</I>[/<I>scale</I>/<I>offset</I>[/<I>nan</I>]]]
<P>
<BR>
<P>
where everything in brackets is optional. If you only use the default
netCDF file format then no options are needed: just continue to pass
the name of the grdfile. However, if you use another format you must
append the =<I>id</I> string, where <I>id</I> is the format id number
listed above. In addition, should you want to multiply the data by
a scale factor, then add a constant offset you may append the
/<I>scale</I>/<I>offset</I> modifier. Finally, if you need to indicate
that a certain data value should be interpreted as a NaN (not-a-number)
you may append the /<I>nan</I> suffix to the scaling string (it cannot
go by itself; note the nesting of the brackets!).
<P>
Some of the grd formats allow writing to standard output and reading
from standard input which means you can connect <A NAME="tex2html283"
HREF="http://www.soest.hawaii.edu/gmt"><B>GMT</B></A> programs that
operate on grdfiles with pipes, thereby speeding up execution and
eliminating the need for large, intermediate grdfiles. You specify
standard input/output by leaving out the filename entirely.
That means the ``filename'' will begin with
``=<I>id</I>'' since the <A NAME="tex2html284"
HREF="http://www.soest.hawaii.edu/gmt"><B>GMT</B></A> default netCDF format does
not allow piping (due to the design of netCDF).
<P>
Everything looks more obvious after a few examples:
<P>
<OL>
<LI>To write a binary float grd file, specify the name as <U>my_file.grd=1</U>.
<P>
</LI>
<LI>To read a short integer grd file, multiply the data by 10 and then
add 32000, but first let values that equal 32767 be set to NaN,
use the filename <U>my_file.grd=2/10/32000/32767</U>.
<P>
</LI>
<LI>To read a 8-bit standard Sun rasterfile (with values in the 0-255 range)
and convert it to a <IMG
WIDTH="16" HEIGHT="29" ALIGN="MIDDLE" BORDER="0"
SRC="img53.gif"
ALT="$\pm$">1 range, give the name as
<U>rasterfile=3/7.84313725e-3/-1</U> (i.e., 1/127.5).
<P>
</LI>
<LI>To write a short integer grd file to standard output after subtracting
32000 and dividing its values by 10, give filename as =2/0.1/-3200.
<P>
</LI>
</OL>
<P>
Programs that both read and/or write more than one grdfile may
specify different formats and/or scaling for the files involved.
The only restriction with the embedded grd specification mechanism
is that no grdfiles may actually use the ``=''
character as part of their name (presumably, a small sacrifice).
<P>
<A NAME="4524"></A>
<P>
One can also define special file suffixes to imply a specific file
format; this approach represents a more intuitive and user-friendly
way to specify the various file formats. The user may create a file
called <U>.gmt_io</U> in the home directory and define any
number of custom formats. The following is an example of a
<U>.gmt_io</U> file:
<A NAME="4527"></A>
<P>
<BR>
<P>
<PRE><TT>
# GMT i/o shorthand file
<BR># It can have any number of comment lines like this one anywhere
<BR># suffix format_id scale offset NaN Comments
<BR>
grd 0 - - - Default format
<BR>
b 1 - - - Native binary floats
<BR>
i2 2 - - 32767 2-byte integers
<BR>
ras 3 - - - Sun rasterfiles
<BR>
byte 4 - - 255 1-byte grids
<BR>
bit 5 - - - 0 or 1 grids
<BR>
mask 5 - - 0 1 or NaN masks
<BR>
faa 2 0.1 - 32767 Gravity in 0.1 mGal
</TT></PRE>
<P>
These suffices can be anything that make sense to the user. To
activate this mechanism, set parameter GRIDFILE_SHORTHAND to TRUE in
your <U>.gmtdefaults</U> file. Then, using the filename
<U>stuff.i2</U> is equivalent to saying <U>stuff.i2=2/1/0/32767</U>,
and the filename <U>wet.mask</U> means wet.mask=5/1/0/0. For a
file intended for masking, i.e., the nodes are either 1 or NaN,
the bit or mask format file may be down to 1/32 the size of the
corresponding grd format file.
<A NAME="4535"></A>
<P>
<HR>
<!--Navigation Panel-->
<A NAME="tex2html1400"
HREF="node33.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.gif"></A>
<A NAME="tex2html1394"
HREF="node15.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.gif"></A>
<A NAME="tex2html1388"
HREF="node31.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.gif"></A>
<A NAME="tex2html1396"
HREF="node1.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.gif"></A>
<A NAME="tex2html1398"
HREF="node149.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.gif"></A>
<BR>
<B> Next:</B> <A NAME="tex2html1401"
HREF="node33.html">4.18 Binary table i/o</A>
<B> Up:</B> <A NAME="tex2html1395"
HREF="node15.html">4. General features</A>
<B> Previous:</B> <A NAME="tex2html1389"
HREF="node31.html">4.16 Character escape sequences</A>
  <B> <A NAME="tex2html1397"
HREF="node1.html">Contents</A></B>
  <B> <A NAME="tex2html1399"
HREF="node149.html">Index</A></B>
<!--End of Navigation Panel-->
<ADDRESS>
Paul Wessel
2001-04-18
</ADDRESS>
</BODY>
</HTML>
|
