/*
FILE: vector.doc
Document explaining how to use the vector plotting program.
*/
The vector plotting program generates a longitude vs. latitude plot with one or
more of the following elements:
1) coastlines
2) vectors
3) cruise track
It requires two or three input files, depending on which of the above elements
will be plotted:
1) the control file, which specifies the program plotting options
2) a map file, if coastlines are desired
3) the vector data file, if vectors and/or the cruise track are to
be plotted
To run the program, the user usually edits a copy of the sample control file
and then simply types:
vector [ control filename ]
assuming the vector executable is in the user's current directory or search path.
(On the SOEST network, the path is /home/noio/programs/codas3/bin/sun4.
On the PC, it is n:\codas3\bin\pc.)
The program then generates PostScript commands for displaying the plot,
which can be spooled to a PostScript printer using the appropriate
system command (e.g., 'lpr outfile.ps' on Unix systems), or displayed
on a screen using a PostScript viewing package like ghostscript.
-----------------------
The Vector Control File
-----------------------
This text file contains all the user's directions to the vector plotting
program. As a starting point, it is easiest to just copy the sample
vector.cnt file in the ./codas3/cntfiles directory and then edit it as needed.
The contents of this file can initially be classified into two types:
1) comments, always bracketed by /* */
2) options
Comments are ignored by the program, and should NOT be nested.
Options can follow three patterns:
1) a keyword alone
2) a keyword followed by a user-supplied string, quotation or value(s).
3) a keyword followed by a list of sub-options terminated with the word 'end'.
Keywords have special meaning to the program and must be spelled as shown
(case-sensitive!). The colon, when present, is part of the keyword; there
should be no space between the keyword and the colon, but there should be
whitespace (blank or newline) following the colon. The colon is needed
in case 2) and 3) above, that is, when a keyword must be followed by more
information from the user or more sub-options terminated by 'end'.
When a particular keyword is omitted from the control file, the program will
assume some default value or action, which may or may not be what the user wants.
Below is an explanation of all the keywords and their default settings.
Angular brackets <> are used to signify where the user must supply a
value for the keyword. The brackets must not be typed. Where additional
punctuation or words appear outside the brackets, the user MUST include
those as they are significant delimiters. For example, text for the
title options must be enclosed in double quotation marks. Position
coordinates (x,y) must have the two values separated by the comma.
A single control file can be used to produce multiple plots per page and
multiple pages of plots. Most options are "sticky," that is, once set, they carry
over to subsequent options, plots, and pages until they are reset to
some other value. This is consistent with the expectation that a
single control file is generally used to generate similar vector plots,
for example, to show velocities at different depth layers for a given region.
After outlining the options for the first plot, only those particular
options that need to be different for the subsequent plot need to be respecified.
Plot Placement Options
----------------------
top_margin: < n inches >
left_margin: < n inches >
right_margin: < n inches >
bottom_margin: < n inches >
The *_margin: options are used to set the page margins. The space
within these margins is considered the plotting area. The plotting
area includes room for the plot itself, the page and plot titles,
and the numeric labels on the axis tick marks. The time stamp and
annotation, if any, will always appear just inside the upper right
corner of the page, regardless of the margin setting. (These can
be suppressed but not relocated elsewhere; see time_stamp: and
annotation: options below.) The scaling legend, by default, will
appear below the lowest plot axis, and may frequently end up in the
bottom margin. See the legend: option below to see how to relocate
the legend.
By default, the top, bottom, and left margins are all set to 1 inch,
and the right margin is set to 0.5 inch.
subplot: < mni >
The 3-digit number, mni, instructs the program to divide the page into m by n
equal-sized plotting areas, and to put the current plot in position i,
where the plotting areas are numbered sequentially across from top to bottom.
If this option is not used, then the program assumes that the entire page
is one plotting area.
The diagram below shows how vector interprets "subplot: 231", for example.
_________________
| | | |
current plotting area --> | 1 | 2 | 3 |
|_____|_____|_____|
| | | |
| 4 | 5 | 6 |
|_____|_____|_____|
new_page
orientation: < landscape | portrait >
The new_page option is used to place subsequent plots on a new page.
It is only needed when more than one plot is being placed per page
(that is, the subplot: mni argument has m > 1 or n > 1).
When the subplot: option is not being used, or is set to 111,
the program automatically places each plot on its own page.
The orientation: specifies whether the x-axis of the plot will be parallel to
the longer edge of the page (landscape) or to the shorter edge of the page
(portrait). The default is landscape orientation.
Axis Control Options
--------------------
lon_range: < left longitude > to < right longitude > by < tick interval >
lat_range: < min. latitude > to < max. latitude > by < tick interval >
These options specify the x- and y-axis range, respectively. The lon_range:
can be specified as being between -180 to 180 or between 0 to 360 degrees.
The lat_range: is some subset of -90 to 90 degrees. The tick interval,
is specified in degrees and indicates where the axis ticks will occur;
a tick interval of 1, for example, means that a tick will show at every
integral degree.
If left unspecified, the lon_range: and lat_range: default to 0.0,
and the vector program will exit with the message: "Nothing to plot!"
axis:
font: < PostScript font >
font_size: < n points >
linewidth: < n points >
label_interval: < n ticks >
decimal_place: < n decimal places >
scale: < lon degrees per inch > by < lat degrees per inch >
origin: < x inches > , < y inches >
end
The axis: option is used to further specify how the axes are to be drawn
and labeled. The font: and font_size: option may be used to change the
font used in printing the numerical labels on the axis tick marks from
the default setting of 10-point Times-Bold.
The linewidth: option can be used to attain heavier or lighter axis lines
and ticks. The default setting is 0.5 point.
The label_interval: option is used to control the frequency of numeric
labels on the axes. By default, every tick mark will be labeled (i.e.,
label_interval: is 1). The user may set this option to 5, for example,
so only every 5th tick mark will be labeled.
The decimal_place: option is used to control the precision used in
displaying the numeric labels on the tick marks. By default, the
program displays as many decimal places as required to reflect the
precision of the label_interval: value multiplied by the lon_range:
and lat_range: tick interval. For example, if the lon_range:
tick interval specifies that ticks be spaced every quarter-degree while the
label_interval: specifies that every other tick be labeled,
then the program will be labeling every half degree and will
display one decimal place by default.
The scale: option is used to specify the x- and y-axis scale in degrees
per inch. By default, the program selects scaling factors that achieve
the maximum possible rectangular projection that can be accommodated
within the plotting area. This projection causes the longitude axis
to be scaled at cosine of the midpoint of the latitude range.
When specifying the scale: option, the user must take care to pick
values that can accommodate the longitude and latitude range to be plotted
in what the program perceives to be the plotting area; otherwise, the
program exits with the error message: "Unable to fit plot on page."
The plotting area is determined by the page margin settings, the subplot:
option above, the presence of and font sizes used for plot and page titles,
the font sizes used for axis labels, and so on. If the error message
indicates that the plot barely fits, then fiddling with the title and
font settings may solve the problem. Otherwise, the user must either
narrow down the plotting range(s) or increase the scale: specification.
The origin: option is used to position the current plot's origin at a
specific distance from the page's origin, which coincides with the lower left
corner of the paper oriented according to the orientation: specification above.
This distance is specified in inches.
If the plot's origin is not specified using this option, the program
calculates it such that the plot will be centered within the plotting area.
The axis: list of sub-options must always be terminated by the word 'end'.
Vector Plotting Options
-----------------------
vecfile: < [ path ] input file name >
vecfiles: < [ path ] input file name >
< [ path ] input file name >
.
.
.
end
The vecfile: option is used to specify the name of one input file that
contains data to be plotted. The vecfiles: option is used to specify
a list of one or more such input files. Each input file must be
an ASCII-formatted file with data in columns delimited by whitespace.
The first two columns must give longitude and latitude in decimal degrees.
When vectors are to be plotted, then one or more additional pairs of columns
must also be present to specify the U and V velocity components in m/s.
When the vecfiles: option is used, the list of input files must be
terminated by the word 'end'.
u_v_pair: < n pair >
cruise_track
When vectors are to be plotted, the u_v_pair: option must be used to
specify which pair of U/V columns from the input vector file
should be plotted.
The cruise_track option is used to request that the longitude/latitude
data from the input vector file be joined by lines to show the cruise track.
arrow:
headlength: < n inches >
min_headlength: < n inches >
linewidth: < n points >
scale: < n cm/s per inch >
end
The arrow: option can be used to control how the vectors are drawn.
The headlength: option is used to specify the maximum length of the
arrowheads on the vectors, in inches. By default, the headlength:
is set to 0.10 inch.
The min_headlength: is used to specify the minimum length of the
arrowheads on the vectors for the cases where velocities scale
below the headlength: specification. When velocities scale below
this min_headlength: specification, a dot is drawn instead of an
arrow. By default, the min_headlength: is set to half the
headlength: specification.
The linewidth: option is used to set the pen weight for drawing the
vectors. The default value is 0.6 point.
The scale: specifies the vector scaling in cm/s per inch. The default
setting is 100 cm/s to an inch.
Map Plotting Options
--------------------
map:
file: < [ path ] filename >
shading: < gray level, from 0.0 (black) to 1.0 (white) >
linewidth: < points >
end
The map: option is used to request that coastlines be drawn. The file:
option is used to specify the name of the file containing longitude and
latitude coordinates for the coastlines. Several such files are
distributed along with the program, in directory ./codas3/vecplot/mapfiles
along with a utility program called 'extract', which is useful for
reducing a map file to some smaller subset of interest that can be read
in more quickly when multiple plots with the same coastlines are to
be generated. (See the Map Files and Extract Program sections below
for details.) The user can also supply such a file. It must be a 2-column
ASCII file of longitude and latitude, where each set of continuous coastlines is
terminated by '-9999.00 -9999.00' and coordinates for inland water
boundaries are terminated by '-8888.00 -8888.00'.
The shading: option specifies the gray level to be used in shading in the
land areas. A value of 0 blackens these areas, and a value of 1 results in no
shading. Any value in between is admissible. The default value is 1
(no shading).
The linewidth: option is used to control the pen weight used in drawing
the coastlines. The default is 0.4 point.
Note: As of 95/05, there are still a few bugs in the map-drawing routines
that may cause wierd coastlines or even a core dump when particular
longitude ranges are requested. Often, a minor adjustment in the
longitude range (extending or reducing it a few degrees or so) may be
all that is necessary to work around the problem.
Plot Titles and Annotations
---------------------------
main_title: "< text for page title >"
sub_title: "< text for subtitle >"
plot_title: "< text for plot title >"
The main_title: and sub_title: options are used to specify page titles,
which are centered over the plot(s). The text for these titles must be
enclosed in double quotation marks. By default, they are printed in
Times-Bold at 20 points and 10 points, respectively. See the title_font:
and title_font_size: options below for how to change these settings.
The plot_title: is used to specify a title for a plot. This will be centered
over that particular plot only. By default, it is printed in Times-Bold
at 10 points. See the title_font: and title_font_size: options below
for how to change these settings.
Maximum length for all titles is 80 characters.
To disable a title from a previous plot/page, simply set the appropriate
title option to an empty string, for example, plot_title: "".
title_font: < PostScript font >
title_font_size: < no. of points >
These two options are used to change the font used for titles. The
title_font: is used to specify a PostScript font, while the title_font_size:
is used to specify the font size in points. These options must precede
the *_title: option for which they are intended to take effect, for example:
main_title: "KN9302"
title_font_size: 15
sub_title: "6 to 10 April 1993"
title_font: Helvetica
plot_title: "Layer: 21 to 25m"
In the above (rather strange) example, the main title will be printed
in the default font, Times-Bold at 20 points. The subtitle will be
printed in Times-Bold, at 15 points. And the plot title will be printed
in 15-point Helvetica.
label:
type: < common | local >
position: < x > , < y >
justify: < left | right | center >
text: "< text for label >"
symbol: < circle | square | delta | diamond | del | x | plus |
filled_circle | filled_square | filled_delta |
filled_diamond | filled_del >
font: < PostScript font >
font_size: < points >
symbol_size: < points >
end
The label: option can be used to overlay text and symbols on the plot.
There are two types of labels: common and local.
A common label is overlaid on every subsequent plot generated.
A local label appears only on the current plot. By default, a label is common.
The position: option specifies the coordinates, in degrees,
at which the label is to be drawn. By default, the label will be
left-justified at the location specified by the position: option.
The justify: option can be used to control the alignment.
The text: option specifies the text to be overlaid. The text must
be enclosed in double quotation marks. Maximum length is 80 characters.
The symbol: option is used to select which symbol to print.
If both text: and symbol: are specified, then the text appears
to the right of, left of, or centered under the symbol,
depending on whether the justify: option is set to left,
right or center, respectively.
By default, the text is printed using typeface Helvetica, 12 points.
The font: and font_size: options can be used to select some other font/size.
By default, 4-point symbols are printed. The symbol_size: option is
used to specify some other size.
Important: when several labels are being specified, all the sub_options
from the preceding label specification are carried over (sticky),
except for the position:, text:, and symbol: options. Hence,
there is no need to respecify the other sub-options unless they
specifically need to be different from the immediately preceding label.
clear_labels
This option is used to turn off all common labels on subsequent plots.
legend:
type: < common | local >
length: < cm/s >
label: "< text for legend >"
font: < PostScript font >
font_size: < no. of points >
linewidth: < no. of points >
end
When vectors are plotted (that is, when the u_v_pair option is used),
then the program normally prints a scaling legend right below the
lowest plot axis. The legend: option can be used to control how
and where this legend is printed.
We distinguish between common and local legends:
A common legend is printed once per page. A local legend is
printed once per plot. The default type is common.
By default, the common legend is printed half an inch below the
lowest plot axis and nearly right-aligned with the right axis of
the rightmost plot. By default, a local legend is printed
just inside the plot axes, at a distance of 1/2", 3/4" from
the lower right corner of the plot.
The position: option can be used to change these default positions.
The < x > and < y > values should be specified in inches from the page origin,
in the case of a common legend, and in inches from the plot origin,
in the case of a local legend. The upper left corner of the scaling legend
will then be positioned at those coordinates.
By default, the program will use the label "Speed (cm/s)" on the legend.
The label: option can be used to specify some other label. It
can also be used to suppress printing of the legend altogether,
by setting it to an empty string ("").
By default, the scaling legend will display the same length as the
arrow: scale: specification. For example, if the arrow: scale:
specification is left at the default of 100 cm/s per inch, then
the scaling legend will show 100 cm/s and will be one inch long.
The length: option can be used to display some other value and
hence control the size of the printed legend.
By default, the label and numbers on the legend will be printed in
10-point Helvetica. The font: and font_size: options can be used
to select some other PostScript font/size.
By default, the scaling legend will be plotted using a 0.5-point
line. The linewidth: option can be used to specify a different line width.
The list of legend: sub-options must be terminated by the word 'end'.
time_stamp: "< text to use in place of system time stamp >"
annotation: "< text to print below time stamp >"
By default, the vector plotting program always prints the time from the
system clock in the upper right corner of the page. The time_stamp:
option would normally be used to suppress this default behavior by specifying
an empty string, as in time_stamp: "". It can also be used to specify
some other string in place of the system time.
The annotation: option can be used to specify text to be printed right below
where the time stamp appears (in the upper right corner of the page).
By default, no annotation is printed.
Output Options
--------------
ps_file: < PostScript output file name >
This option specifies the name to use for the program's output file,
consisting of PostScript language instructions to the printer.
If it is omitted, then the program prints the output to stdout
(the screen, unless redirected elsewhere). If the file already exists,
then the program either overwrites or appends to it, depending on
which command is used to start plotting:
make_plot
add_plot
These two commands instruct the program to start generating the plot
based on the options already read in. If make_plot is used, then
the output file is created or overwritten, if it already exists.
If add_plot is used, then the output file is appended to, if it
already exists, or created otherwise. Normally, the first plot
instruction in a given control file will be 'make_plot' while
subsequent plots will use 'add_plot' if the same ps_file:
specification is in effect.
Miscellaneous Options
---------------------
skip_to: < label >
This option directs the vector program to ignore all subsequent control file
entries until it encounters a match for the indicated < label >.
The < label > can be any sequence of characters, for example, 'YY'.
This is a useful alternative to using /* */ to temporarily "comment out"
parts of the control file, especially when the section to be skipped over
already contains some comment fields (since nested comments are not allowed).
---------
Map Files
---------
Presently, the vector program comes with five map files of varying
resolution and coverage.
1) codas3/vecplot/mapfiles/westpac.map (West Pacific)
resolution: medium
lon_range : 120E to 160E
lat_range : 10S to 15N
2) codas3/vecplot/mapfiles/solomon.map (Solomon Islands)
resolution: high
lon_range : 140E to 161E
lat_range : 12S to 9N
3) codas3/vecplot/mapfiles/hawaii.map (Hawaiian Islands)
resolution: high
lon_range : 161W to 154W
lat_range : 18N to 23N
4) codas3/vecplot/mapfiles/asia.map (Asia and Pacific Ocean)
resolution: medium
lon_range : 10E to 236E (124W)
lat_range : 55S to 82N
5) codas3/vecplot/mapfiles/world.map
resolution: low
lon_range : 0E to 360E
lat_range : 90S to 90N
If you are using only a small subset of the map file to generate several plots,
it is a good idea to create your own subset map file once and use this for all
your plots, thereby saving time needed to read the original map file (this is
especially important when using the rather large asia.map and world.map files).
Please note that the above map files were digitized with a different purpose
in mind, and some of them (in particular, the asia.map file) will have problems
when the vector program shading: option is turned on (the coastline coordinates
may not define a closed polygon). It may be necessary to forego the shading
in such cases.
The Extract Program
-------------------
To run the map extracting program, type:
extract