NAME
ncview - graphically display netCDF files under X windows
SYNOPSIS
ncview [-beep] [-copying] [-frames] [-warranty] [-private] [-ncolors
XX] [-extrainfo] [-mtitle "title"] [-minmax fast | med | slow | all]
datafiles ...
DESCRIPTION
Ncview displays 2-D slices of a netCDF data file, using the X Window
System graphical user interface (Release 4 or higher). You can examine
different floating point variables in the file, and animate the
floating point data along the ‘‘record dimension’’ (usually time) to
see how it evolves. You can also display 1-D (line plot) views of the
data simply by clicking the mouse on the point of interest.
When you first invoke ncview, a command panel comes up which has a
number of buttons for manipulating the current view into the data file,
and presenting various information about the current view. From the
top, going down, the information fields are: the ’title’ of the data
file; the ’long_name’ of the currently selected variable; the frame
number (i.e., place along the scan axis) currently displayed; the
minimum and maximum values of the variable; and the value of the data
point under the cursor (only active when the pointer is over the color
contour image).
Next comes a row of buttons similar to a tape recorder, used for
changing the view into the netCDF file along the scan dimension. In
Version 1.XX of ncview, the scan dimension is constrained to be the
‘‘record dimension’’ (in netCDF parlance). From the left, the buttons
are: the quit button; a button to take you directly to the first frame,
marked "->1"; rewind, which loops the images going backwards; step
backwards; pause; step forwards; and fast forward, which loops the
images going forwards.
Below this is the row of option buttons, which from the left are: the
colormap button, labeled with the name of the current colormap (see
below); "Inv P", which inverts the physical representation of the data
(flips it upside-down); "Inv C", which inverts the colors currently
being used so that the colors indicating minimum and maximum are
switched; the magnification button, which sets how much image expansion
the image undergoes; and the transformation button, which determines
what preprocessing the data undergoes before display. For this button,
"Linear" means no preprocessing, "Low" means that the data is raised to
the fourth power before conversion to a pixel, so that low values are
emphasized; and "Hi" means that the fourth root of the data is taken
before conversion, so that large values are emphasized. Next comes
"Set Dim"; pressing this pops up a window which allows you to determine
which variables are shown on the X and Y axes. Note that Version 1.XX
of ncview will not transpose your data! This means that, for example,
you cannot simultaneously display the X dimension along the Y axis
while displaying the Y dimension along the X axis---that would be an
attempt to transpose the data. You can display the X dimension along
the Y axis if some other variable which varies less rapidly in your
particular data file (for example, depth) is on the X axis. Such a
configuration is possible because it involves no transposition of data.
In general you don’t have to worry about this issue much, because if
you attempt to pick axes which would be transposing the data, ncview
switches them (and tells you that it’s doing so!) so you can get the
axes you want. Note that there is never any ambiguity about which
dimensions are being displayed on what axes; that information is always
shown in the main panel. Next is "range", which pops up dialog boxes
to set the data min and maxes which will be contoured. Pressing with
the RIGHTMOST mouse button on the "range" button resets the ranges to
match the currently displayed slice; this is a VERY useful option, so
remember it and make use of it frequently! The last button shows the
method currently employed for expanding the data onto the screen; the
default, "bi-lin", performes a bi-linear interpolation. Also available
is "repl", which simply replicates the pixels and is somewhat faster.
The next row of buttons shows what variables can be displayed from the
input files. Note that when ncview first comes up, if there is more
than one variable in the file, you must select a variable to display
before you will see anything. If there is only one variable in the
file, the selection defaults to that one.
Below the variable selection buttons are the dimension information
fields. All the dimensions for the displayed variable which can take
on more than one value are shown here, one variable to a line. In each
line, there are 6 fields of information; from left to right, they are:
"Dim", the Dimension identifier, which is ‘Scan’ if the dimension is
currently the scanned dimension (i.e., the dimension accessed via the
tape-recorder style buttons), ‘X’ if the dimension appears in the color
contour display along the x axis, or ‘Y’ if it appears in the color
display along the y axis. This field will be blank if it isn’t Scan,
X, or Y. Next come "Name", the dimension’s short name; "Min", the
minimum value of the dimension; "Current", the current value of the
dimension as displayed in the color contour panel; "Max", the maximum
value of the dimension; and "Units", the dimension’s units. Clicking
on the "Current" field of a dimension allows you to change the current
value of that dimension. Clicking with the left mouse button increases
the current value of that dimension; clicking with the right button
decreases it.
POPUP X-Y GRAPH
You can get a popup X-Y (line) graph of data at a point simply by
clicking on the point of interest. You have several options at this
point; with the bottons at the bottom of the window you can change the
axis along which the data is graphed (if there are other axes
available), use log scaling for the X and/or Y axis, and set the data
range. You can also dump out the data from the X-Y plot into an text
file, for easy importation into other programs.
Up to five line plots can be on one graph. The panel on which the next
line plot will appear is called the "locked" panel. If you don’t want
the next line plot to appear on the locked panel, then unlock it by
pressing the "Locked" button. At the moment, panels are automatically
unlocked when you choose a new variable.
UDUNITS SUPPORT
ncview supports time axes that use the conventions in the udunits
package. Typical units names in this scheme would be "days since
1990-01-01". If ncview encounters a time dimension that it understands
in this way, then it displays the calendar date (as calculated by the
udunits package, not ncview) rathar than the actual axis value. For
instance, it might display "3_Jun_1995" rather than "Day 2390". To
have this functionality, the udunits package must be able to find the
"udunits.dat" file. You must set the environmental variable
UDUNITS_PATH to the location of this file for ncview to be able to find
it.
MODIFIERS
Clicking on a button with the left mouse button invokes the standard
action described above; clicking with the right mouse button on the
colormap select, transformation, magnification, or dimension "Current"
buttons DECREASES the selection instead of increasing it (i.e., cycles
in the reverse direction). Holding down the control key "accelerates"
actions; while clicking with the left mouse button will increase the
rate at which the rewind, step backwards, step forwards, and fast
forward keys will step through the data. When holding down the control
key while clicking on the magnification button, the magnification
DOUBLES or HALVES instead of incrementing or decrementing by one.
Ncview attempts to save the displayed images in main memory, with each
frame being saved as it is calculated for the first time. This speeds
up looping replays of the same data. If there is not enough memory to
store all the required frames at the selected magnification, ncview
will inform you and automatically stop trying to do so. Changing the
magnification will again force ncview to try and allocate a image
buffer.
Since the scaled, interpolated pixel maps are stored, the following
operations will flush the image buffer and require recalculating the
images if they are performed: inverting the data; inverting the color
map; changing the magnification; changing the data transformation
(linear, lo, or hi); changing the dimension; changing the range;
changing the pixel replication scheme. Changing colormaps does not
require refilling the image buffer.
You can invoke ncview with multiple netCDF filenames on the command
line, and it will try to present the data in a logical way; i.e., if
there are identically named variables in the data files, it will try to
treat them as if they were all in one giant data file. If there are
different variables in different files, it will let you choose to
display any of the available variables. This is generally a Good
Thing, but if you have identically named variables in different files
with different attributes, ncview will not know which attribute you
want to use and most likely will crash.
SETTING THE DATA RANGE
It is important to set the data range correctly; otherwise, the color
contour might come out all red, or all blue, or otherwise not very
interesting. There are a number of ways to set or manipulate the
range: 1) Click with the left mouse button on the "range" button. This
pops up a dialog window letting you specify the minimum and maximum
values directly. 2) Click with the right mouse button on the "range"
button. This scales the displayed data to the currently shown frame.
3) Click with the left mouse button on a data point in the color-
contour window; this will set the minimum scaling to the value of the
data which you clicked on. 4) Click with the right mouse button on a
data point in the color-contour window; this will set the maximum
scaling to the value of the data which you clicked on.
OPTIONS
-beep: rings the terminal’s bell when stepping forward through frames
in movie mode and the loop is restarted.
-extrainfo: Puts up extra information in the color-contour window.
This is useful for photographing the computer screen to make slides or
pictures of the data.
-frames: This will make ncview dump out the frames it displays in a
series of PPM-format files. You can then make them into an mpeg movie
if you so desire (using tools other than ncview).
-mtitle: Puts the following argument (enclosed in quotes) up as the
title of the color-contour window.
-ncolors: Sets the number of colors which will be displayed. Defaults
to 200. Must currently be less than 256.
-private: Forces use of a private colormap. This will cut down on the
number of colormap entries used, but will turn the rest of the screen
annoying colors.
-minmax: determines how the calculation of minimum and maximum values
is done. If fast, then only the first, middle, and last time entries
of each variable are examined. If med, then every fifth time entry is
scanned for extrema. If slow, then every tenth entry is used. If all,
then every time entry is examined for extrema. Default is "fast".
-copying: prints out the terms under which ncview may be copied,
distributed, and modified. Ncview is covered under the provisions of
the Gnu General Public Liicense Version 1.
-warranty: Ncview comes with no warranty; this option prints out a
fuller statement to this effect.
ENVIRONMENT
Ncview looks in directory
/build/buildd/ncview-1.93g/debian/ncview/usr/lib/ncview for system-wide
colormap (.ncmap) files. It also examines the user’s environmental
variable NCVIEWBASE for the name of a directory which contains
additional colormap files. If that is not defined, then colormaps are
sought in the user’s home directory, and in the directory which was run
from.
Colormap files have 256 lines, each consisting of one r g b triplet,
where r, g, and b are integers in the range of 0 to 255. There should
be only whitespace separating the r, g, and b values on each line.
Colormap files end with the extension ".ncmap". If Ncview does not
find any colormaps, it will complain, and supply a simple default map.
It is necessary to install the applications default file, "Ncview", in
your $XAPPLRESDIR directory for the program to function properly. If
the screen appears out of alignment, make sure that this installation
has been performed.
The application resources file recognizes the following resources, in
addition to the standard ones:
labelWidth
The width, in pixels, of the information labels at the top of
the main window. If you generally use long titles and variable
longnames, you might want to increase this. Default = 400.
buttonWidth
The width, in pixels, of the "variable" and "dimension" buttons.
If you use long names for these, you might want to increase this
value. Default = 50.
nVarsPerRow
The number of variable buttons in a row before a new one is
started. Set to be aesthetically pleasing to you. Default = 5.
deltaStep
The amount to step forward and backwards by when the control key
is held down while pushing the button. If this value is less
than 0, in indicates an absolute number of steps to take; if
this value is greater than zero, it indicates the percent (in
integer form, from 1 to 100) of the total file size to step.
Default = 10 (ten percent).
BUGS
Occasional bugs surface, especially when mixing variables in different
files.
Please send all bug reports to pierce@cirrus.ucsd.edu
local