1NCVIEW(1)                   General Commands Manual                  NCVIEW(1)
2
3
4

NAME

6       ncview - graphically display netCDF files under X windows
7

SYNOPSIS

9       ncview  [-beep]  [-copying]  [-frames] [-warranty] [-private] [-ncolors
10       XX] [-extrainfo] [-mtitle "title"] [-minmax fast | med |  slow  |  all]
11       datafiles ...
12

DESCRIPTION

14       Ncview  displays  2-D  slices of a netCDF data file, using the X Window
15       System graphical user interface (Release 4 or higher).  You can examine
16       different  floating point variables in the file, and animate the float‐
17       ing point data along the ``record dimension'' (usually time) to see how
18       it  evolves.   You  can  also display 1-D (line plot) views of the data
19       simply by clicking the mouse on the point of interest.
20
21       When you first invoke ncview, a command panel comes up which has a num‐
22       ber  of  buttons  for manipulating the current view into the data file,
23       and presenting various information about the current  view.   From  the
24       top,  going  down,  the information fields are: the 'title' of the data
25       file; the 'long_name' of the currently  selected  variable;  the  frame
26       number (i.e., place along the scan axis) currently displayed; the mini‐
27       mum and maximum values of the variable; and the value of the data point
28       under  the  cursor (only active when the pointer is over the color con‐
29       tour image).
30
31       Next comes a row of buttons similar to a tape recorder, used for chang‐
32       ing the view into the netCDF file along the scan dimension.  In Version
33       1.XX of ncview, the scan dimension is constrained to  be  the  ``record
34       dimension''  (in netCDF parlance).  From the left, the buttons are: the
35       quit button; a button to take you directly to the first  frame,  marked
36       "->1";  rewind, which loops the images going backwards; step backwards;
37       pause; step forwards; and fast forward, which loops  the  images  going
38       forwards.
39
40       Below  this  is the row of option buttons, which from the left are: the
41       colormap button, labeled with the name of  the  current  colormap  (see
42       below);  "Inv P", which inverts the physical representation of the data
43       (flips it upside-down); "Inv C", which  inverts  the  colors  currently
44       being  used  so  that  the  colors  indicating  minimum and maximum are
45       switched; the magnification button, which sets how much image expansion
46       the  image  undergoes;  and the transformation button, which determines
47       what preprocessing the data undergoes before display.  For this button,
48       "Linear" means no preprocessing, "Low" means that the data is raised to
49       the fourth power before conversion to a pixel, so that low  values  are
50       emphasized;  and  "Hi"  means that the fourth root of the data is taken
51       before conversion, so that large values  are  emphasized.   Next  comes
52       "Set Dim"; pressing this pops up a window which allows you to determine
53       which variables are shown on the X and Y axes.  Note that Version  1.XX
54       of  ncview will not transpose your data!  This means that, for example,
55       you cannot simultaneously display the X  dimension  along  the  Y  axis
56       while  displaying  the  Y dimension along the X axis---that would be an
57       attempt to transpose the data.  You can display the X  dimension  along
58       the  Y  axis  if  some other variable which varies less rapidly in your
59       particular data file (for example, depth) is on the  X  axis.   Such  a
60       configuration is possible because it involves no transposition of data.
61       In general you don't have to worry about this issue  much,  because  if
62       you  attempt  to  pick axes which would be transposing the data, ncview
63       switches them (and tells you that it's doing so!) so you  can  get  the
64       axes  you  want.   Note  that  there is never any ambiguity about which
65       dimensions are being displayed on what axes; that information is always
66       shown  in  the main panel.  Next is "range", which pops up dialog boxes
67       to set the data min and maxes which will be contoured.   Pressing  with
68       the  RIGHTMOST  mouse button on the "range" button resets the ranges to
69       match the currently displayed slice; this is a VERY useful  option,  so
70       remember  it  and make use of it frequently!  The last button shows the
71       method currently employed for expanding the data onto the  screen;  the
72       default, "bi-lin", performes a bi-linear interpolation.  Also available
73       is "repl", which simply replicates the pixels and is somewhat faster.
74
75       The next row of buttons shows what variables can be displayed from  the
76       input  files.   Note  that when ncview first comes up, if there is more
77       than one variable in the file, you must select a  variable  to  display
78       before  you  will  see  anything.  If there is only one variable in the
79       file, the selection defaults to that one.
80
81       Below the variable selection  buttons  are  the  dimension  information
82       fields.   All  the dimensions for the displayed variable which can take
83       on more than one value are shown here, one variable to a line.  In each
84       line,  there are 6 fields of information; from left to right, they are:
85       "Dim", the Dimension identifier, which is `Scan' if  the  dimension  is
86       currently  the  scanned dimension (i.e., the dimension accessed via the
87       tape-recorder style buttons), `X' if the dimension appears in the color
88       contour  display  along  the  x axis, or `Y' if it appears in the color
89       display along the y axis.  This field will be blank if it  isn't  Scan,
90       X, or Y.  Next come "Name", the dimension's short name; "Min", the min‐
91       imum value of the dimension; "Current", the current value of the dimen‐
92       sion  as displayed in the color contour panel; "Max", the maximum value
93       of the dimension; and "Units", the dimension's units.  Clicking on  the
94       "Current"  field  of a dimension allows you to change the current value
95       of that dimension.  Clicking with the left mouse button  increases  the
96       current  value  of  that  dimension;  clicking  with  the  right button
97       decreases it.
98
100       You can get a popup X-Y (line) graph of  data  at  a  point  simply  by
101       clicking  on  the  point of interest.  You have several options at this
102       point; with the bottons at the bottom of the window you can change  the
103       axis  along  which  the data is graphed (if there are other axes avail‐
104       able), use log scaling for the X and/or Y axis, and set the data range.
105       You can also dump out the data from the X-Y plot into an text file, for
106       easy importation into other programs.
107
108       Up to five line plots can be on one graph.  The panel on which the next
109       line  plot will appear is called the "locked" panel.  If you don't want
110       the next line plot to appear on the locked panel,  then  unlock  it  by
111       pressing  the "Locked" button.  At the moment, panels are automatically
112       unlocked when you choose a new variable.
113

UDUNITS SUPPORT

115       ncview supports time axes that use the conventions in the udunits pack‐
116       age.   Typical  units  names  in  this  scheme  would  be  "days  since
117       1990-01-01".  If ncview encounters a time dimension that it understands
118       in  this  way, then it displays the calendar date (as calculated by the
119       udunits package, not ncview) rathar than the actual  axis  value.   For
120       instance,  it  might  display  "3_Jun_1995" rather than "Day 2390".  To
121       have this functionality, the udunits package must be able to  find  the
122       "udunits.dat"   file.    You   must   set  the  environmental  variable
123       UDUNITS_PATH to the location of this file for ncview to be able to find
124       it.
125

MODIFIERS

127       Clicking  on  a  button with the left mouse button invokes the standard
128       action described above; clicking with the right  mouse  button  on  the
129       colormap  select, transformation, magnification, or dimension "Current"
130       buttons DECREASES the selection instead of increasing it (i.e.,  cycles
131       in  the reverse direction).  Holding down the control key "accelerates"
132       actions; while clicking with the left mouse button  will  increase  the
133       rate  at which the rewind, step backwards, step forwards, and fast for‐
134       ward keys will step through the data.  When holding  down  the  control
135       key  while clicking on the magnification button, the magnification DOU‐
136       BLES or HALVES instead of incrementing or decrementing by one.
137
138       Ncview attempts to save the displayed images in main memory, with  each
139       frame  being saved as it is calculated for the first time.  This speeds
140       up looping replays of the same data.  If there is not enough memory  to
141       store  all  the  required  frames at the selected magnification, ncview
142       will inform you and automatically stop trying to do so.   Changing  the
143       magnification  will again force ncview to try and allocate a image buf‐
144       fer.
145
146       Since the scaled, interpolated pixel maps  are  stored,  the  following
147       operations  will  flush  the image buffer and require recalculating the
148       images if they are performed: inverting the data; inverting  the  color
149       map; changing the magnification; changing the data transformation (lin‐
150       ear, lo, or hi); changing the dimension; changing the  range;  changing
151       the  pixel  replication  scheme.   Changing  colormaps does not require
152       refilling the image buffer.
153
154       You can invoke ncview with multiple netCDF  filenames  on  the  command
155       line,  and  it  will try to present the data in a logical way; i.e., if
156       there are identically named variables in the data files, it will try to
157       treat  them  as  if they were all in one giant data file.  If there are
158       different variables in different files, it will let you choose to  dis‐
159       play  any  of the available variables.  This is generally a Good Thing,
160       but if you have identically named variables  in  different  files  with
161       different  attributes, ncview will not know which attribute you want to
162       use and most likely will crash.
163

SETTING THE DATA RANGE

165       It is important to set the data range correctly; otherwise,  the  color
166       contour  might  come  out  all  red, or all blue, or otherwise not very
167       interesting.  There are a number of  ways  to  set  or  manipulate  the
168       range: 1) Click with the left mouse button on the "range" button.  This
169       pops up a dialog window letting you specify  the  minimum  and  maximum
170       values  directly.   2) Click with the right mouse button on the "range"
171       button.  This scales the displayed data to the currently  shown  frame.
172       3)  Click  with the left mouse button on a data point in the color-con‐
173       tour window; this will set the minimum scaling to the value of the data
174       which  you  clicked on.  4) Click with the right mouse button on a data
175       point in the color-contour window; this will set the maximum scaling to
176       the value of the data which you clicked on.
177

OPTIONS

179       -beep:  rings  the terminal's bell when stepping forward through frames
180       in movie mode and the loop is restarted.
181
182       -extrainfo: Puts up extra  information  in  the  color-contour  window.
183       This  is useful for photographing the computer screen to make slides or
184       pictures of the data.
185
186       -frames: This will make ncview dump out the frames  it  displays  in  a
187       series  of PPM-format files.  You can then make them into an mpeg movie
188       if you so desire (using tools other than ncview).
189
190       -mtitle: Puts the following argument (enclosed in  quotes)  up  as  the
191       title of the color-contour window.
192
193       -ncolors:  Sets the number of colors which will be displayed.  Defaults
194       to 200.  Must currently be less than 256.
195
196       -private: Forces use of a private colormap.  This will cut down on  the
197       number  of  colormap entries used, but will turn the rest of the screen
198       annoying colors.
199
200       -minmax: determines how the calculation of minimum and  maximum  values
201       is  done.   If fast, then only the first, middle, and last time entries
202       of each variable are examined.  If med, then every fifth time entry  is
203       scanned for extrema.  If slow, then every tenth entry is used.  If all,
204       then every time entry is examined for extrema.  Default is "fast".
205
206       -copying: prints out the terms under which ncview may be  copied,  dis‐
207       tributed,  and modified.  Ncview is covered under the provisions of the
208       Gnu General Public Liicense Version 1.
209
210       -warranty: Ncview comes with no warranty;  this  option  prints  out  a
211       fuller statement to this effect.
212

ENVIRONMENT

214       Ncview  looks  in  directory /usr/share/ncview for system-wide colormap
215       (.ncmap) files.  It also examines  the  user's  environmental  variable
216       NCVIEWBASE  for  the name of a directory which contains additional col‐
217       ormap files.  If that is not defined, then colormaps are sought in  the
218       user's home directory, and in the directory which was run from.
219
220       Colormap  files  have  256 lines, each consisting of one r g b triplet,
221       where r, g, and b are integers in the range of 0 to 255.  There  should
222       be  only  whitespace  separating  the  r, g, and b values on each line.
223       Colormap files end with the extension ".ncmap".   If  Ncview  does  not
224       find any colormaps, it will complain, and supply a simple default map.
225
226       It  is necessary to install the applications default file, "Ncview", in
227       your $XAPPLRESDIR directory for the program to function  properly.   If
228       the  screen  appears out of alignment, make sure that this installation
229       has been performed.
230
231       The application resources file recognizes the following  resources,  in
232       addition to the standard ones:
233
234
235       labelWidth
236              The  width,  in  pixels, of the information labels at the top of
237              the main window.  If you generally use long titles and  variable
238              longnames, you might want to increase this.  Default = 400.
239
240       buttonWidth
241              The width, in pixels, of the "variable" and "dimension" buttons.
242              If you use long names for these, you might want to increase this
243              value.  Default = 50.
244
245       nVarsPerRow
246              The  number  of  variable  buttons  in a row before a new one is
247              started.  Set to be aesthetically pleasing to you.  Default = 5.
248
249       deltaStep
250              The amount to step forward and backwards by when the control key
251              is  held  down  while pushing the button.  If this value is less
252              than 0, in indicates an absolute number of  steps  to  take;  if
253              this  value  is  greater than zero, it indicates the percent (in
254              integer form, from 1 to 100) of the total  file  size  to  step.
255              Default = 10 (ten percent).
256
257

BUGS

259       Occasional  bugs surface, especially when mixing variables in different
260       files.
261
262       Please send all bug reports to pierce@cirrus.ucsd.edu
263
264
265
266                                     local                           NCVIEW(1)
Impressum