This Appendix presents, alphabetically, each of the current command names along with a description of the arguments to each command. Each entry in this file is equivalent to requesting help with the command help cmd where cmd is the command name. Command arguments inside square brackets are optional parameters; the description will describe what value will be substituted if these arguments are not supplied.
If there is a difference between the descriptions that follow and the corresponding on-line version, the on-line help message should be assumed to be correct.
AITOFF will convert the X values (longitude) from
the most recent XCOLUMN
command and the Y values (latitude) from the most recent
YCOLUMN command and convert them
to the equivalent x-y positions for use in an Aitoff (more
precisely, a Hammer) projection. The AITOFF
command MUST be called every time new data is inserted either
with the XCOLUMN or
YCOLUMN commands. If the
optional arguments L and B are present,
they are converted to the equivalent x-y positions for use in
an Aitoff projection. For the equivalent Aitoff "box", see the
GLOBE command.
ANGLE will cause text from
LABEL and
PUTLABEL commands to be
presented at D degrees counterclockwise from the
horizontal (+x direction). Alternatively, if there are four
arguments present, then they are taken to be the World (user)
coordinates of two positions and the ANGLE is set
to the slope of the line.
MAJX, MAJY.
ARC draws an arc at the current cursor position
with major axes MAJX and MAJY (in World
coordinate units). The curve is drawn as a polygon with the
characteristics specified by the command
FILL. The number of points used to
generate the curve can be controlled by adjusting the value of
the character expansion
(see the command EXPAND).
The optional parameter ANG defines the angular extent
of the arc in degrees (set to 360 degrees if not given).
An additional optional parameter, STARTANG,
may be used to determine an initial offset angle of the arc relative to
MAJX (this defaults to 0 degrees if this parameter is
not present). Use the command ANGLE
to set the rotation of MAJX with respect to the
positive x-axis. All angles are in units of degrees and are
defined to be zero toward the right of the viewport
(regardless of the direction of the World Coordinate system)
and increasing counter-clockwise.
See also the BEAM command.
NOTE: If the World Coordinate system
is currently RA and DEC, a rotated arc may not plot correctly.
Use 'header px px' or
'header so so'
(or some other equivalent offset option) to set the coordinate
system to something comparable in scale.
ARROW draws an arrow from the current cursor
position to the World (user) coordinate (X,Y).
The acute angle of the arrow point, in degrees, is specified by
the optional input ANGLE; angles in the range
20.0 to 90.0 give reasonable results. If ANGLE is
not present on the command line, a value of 45.0 degrees is used.
The fraction of the triangular arrow-head that is cut away from the
back is specified by the optional parameter VENT.
A value of 0.0 gives a triangular wedge arrow-head; 1.0 gives
an open >. Values of 0.3 to 0.7 give reasonable results. The
default value for VENT (if it is not present) is 0.3.
EXPAND can be used to vary
the length of the arrowhead. For
EXPAND set to 1.0, the default
size of the arrowhead is 1/40th of the smaller of the width or
height of the view surface.
ASK will set the prompt state to ON if
K is set to 1 and the current device selected is
interactive; otherwise, ASK will set the prompt
state to OFF. If ASK is set ON, then every command
that erases the page will prompt the user before clearing the
screen. The default state of this is OFF; also, every time a new
device is selected (see DEVICE),
ASK is set to OFF.
AUTOLEVS will fill an internal contour level array
with NLEV contours between the values MIN
and MAX. NLEV must be input, but the
rest of the parameters are optional. If either of or both
MIN and MAX are not given, they are
default to the minimum and maximum of the current array loaded
using the command IMAGE. The
optional parameter TYPE is a string of characters
specifying the type of contour levels to generate. If
TYPE is LIN, then the contour levels
are linearly spaced (this is the default if TYPE
is not present); if TYPE is LOG, then
the levels are spaced evenly in the logarithm.
90(K-1).
BAR is analogous to the command
BIN except that it will draw a
bar graph on all (x,y) coordinates read by
XCOLUMN and
YCOLUMN in the direction
specified by the argument K. Set the argument
K to 1 to put the bar extending towards the +X
direction; 2 for +Y; 3 for -X; and 4 for -Y. The values read
by the most recent call to ECOLUMN
determine which color to draw individual bars. If this array is
empty, the current color index is used. The optional argument
THRESH may be used to specify the "bottom" of the
bar. If this optional argument is present, then it is used to
anchor the beginning of the bar graph and should be entered in
the units of that axis. If this optional argument is not
present, the box edge opposite the direction the bar extends
acts as the threshold. An additional optional argument
GAP may be used to specify the "width" of the bar.
If this is not present, the width is defined as the difference
between the mean of the current point and the next point and the
mean of the current point and the previous point. If
GAP is present, it should be in entered in units of
that axis (i.e. for K == 2, GAP
should be in the units of the X-axis) and the bar will be
centered on the point with half the width on either side.
BEAM draws a beam at the current cursor position
outlined using the current color and line width properties.
It has a major axis MAJ and minor axis
MIN and is rotated by a position angle PA
(which is in units of degrees defined as zero along the positive
Y-axis (regardless of the current World Coordinate system) and
increasing counter-clockwise). The optional parameters
OFFX and OFFY (which both default to 0)
define the offset of the center of the beam from the current
cursor position. These offsets are in units of the width or
height of the box that bounds the beam. The beam will first be
drawn solid using the optional input FILLCOLOR and is
then drawn hollow with the current color. If FILLCOLOR
is not provided, it defaults to color index 15.
By default, the axes will be scaled as if header rd rd
has been previously called. This means that the X-axis will be
scaled by 15*cos(declination). To override this scaling, the optional
input SCALE can be provided and set to whatever
scaling is desired (no scaling can be achieved by setting
SCALE to 1). If SCALE is set to any
negative value (or is not present), then RA-Dec type scaling will be
done. The major and minor axes of the beam should be in the same
units as the two axes. This means if SCALE is set
to anything but 1, then they should both be in the same units
as the Y-axis.
If the optional argument BGRECT is provided
(it defaults to 0) and is not negative, then a solid rectangle
will be drawn in that color (color index BGRECT) first.
The rectangle will only be as large as the width and height of the beam.
N.
BGCI sets the text background color index for
subsequent text. By default, text does not obscure underlying
graphics. If the text background color index is positive,
however, text is opaque: the bounding box of the text is
filled with the color specified by the value of N
before drawing the text characters. Use color index 0 to erase
underlying graphics before drawing text. If N is
less than 0, the text will be transparent; if greater than or
equal to 0, the text will be drawn on an opaque background with
color index N. The initial value of the text
background color index is -1 (transparent) and is reset to -1
whenever a new device is selected.
BIN connects the coordinates read by
XCOLUMN and
YCOLUMN as a histogram. If
the optional argument K is present and equal to 0,
then the individual X values denote the lower left edge (in X)
of the bin. If K is set to 1 or is not present,
then the individual X values denote the center location of the
bin. If the optional parameter GAP is present, it
represents the distance (in X axis units) that signals a gap in
the histogram not to be connected. This is useful for histograms
with irregular spacing or directional changes. A good value
for GAP is 2.
LIMITS and TICKSIZE.
BOX annotates the viewport with a frame, axes,
numeric labels, etc. The two arguments X and
Y are strings of options that determine the type
of box and the labeling that will be drawn. The option letters
may be in any order and do not depend on case. If either
parameter is omitted, the missing parameter is given the
default value set by the string variables XBOX and YBOX (see
the command SET). If none of the
letters `A', `B', or `C' are specified, then tick marks will
not be drawn. The options currently available
are:
A : Draw Axis line (X axis is a horizontal line at Y=0, Y axis
is a vertical line at X=0).
B : Draw Bottom (X) or Left (Y) edge of the frame.
C : Draw Top (X) or Right (Y) edge of the frame.
D : Include the superscript symbols 'o', ''', and '"'.
If this option is used, the option `Y' is implicitly implied.
F : Write only the last part of the label for the first time
(left or bottom most) tick on the axis (see Z). For example,
if the full first label is 17 42 34.4, then only write 34.4.
This option is useful for sub-panels that join each other.
Care is needed because first label carries sign as well.
G : Draw a Grid of vertical (X) or horizontal (Y) lines at each of
the major tick mark positions.
H : Include the superscript symbols 'd', 'h', 'm', and 's'.
I : Invert the tick marks; i.e. draw them outside the viewport
instead of on the inside.
L : Label axis Logarithmically. If option `Z' is used, then this
option is ignored. The major tick interval is ALWAYS 1.0;
the number of minor ticks is ALWAYS 8. The numeric label is
10**(x) where x is the world coordinate at the tick mark.
M : Write Numeric labels in the unconventional location Above (X)
or to the Right (Y) of the viewport.
N : Write Numeric labels in the conventional location Below (X)
or to the Left (Y) of the viewport.
O : Omit leading zeros in numbers < 10 in time labels. For
example, the label 3h 3m 1.2s will be written rather than
03h 03m 01.2s. The day field is not affected by this option
and this option is ignored unless used with the `Z' option.
This option is ignored when used with the `V' option as it
makes it impossible to align the labels nicely. This option
is useful to help save space on the X-axis.
P : Extend ("Project") the major tick marks outside the box. This
option will be ignored if option `I' is also specified.
S : Draw Minor Tick marks (Subticks).
T : Draw Major Tick marks at the major coordinate interval.
V : Orient numeric labels Vertically. This is only applicable
to the Y axis. The default is to write the Y-labels parallel
to the axis.
Y : Do not include the day field in time labeling. This means
that labels are "HH MM SS.S" rather than "DD HH MM SS.S".
The hours will accumulate beyond 24, if necessary, in this case.
Z : Use time labeling ((DD) HH MM SS style). The World
coordinates of the box (see LIMITS) and the tick mark increments
(see TICKSIZE) should be given in units of seconds.
1 : Force decimal labeling, instead of automatic choice.
2 : Force exponential labeling, instead of automatic.
0 : By itself, a zero produces a null operation argument; useful
to produce a box along only one axis.
BUFFER will execute the contents of the
command buffer (the same as the command
"playback" or
"playback buffer").
BUFFER may also be used as an argument for commands
requiring a macro name (e.g. LIST
and WRITE).
COLOR defines the current color index used for
filling polygons, drawing lines, and labeling characters for
the selected device. COLOR is originally set to 1
and is reset to this value whenever a new device is selected.
The number of colors available is device dependent (the range
can be displayed with the command
'echo cmin cmax'). If the
requested color index is not available on the selected device,
a color index 1 will be substituted. The first 16 colors
usually have predefined values. Additional values are device
dependent. Each color associated with the color index
N is listed in
the following table:
n Color n Color
--------------------------------------------------------------
0 Black (background) 8 Orange (Red + Yellow)
1 White (foreground) 9 Green + Yellow
2 Red 10 Green + Cyan
3 Green 11 Blue + Cyan
4 Blue 12 Blue + Magenta
5 Cyan (Blue + Green) 13 Red + Magenta
6 Magenta (Red + Blue) 14 Dark Gray
7 Yellow (Red + Green) 15 Light Gray
16-255 Undefined
CONNECT draws line segments connecting the
coordinates read by XCOLUMN
and YCOLUMN. The lines are
drawn using the current line style (set by the command
LSTYLE), in the current color
(set by the command COLOR), and
the current thickness (set by the command
LWIDTH).
IMAGE.
CONTOUR makes a contour plot of an array read with
the IMAGE command at the
contour levels set using either the
LEVELS or
AUTOLEVS commands. The contour
levels MUST be set before a call to CONTOUR. The
contour level array will be modified according to the current
value of the user variable SLEVEL and the string variable
LEVTYPE (also see the command SLEVEL)
before calling any of the contour methods below.
Currently, there are four contour routines available. The
optional parameter N allows the user to select
which of four contour drawing methods will be used to generate
the plot. If N is the character `s', then the
command will produce a fast contour plot (this is the default
if N is not present); if N is `t',
then a smoother contour is produced; if N is `b',
then the same contour plot as with `s' is produced but with
blanking; and `l' produces the same contour plot as with `t',
but with contour level labeling.
For N set to `b', an optional argument
BLANK may be given to specify the blanking value
such that array elements equal in value to BLANK
are ignored (blanked). For N set to `l', the
optional argument BLANK defines the spacing along
the contour between labels (in grid cells) and the optional
parameter MIN specifies the minimum number of
cells that must be crossed before drawing the first contour
label. The default value for BLANK is 0.0 when
N = `b' and 16 for N = `l';
MIN defaults to 8. The optional parameters are
ignored by the contour options N = `s' and `t'.
By default, each contour line is drawn with the current line
attributes (color index, line style, and line width). However,
for options `t' and `l', the default is to draw negative contours
values with dashed and positive contours values with solid lines.
If, however, the parameter N is set to `-t'
(option `t' prepended with a minus sign), then negative contours
values will be drawn with the same line style as positive
contours values.
CURSOR enables the graphics cursor and returns the
x-y position of the cursor along with the key pressed.
CURSOR may also display the image value of the
selected position if an array is currently loaded (see the
IMAGE command) and the cursor
position lies within the scope of the image region (see the
command TRANSFER). The two
optional arguments may be used to determine the starting
position of the cursor. If both parameters are given, they are
used as the World (user) coordinates for the starting
position. If only one parameter is present, it is used as the
X starting position and the Y position is set as the current
cursor position. Finally, if no arguments are present, the
current cursor position is used as a starting position.
If CURSOR is called inside a macro (see the command
DEFINE), with the command
PLAYBACK, or is executed inside
a file via the command INPUT, then
only one keystroke is allowed and no saving of commands will be
done. If, on the other hand, CURSOR is called
interactively, then CURSOR may perform several
functions, depending on the character typed. Internal calls to
CURSOR will occur repetitively until the letter `X'
is typed. On some devices, the left most mouse button will be
associated with the keystroke `A'; the middle with `D'; and the
right with `X'.
Other keystroke functions are:
A : Display the cursor position and image intensity.
D : Draw to the current cursor position.
M : Move to the present cursor position.
P : Draw a point of the current symbol type.
S : Toggles ability to save following keys as commands.
X : Exit the cursor routine.
? : Present this list of key commands.
DATA opens an external file for reading data. The
file is assumed to have data in columns separated by spaces,
tabs or commas. Any column can be read as x or y coordinates
with the XCOLUMN and
YCOLUMN commands.
DEFINE creates an entry for the macro xxx,
and subsequent commands (until the END
command) are considered the body of the macro. The prompt changes
to DEFINE> to indicate the mode. A macro is just
a collection of commands (or other macros) that can be executed
with one call statement. A macro is invoked by using its name as
a command. The contents of the macro may be listed by using the
macro name as an argument to the command
LIST. Macros may be saved using the
command WRITE and may be played
back using the command PLAYBACK.
Macros may be passed arguments or variables whenever they are
executed. The ten tokens used inside the macro to identify the
macro arguments are $1, $2, ..., $9, and $0. These tokens may be
used in the body of the macro, and when the macro is invoked its
arguments will be substituted for these tokens. These tokens MAY
NOT be redefined inside the macro (for example, using the command
SET). If an argument is not present when the macro
is invoked, the token is replaced with a blank space.
N1 - N2 from a macro buffer.
DELETE removes commands from the macro listing
(numbered according to what is shown with the command
LIST). If no arguments are present,
then the last command in the command buffer (see
BUFFER) is deleted. If
N2 is not present, then only the command numbered
N1 in the command buffer
(BUFFER) is removed. If both
N1 and N2 are present, then all commands
from N1 to N2 (inclusive) are deleted
from the command buffer (BUFFER).
If the optional macro name is given, then lines N1 to
N2 (inclusive) are removed from MACRO.
For example, to remove line 4 from a macro named "dojob",
use the command delete 4 4 dojob.
Note that the command buffer macro name is "BUFFER".
DEVICE defines the "device specification" for the
plot device. The specification is system dependent, but usually
has the form "device/type" or "file/type". If the argument is a
question mark ("?"), the user will be prompted to supply a device
name after a list of the currently available devices is
presented. When a new device is selected, the
PANEL command is reset and the
COLOR,
EXPAND,
FILL,
FONT,
LSTYLE, and
LWIDTH commands are called to reset
each to a value of 1. The color palette (see the command
PALETTE) is also reset to
the default palette and the coordinate transfer function
(TRANSFER) is reset to linear.
Finally, the inquire state is turned off (see the command
ASK).
DOT draws a point at the current location (set by
MOVE,
DRAW, etc.)
(or at the position (X,Y) if provided) in the style determined by
the latest call to SYMBOL or
PCOLUMN. The symbol's size is
governed by the last call to the command
EXPAND.
(X,Y) from the current coordinate position.
DRAW draws a line to the World (user) coordinate (X,Y)
from the current location (set by a previous call to
MOVE,
DRAW, etc.).
DRAW then makes (X,Y) the current position.
EXPRESSION on the screen.
ECHO acts just like the command
SET except that rather than assigning
the result of the EXPRESSION to anything it displays
the result on the screen. See the command
SET for an explanation of
EXPRESSION. There may be more than one
EXPRESSION present, but each one should be delimited
by enclosing parenthesis. Literal strings may also be displayed
by enclosing the text in double quotes. String variables may be
displayed by listing their names. For example, to display the
current cursor position, use the command:
echo "cx = " cx "cy = " cy.
N of the data file.
ECOLUMN reads column N from the data file as the
magnitudes of the error bar displacements from the corresponding (x,y)
coordinates. Note that the command
LOGARITHM
does not adjust the error values to logarithmic scale.
ECOLUMN values are also used by the command
LOOKUP.
END finishes the macro definition
and returns to EXECUTE mode. In INSERT mode, END
terminates inserting and returns to EXECUTE mode. In EXECUTE
mode, END exits from the program altogether.
The commands EXIT and QUIT may be
used as a substitute for the command END.
ENVIRONMENT can clear the current page, set up the
World (user) limits and draw a standard box. The first four
optional arguments establish the World (user) limits of the plot
region. If they are not present, then the data read from the most
recent call to the commands XCOLUMN
and YCOLUMN is used to autoscale
the limits. If the limits are present, then two other optional
parameters may be selected. The first of these parameters,
N, will set the scales of the X and Y axes to be equal,
if it is equal to 1; otherwise the two axes will be scaled
independently. The final optional parameter K will
determine what type of box to draw and may have the following values:
-2 : draw no box, axes or labels;
-1 : draw box only;
0 : draw box and label it with coordinates;
1 : same as K=0, but also draw the coordinate axes (X=0, Y=0);
2 : same as K=1, but also draw grid lines at the major
: increments of the coordinates;
10 : draw box and label X-axis logarithmically;
20 : draw box and label Y-axis logarithmically;
30 : draw box and label both axes logarithmically.
Both N and K default to 0 if not provided.
ERASE erases the graphics screen. If the current
device is a hardcopy device, ERASE will cause the
plot to advance to the next page. If ASK
is set ON and the current device is not a hardcopy device, then the
user will be prompted before advancing to the next page.
90(K-1).
ERRORBAR is analogous to
POINTS; it draws error bars at
each of the (x,y) points (read by the most recent call to the
commands XCOLUMN and
YCOLUMN) at a length specified
by the points read by the command
ECOLUMN. The argument K
should be 1 to put the bar along the +x direction; 2 for +y;
3 for -x; and 4 for -y. If K is 5, then error bars
are drawn in both the +x and -x directions.
Likewise, if K is 6, then error bars
are drawn in both the +y and -y directions.
Use EXPAND
to govern the size (extent) of the caps.
Setting the expansion to zero means no caps are drawn.
ETXT erases the text from the view surface (if the
device is capable of doing this). This should erase text without
affecting the currently displayed graphics. Nothing is done on
devices without this capability.
E.
EXPAND sets the expansion for all characters and points.
It is initially set to 1.0 and is reset to 1.0 whenever
a new device is chosen.
N.
FILL sets the fill type. The fill type is
identified by N, where N refers to
one of the following:
1 : solid
2 : hollow
3 : hatched
4 : cross-hatched
The fill type is initially set to 1 (solid) and is reset to 1
whenever a new device is chosen. If the fill type is hatched or
cross-hatched, optional arguments can be supplied that affect
the way the hatching will be done. Up to three additional
arguments may be provided. ANGLE specifies the
angle the hatch lines make with the horizontal, in degrees,
increasing counterclockwise. SEPN is the spacing
of the hatch lines. The unit spacing is 1 percent of the smaller
of the height or width of the view surface. PHASE
is an offset value and is a real number between 0 and 1. The
hatch lines are displaced by this fraction of SEPN
from a fixed reference. Adjacent regions hatched with the
same PHASE have contiguous hatch lines. To hatch
a region with alternating lines of two colors, fill the area
twice: once with PHASE=0.0 in one color and
PHASE=0.5 in the other color. The default value
for ANGLE is 45.0 degrees, SEPN is 1.0,
and PHASE is 0.0.
FIT will solve either for a linear fit of the form:
"y = a + bx" by either the
(a) Least Squares method ("lsqfit"); or
(b) Criterion of Least Absolute Deviations ("medfit");
or will solve for a Gaussian fit of the form
"y = a * exp(-((x - b)/c)**2)".
The data that comprise the "x" and the "y" in these equations are
from the most recent call to the
XCOLUMN and
YCOLUMN commands. For a
linear fit, there is only one required argument, STYLE,
which specifies which type of linear fit to perform. The only
possible values of STYLE are "lsqfit" and "medfit".
The fit coefficients and the corresponding errors in the fit are
displayed at the command line. When using the "lsqfit" technique,
estimates of the measurement errors may be included by reading the
error values with the ECOLUMN
command. The optional parameters provide a way to assign the fits
and the error estimates to User Variables (see the
SET command). The "lsqfit" returns
(in this order) the parameters "a" and "b" along with a chi-square
for the fit and sigma errors on the estimates of "a" and "b". If data
in the most recent call to ECOLUMN
was used to specify errors on the observation points, a "goodness
of fit" is also returned. If, however, no errors are specified,
the correlation coefficient is returned in place of the "goodness
of fit". The "medfit" returns (in this order) the fit parameters
"a" and "b" along with "absdev" (the mean absolute deviation in
the "y" direction). As an example, the command
fit lsqfit \0 \1
will only assign the fit parameters "a" and "b" to the User
Variables \0 and \1 and the remaining items will be ignored (but
still displayed at the command line).
For Gaussian fits, there are two required arguments:
STYLE and N, where STYLE
must be "gaussian" and N specifies the number of
Gaussians to fit. The number of optional parameters that
may follow is governed by the value of N. Optional
arguments should follow in groups of 3's in the following order:
amplitude, mean, and full width at half maximum. Assignment of the
output values follows as for linear fits. If the 3*N+1
parameter is present, it is set to the chi-square of the fit.
Setting any parameter to it's negative holds that value fixed
during the fit. For example:
set \1 1.0 # Guess at amplitude.
set \2 5.0 # First guess at X-position of peak.
set \3 -2.3 # Input FHWM and hold this fixed during fit.
fit gaussian 1 \1 \2 \3 \4 # Fit 1 Gaussian and store fit
# and chi-square in \1, \2, \3, and \4, respectively.
N.
FONT sets the font type to one of the available fonts.
The argument N selects the font used for subsequent
text plotting. The font type is initially set to 1 ("normal")
and is reset to 1 whenever a new device is chosen. Currently,
four fonts are available and can be set by setting the parameter
N to one of the following values:
1 : (default) a simple single-stoke font ("normal" font)
2 : roman font
3 : italic font
4 : script font
The font may also be temporarily changed within a text string
by using the escape sequences: \fn, \fr, \fi, or \fs.
NEW command.
FREE will remove the user specified variable(s) from
WIP. In addition, it releases (i.e. frees) the memory associated
with each ITEM. At least one ITEM is
required and each ITEM listed specifies the name of
the string variable, user variable, or vector (without any index)
to release.
GLOBE draws a "globe" for use in Aitoff (Hammer)
projections. The "globe" that is drawn is an outline of the
entire sky centered on the position (L, b) = (0, 0). There
are two optional parameters. The first optional parameter
NLONG represents the number of longitude lines
that are drawn and the optional parameter NLAT
represents the number of latitude lines that are drawn. If
these arguments are omitted, the values of NLONG = 5
and NLAT = 3 will be used for defaults.
Also see the command AITOFF.
HALFTONE draws a plot of the array read with the
IMAGE command over the subimage
region selected with the SUBIMAGE
command according to the coordinate transformation matrix
specified by the TRANSFER
command and the current image transfer function (see the
ITF command).
If the device permits, colors
can be preassigned to the halftone values with any of the
PALETTE,
LOOKUP,
RGB, or
HLS commands
(whenever a new device is selected, the palette is reset).
The first two optional parameters allow the user to specify the
intensity range for the plot.
If the optional parameters MIN and
MAX are not present,
then HALFTONE will use the image minimum and maximum.
The next optional parameter, N, if present,
indicates that histogram equalization should be performed using
N bins. If this parameter is present and is set to
zero, then the full number of color table entries will be used
in the binning. If this is not present, no equalization will be done.
The last optional parameter BLANK is used to
specify a blank value in the image to ignore when doing
histogram equalization. It defaults to -99.
Histogram equalization is only applied to data within the
current subimage region and within the minimum and maximum intensity.
NOTE: Histogram equalization changes the current LUT. The LUT
must be reset before calling the HALFTONE command again.
HARDCOPY command will cause the output file to be
closed and the file spooled to the printer. How the file is
printed is determined by the string variable "print" (see the
command SET). By setting "print"
to the string "ignore", automatic printing can be disabled.
By default, the string variable "print" is set to "lpr"
(use the command 'echo print'
to display the current value of "print").
HEADER sets the transfer function and World (User)
limits of the box region for the current image. This function
makes use of the current SUBIMAGE
values to fix the World coordinate range. If the optional
arguments XTYPE and YTYPE are
not present, they are set to the current values of the string
variables "XHEADER" and "YHEADER", respectively. If only one
argument is present, both XTYPE and YTYPE
are set to this value. Currently, there are 7 possible values
for XTYPE and YTYPE used to control
the resulting header arrangement:
rd : Right ascension/declination (absolute coordinates).
so : Arcsecond offset positions.
mo : Arcminute offset positions.
po : Pixel offset positions.
px : Absolute pixel positions.
gl : General linear coordinates.
go : General linear offset coordinates.
All offset arguments are relative to the value of the user variables
CRVALX and CRVALY. The option "rd" includes a 15*cos(dec) factor
applied to the right ascension term. Incorrect options are treated
as if "px" was selected. The options "gl" and "go" apply no
additional scaling factor to the header variables. If the image
headers CRVAL, CRPIX, and CDELT are not present for that axis or
are all set to 0, the coordinate transfer function will be set to
its default value (see the command
TRANSFER) and the world limits
to the image range in pixels.
NOTE: Currently, the conversion is
fixed to be from radians to arcseconds (or seconds of time) for
MIRIAD images; degrees to arcseconds for FITS images; and no
conversion for BASIC images.
xxx.
HELP prints a one line
description of every command. With the name of a command as
an argument, HELP prints more information on that
particular command. The command 'help ?' will
provide a list of all available command and macro names.
IMAGE.
HI2D plots a series of cross-sections of the current
image (see IMAGE). Each
cross-section is plotted as a hidden line histogram. The one
required argument, BIAS, specifies a bias value
to be applied to each successive cross-section (in order to
raise it above the previous one). BIAS is in the
same units as the image data. If the optional parameter
SLANT is present, it is an integer value offset to
be applied to each successive cross-section (in the X-direction).
If SLANT is greater than 0, then the plot slants to
the right; less than 0, it slants to the left. The default value
for SLANT is 0 (no slant). If the optional argument
CENTER is present and equal to 1 (the default), then
the individual X values denote the center location of the bin;
otherwise, the X values denote the lower edge (in X) of the bin.
XCOLUMN.
HISTOGRAM connects the coordinates read by
XCOLUMN as a histogram. If the
optional arguments MIN and MAX are present,
they are used to specify the minimum and maximum of the histogram.
Furthermore, an optional parameter N can specify the
number of bins to divide up the histogram. At present, N
may not exceed 200. By default, MIN and MAX
are set to the minimum and maximum of the data read by
XCOLUMN and N is set
to 5. The user should set the limits (see the command
LIMITS) of the box before calling
the HISTOGRAM command.
HLS sets the color representation of the color index
K to the provided values of Hue-Lightness-Saturation.
HUE is represented by an angle in degrees, with red
at 120, green at 240, and blue at 0 (or 360). LIGHT
ranges from 0 to 1, with black at lightness of 0 and white at
lightness 1. SAT ranges from 0 (gray) to 1 (pure color).
HUE is irrelevant when SAT is 0. If
K is greater than the maximum color index of the device,
then this call will be ignored (use the command
'echo cmin cmax'
to display the current color range).
ID puts the name of the user and the current date
and time at the bottom of the plot region. If the environment
variable PGPLOT_IDENT is defined and the current device is a hardcopy
device (the command 'echo hardcopy'
will return 1 if this is true), then this call is automatically
done when the device is finally closed (see the command
HARDCOPY).
xxx if EXPRESSION is true.
IF allows conditional execution of macros and commands.
The macro or command XXX is executed only if the
conditional test of the expression is TRUE (non-zero). The
EXPRESSION may be a simple (X OP Y)
expression where the parameters X and Y
may be any numerical value or user variable (see the
SET command) and OP is
the condition to test and is defined TRUE for the following:
op : Test
------------------------------------------------------
== : X equal to Y;
!= : X not equal to Y;
< : X less than Y;
> : X greater than Y;
<= : X less than or equal to Y;
>= : X greater than or equal to Y;
&& : X and Y are non-zero;
|| : X or Y are non-zero;
^ : X or Y, but not both, are non-zero.
If the test consists of more than just a simple (X op Y)
test, then the entire expression MUST be enclosed by parenthesis.
As an example,
if ((x1 < x2) && (y1 < y2)) limits x2 x1 y1 y2
will only execute the LIMITS
command if X1 is less than X2 AND Y1 is less than Y2. Note also
that this example illustrates that the usual parameters/arguments
may follow the macro or command name. See the command
SET for a more detailed description
of EXPRESSION.
IMAGE loads an array into WIP for use with plotting
commands like CONTOUR and
HALFTONE.
Currently, WIP tests the file to determine its file type (i.e.
FITS, MIRIAD, BASIC, etc.) and then loads it into available memory.
The optional parameter PLANE selects which plane of
a data cube to load. The default value for PLANE is 1.
IMAGE trys to read available header information which
will be useful for setting the coordinate transformation matrix
(see the command TRANSFER)
after the image is read into memory (with the command
HEADER). The current subimage
values (see the command SUBIMAGE)
are reset to the full array size of the new image and the user
variables CRVALX/Y, CRPIXX/Y, and CDELTX/Y may be set to the newly
read header values (if they can be read). The subimage values,
6 user variables, and the transformation matrix are used to
determine where the plot will appear. In order to correctly
set the transformation matrix with the command
HEADER, the values of CRVAL,
CRPIX, CDELT, and CTYPE must be present for the first two axes.
The next optional parameter BADPIXEL may be
specified (after PLANE) as the value for blanked or
masked pixels.
By default, these will be set to -99.
This value may be helpful for use
with the CONTOUR command.
The final optional parameter ORDER permits the
image to be smoothed on reading. The parameter ORDER
may take on a value of 0, 1, or 2 and represents the order of
the fit. A value of 0 (or if it is not provided) means to apply
no smoothing (the default).
NOTE: Current image types include: basic, Miriad, and FITS. BASIC image name syntax is: filename`columnsXrows[`offset] where rows and columns are in pixels and the optional offset is in bytes from the beginning of the file. The character 'X' determines the size of each element and is 'b' for unsigned bytes; 's', signed 2 byte integers; 'l', signed 4 byte integers; 'r', 4 byte floating point; 'd', 8 byte double precision floating point.
V to the result of EXPRESSION.
INITIALIZE evaluates the EXPRESSION
(see the command SET) and sets
every element of the array (vector) user variable V
to the result. If N is less than zero, the current
size of the vector variable V is used. If
N is zero, no expression is needed and the vector
is set to size zero (empty). If N is greater than
zero and an expression is present, the first N
elements of the vector are set to the result of the expression.
If the expression is missing, the size of the vector will be reset.
INPUT reads plot commands from a file and treats
them exactly as if they were typed: commands are executed or
can be inserted or macros may be defined. Unlike interactive
mode, individual commands are NOT saved in the command buffer
(see BUFFER).
NOTE: Macros are not redefined so care should be taken to
insure that the proper macro is being executed.
N in a macro.
INSERT enters insert mode (indicated by the
INSERT> prompt) and
subsequent commands are inserted, without execution, into the
named macro until an END command
is encountered. Commands are numbered as shown by the command
LIST. Without any arguments,
INSERT inserts commands at the end of the command
buffer. If N is present but no macro name is given,
then commands are inserted before line N in the
command macro (BUFFER). With
the MACRO argument, INSERT starts
inserting just before line number N in macro
MACRO.
NOTE: The command buffer macro name is
BUFFER.
N.
ITF sets an internal parameter such that all subsequent
image drawing functions (IMAGE and
WEDGE) act on the transformed image.
Acceptable values for N and their meanings follow:
0 : linear
1 : logarithmic
2 : square-root
The initial value of the image transfer function is 0 and is
reset to 0 whenever a new device is selected.
STR at the current cursor position.
LABEL writes the string STR (which
starts at the current cursor position and continues to the
last non-space character in the label string). The string's
size and the angle it is displayed are controlled by the most
recent call to the commands EXPAND
and ANGLE.
LCUR allows a polyline to be drawn using the cursor.
Vertices may be added or removed by locating the cursor at a
desired point and selecting the key 'A' (Add) or 'D' (Delete) or
may terminate the command with the key 'X' (eXit). The vertices
are stored in the XCOLUMN and
YCOLUMN arrays and may be
redrawn by subsequent calls to this command. If the optional
parameter NPTS is given, it is used as the number
of points in the previous call to this command. To initialize
the command, set NPTS to 0. By default,
NPTS is set to the current value of the number of
points in the most recent call to the
XCOLUMN and
YCOLUMN commands.
LDEV lists (to standard output) the names of
the installed devices known to the current version of WIP.
LEVELS establishes the contour values for use in a
contour plot. Currently, the maximum number of levels available
is 40. This array of levels may be augmented if a call to the
command SLEVEL is done prior to
a call to the CONTOUR command.
LIMITS sets the World (user) coordinate system of
the plot window. All coordinates from
XCOLUMN,
YCOLUMN,
MOVE,
DRAW, etc.,
are relative to these limits. If no
arguments are present, then the data from the most recent
XCOLUMN and
YCOLUMN
commands are used to set the limits.
X, Y, E, and PCOLUMN file read to lines L1-L2.
LINES sets the range of lines read from the
data file by the commands
XCOLUMN,
YCOLUMN,
ECOLUMN, and
PCOLUMN.
This is useful to avoid non-data lines. The argument L1
is also used to specify the line that the command
STRING
will use to extract a string variable.
xxx.
LIST lists the commands of the named macro. If there
are no arguments, the macro BUFFER
(the command buffer) is listed. If one argument is given, then
the commands from L1 to the end of the macro
BUFFER is shown. With two
arguments, lines L1 to L2 are shown.
If the macro name xxx is also entered as the third
argument, then that macro is listed over the inclusive line range
of L1 to L2. The numbers assigned to
commands by LIST should be the ranges used by calls
to the commands DELETE and
INSERT.
NOTE: The command buffer macro name is
BUFFER.
LOGARITHM takes the base 10 logarithm of either
vectors or images. The argument NAME specifies
either a vector name (e.g. "x") or an image name (currently,
only the name "image" is acceptable). If the value of the
vector or image is greater than zero, the logarithm is taken
and this result is multiplied by the value of SCALE.
If SCALE is not present, a value of 1.0 is used.
SCALE may be any valid numeric expression (see
the command SET).
LOGARITHM uses -50 for the logarithm
of 0 or negative numbers and does not scale these values.
LOOKUP uses the values read by the most recent call to
the commands XCOLUMN,
YCOLUMN,
ECOLUMN, and
PCOLUMN
to load values into the color lookup table. This is a more
compact (and correct) method for loading an entire table than
the single color index commands RGB and
HLS. All values in the
XCOLUMN,
YCOLUMN,
ECOLUMN, and
PCOLUMN data must be between 0 and 1.
The XCOLUMN data correspond to the
red values, YCOLUMN to green, and
ECOLUMN to blue. The
PCOLUMN data identifies the
ramp intensity level for the corresponding RGB values. Colors
on the ramp are linearly interpolated from neighboring levels.
If the optional parameter N is present and is negative,
then the resulting lookup table will be flipped. By default (if the
optional argument N is missing or is positive), the
RGB table is loaded directly (not flipped).
xxx COUNT times.
LOOP allows for multiple execution of a macro.
The macro xxx is executed COUNT times.
The optional parameters P1, P2, ...
are any arguments needed to be passed to the macro (see the
DEFINE command). The arguments
P1, P2, ... passed to the macro are NOT altered
during each execution of the loop.
N.
N, where N refers to
lines of the following form:
1 : solid
2 : dashed
3 : dot - dash - dot - dash
4 : dotted
5 : dash - dot - dot - dot
If N is some number other than one of the line style
values above, it is set to 1. Also, the line style is set to 1
initially and is reset to 1 whenever a new device is selected.
N.
LWIDTH sets an internal parameter such that all
subsequent lines, text, and graph markers are drawn with lines
of width N. This number may range from the default
of 1 to a maximum of 201. Any other value is set to 1. The
actual thickness drawn is device dependent, but is approximately
equal to 0.005 inches times the value of N. The
initial value of the line width is 1 and is reset to 1 whenever
a new device is selected.
MACRO will read the commands from the file
filename and define macros exactly as if they were
typed interactively. This allows macros saved from previous WIP
sessions (using the WRITE command)
to be read into WIP and defined. Only macro definitions are allowed.
MINMAX list the maximum and minimum values of the
image that has been read by the IMAGE
command. This command may be useful for setting contour levels,
or adjusting a halftone plot. The minimum and maximum of the
current array are stored in the user variables IMMIN and IMMAX.
(The minimum and maximum may also be displayed using the command
'echo immin immax'.) If the
optional parameter N is present and set to any value
greater than 0, then the minimum and maximum are explicitly
recalculated. This may be useful if the minimum and maximum has
been found and then the logarithm of the image is computed.
(x,y).
MOVE sets the current World (user) location to (x,y)
without drawing any lines or text. This simply provides a way to
specify the current position of the cursor.
STR relative to SIDE.
MTEXT writes text at the position specified relative
to a viewport side. The parameter SIDE specifies
which side of the viewport to place the string. SIDE
must be either `B', `L', `T', or `R' to specify the
Bottom, Left, Top, or Right side of the viewport.
Additionally, if SIDE is `LV' or `RV', then the string
will be written perpendicular to the frame rather than parallel
to it. The parameter DISP specifies the displacement
from the frame edge (in character height units). If DISP
is negative, then the string is written inside the viewport. The
parameter COORD is the location of the string as a
fractional length of the specified edge of the viewport.
JUST specifies how to justify the string relative to
COORD with JUST = 0 meaning left justified;
0.5, centered; and 1.0, right justified. The text STR
is the (multiword) string to display.
As an example, "good" values used to place a string along the X
axis, the Y axis, and the top of the plot box are:
mtext B 3.2 0.5 0.5 Xaxis label string
mtext L 2.2 0.5 0.5 Yaxis label string
mtext T 2.0 0.5 0.5 Top label string
The first two examples above correspond to the syntax used by
the commands XLABEL and
YLABEL.
NCURSE allows a set of points to be drawn using the
cursor. Points may be added or removed by locating the cursor
at a desired point and selecting the key `A' (Add) or `D' (Delete)
or may terminate the command with the key `X' (eXit). The points
are stored in the XCOLUMN and
YCOLUMN arrays and may be redrawn
by subsequent calls to this command. If the optional parameter
N is given, it is used as the number of points in the
previous call to this command. To initialize the command, set
N to 0. By default, N is set to the
current number of points in the most recent call to the
XCOLUMN and
YCOLUMN commands. On return,
the cursor points are returned in increasing order of X (unlike
the command OLIN).
NEW creates a new variable. If more than one
ITEM is present on the command line, then each will
represent the name of a new variable to be created. Each
ITEM name must be unique and may not correspond
to a pre-defined variable or any other defined variable. Once
these variables are created, they may be used just like the
pre-defined variables: the command SET
will permit the value to be set/changed and the command
ECHO may be used to display the
current value. Use the command FREE
to release the memory associated with each ITEM. If
the ITEM is enclosed in double quotes
(e.g. "ITEM"), a string variable is created. If the
ITEM has an optional size argument included, a vector
is created. Note that when defining a vector variable, the
maximum number of elements should be enclosed in brackets and
appear affixed to the end of the ITEM name
(e.g. array[10]). If ITEM is not a
vector or string variable, then ITEM represents a
simple user variable.
OLIN allows a set of points to be drawn using the
cursor. Points may be added or removed by locating the cursor
at a desired point and selecting the key `A' (Add) or `D' (Delete)
or may terminate the command with the key `X' (eXit). The points
are stored in the XCOLUMN and
YCOLUMN arrays and may be
redrawn by subsequent calls to this command. If the optional
parameter N is given, it is used as the number of
points in the previous call to this command. To initialize the
command, set N to 0. By default, N
is set to the current number of points in the most recent call
to the XCOLUMN
and YCOLUMN commands. On
return, the cursor points are returned in the order they were
added (unlike the command NCURSE).
K.
PALETTE sets the current image color array to a
known look up table (LUT). The argument K specifies
which palette is loaded and legal values are displayed below.
If K is not associated with a legal palette value,
a warning is issued and the palette remains unchanged. The
value of K can be negative in which case, the
absolute value of K is used and the sense of the LUT
is reversed.
NOTE: Not all devices have color LUTs so this
command may have no effect on them. Whenever a device is
changed, the palette resets to the default.
K Palette set to...
-------------------------------
0 : Background to Foreground (default).
1 : Gray scale.
2 : A rainbow.
3 : Heat scale.
4 : IRAF scale.
5 : AIPS scale.
6 : PGPLOT scale.
7 : Saoimage A scale.
8 : Saoimage BB scale.
9 : Saoimage HE scale.
10 : Saoimage I8 scale.
11 : DS scale.
12 : Cyclic scale.
The optional parameter LEV may be provided to
specify the number of levels into which to squeeze the palette.
If LEV is not present (or is negative), then the
number of levels is not changed. If LEV is present
and set to 0, the number is reset to the maximum range for the
current device. If LEV is present and positive,
the number of color levels is set to this value.
PANEL makes the current plot location panel
K, where there are NX panels across
and NY panels vertically. The direction the panels
run depends on the sign of K. If K is
positive, then the panels are counted across from the lower left
and upwards (K = 1 specifies the first panel). If
K is negative, then the panels are counted across
from the upper left and downwards. PANEL retains a
copy of the VIEWPORT coordinate
system that is present when PANEL is first called.
To reset to those values, use the command panel 1 1 1;
this will reset the plot location to the previous
VIEWPORT area (this is also
done automatically every time the current device is changed).
Be sure to also call panel 1 1 1 prior to changing
the plot location with any other
VIEWPORT command! The
separation between adjacent panels is controlled by the value of
EXPAND as well as by the user
variables XSUBMAR and YSUBMAR (see the
SUBMARGIN command for more
details on these variables). If either NX or
NY is negative, then the gap between the subpanels in
that direction is removed. The absolute value of NX
and NY is always used to determine the number of subpanels.
PAPER changes the size of the view surface to a
specified width (inches) and aspect ratio (height/width). This
command should only be used immediately after a call to the
DEVICE command.
N of the current data file.
PCOLUMN reads column N from the data
file as the values of a symbol array. The data read by
PCOLUMN is used by the commands
POINTS and
BIN (as well as others) to
represent additional data information.
PHARD allows the commands in macro xxx
(or the commands in the command buffer) to be spooled to an
alternative device. The one required argument DEVNAME
is the name of the alternative device (see the command
DEVICE). If no other
arguments are present, then the commands in the command buffer
are played back (see the command
PLAYBACK);
otherwise, the named macro (xxx) is called (with
any further arguments on the command line used as input arguments
to the named macro). If the named device is a hardcopy device, the
HARDCOPY command is automatically
executed at the end of the playback. Finally, the current device
is set to the device that was present when this command was called.
xxx or commands in the command buffer.
PLAYBACK executes the macro xxx without
storing the commands in the command buffer. With an argument of
BUFFER (or no argument),
PLAYBACK replays all commands in the command buffer.
The optional arguments (args) are passed to the macro.
PLOTFIT uses the parameters from the most recent
call to FIT to display a smooth
curve. The optional parameters X1 and X2
can be used to limit the X-range to be plotted. They default to
the full range of the window. The other optional parameter is
the STEP size of the plot. It provides a means to
make the plot smoother or more coarse. The STEP
defaults to the mean of the difference between data in the
most recent call to the XCOLUMN
command.
(x,y).
POINTS draws points of the current style (see the command
SYMBOL) and size (see the command
EXPAND) at the coordinates read by the
commands XCOLUMN and
YCOLUMN.
The command PCOLUMN may be used to
specify a SYMBOL corresponding to
each (x,y) point plotted. The format of the data read by the
PCOLUMN command is the same as the
argument for the SYMBOL command,
except that an optional fractional part may be added to each symbol.
If the entry has a fractional part, it is treated as an expansion
factor (fractional parts less than 0.01 gives the default expansion).
For example, an entry of 93.5 in a point column is the same as
symbol 93,
expand 0.5.
If the optional argument K is present, the command
ECOLUMN may be used to specify a
color corresponding to each (x,y) point plotted. Each item of
data read by ECOLUMN corresponds
to a color index.
POLY will draw a closed polygon based on the data
from the most recent call to the
XCOLUMN and
YCOLUMN commands.
POLY will draw the polygon according to the
graphical characteristics such as
FILL and
COLOR.
Also see the command RECT.
STR at the current location.
PUTLABEL writes a string at the current cursor
location with rotation and size specified by the
ANGLE and
EXPAND commands
(exactly like LABEL).
The label is justified with respect to the current
location according to the argument JUST: 0 for left
justified; 0.5 for centered justified; and 1 for right justified.
If JUST is negative, the cursor is activated and the
position of the cursor when any key is struck is used as the
current location and the absolute value of JUST is
used to determine the string justification.
NOTE: Because -0 will be interpreted as +0 by the
string parser, use something like -0.001 for left justification
when using the cursor to locate the position.
QUARTER is a short cut to selecting a quadrant of
the current image. Rather than determining pixel ranges and
then calling SUBIMAGE,
QUARTER allows the user to quickly set the
corresponding pixel range. If the optional parameter N
is present and set to 1, QUARTER selects the lower
left quadrant; set to 2, the lower right; 3, the upper left;
and 4, the upper right. QUARTER, with any other
value for N or if no argument is present, selects
the inner quarter of the current image.
RANGE permits a way to limit the data used by the
FIT command. By default, the
FIT command uses all the data read by the most
recent call to the XCOLUMN
and YCOLUMN commands.
Specifying the limits in one direction restricts which data
will be used by the FIT command.
If the limits in either direction are equal, then the fit is
unbounded in that direction.
READ reads plot commands from a file and places
them in the command buffer. Commands are not executed and macros
are ignored. To execute the commands, see the command
PLAYBACK; to define macros,
see the commands DEFINE and
MACRO.
RECT is like the command
POLY but draws a
rectangle bordered by the World (user) coordinate vertices
(XMIN, YMIN) and (XMAX, YMAX).
RECT uses the current
fill, line style, and
line color characteristics.
RESET executes a full reset of graphics state of the
current plotting device. The coordinate transformation matrix is
reset to the default value (see the command
TRANSFER); the current
angle is set to 0 (see the command
ANGLE); the
tick mark interval and the number of minor tick marks is reset to 0
(see the command TICKSIZE); the
image transfer function is reset to linear (see the command
ITF); the text background color index
is set to transparent (see the command
BGCI); and the
color, expand, fill, font, line style, and line width are all set
to 1 (see the commands COLOR,
EXPAND,
FILL,
FONT,
LSTYLE, and
LWIDTH). Finally, the Palette
(see the command PALETTE) is
reset to the default palette and the number of halftone levels is
reset to the maximum range possible for the current device.
RGB sets the color representation of color index
K to the Red-Green-Blue values. The range of values
for the color value inputs are [0 - 1], inclusive. If only the
first two arguments are present, the RED value is
also used to set the GREEN and BLUE values
(useful when creating just a gray scale).
If K is larger than the maximum color index of the
device (use the command 'echo cmin cmax'
to display the color index range), then this call is ignored.
SCALE allows the viewport (device) size scale to be
set based on the range of the World (user) coordinate range. The
viewport is changed to the World range divided by the input scale
factor (i.e. X and Y are in World units h
per desired unit). The optional parameter K specifies
the desired conversion the two scale parameters will be performing
and scales as shown below:
K X and Y are dimensioned as...
---------------------------------------------------------------
0 : World (user) units per normalized device coordinate.
1 : World units per inch.
2 : World units per mm.
3 : World units per pixel.
If K is not present on the command line, then it is
set to 2. The value of Y may be omitted, in which
case it is set to the same value as X. However,
if a value other than K = 2 is desired, both
X and Y MUST be present. If K
is not one of the above accepted values, no conversion is performed.
Also, if either X or Y are less than
or equal to 0, no conversion is performed. As an example,
if the limits of the current plot are 0 - 10 in the x-direction and
0 - 12 in the y-direction, scale 2 3 1 will produce
a viewport region 5x4 inches in size. Hence, it is possible to
produce a viewport larger than the view size.
V to result of EXPRESSION.
SET sets the symbolic variable V to the
result from evaluating the statement EXPRESSION.
V is a string variable if it is enclosed in
double quotes. If V is a string variable, then
EXPRESSION represents the value to assign to the
variable (Example: 'set "print" lpr -Pps'). For
user and vector variables, EXPRESSION may be a
simple syntax statement that will be evaluated. Precedence in
the expression is ALWAYS left to right with the inner most set
of parenthesis evaluated first. Hence
(5 * 3 + 2) != (2 + 3 * 5) but ((5 * 3) + 2)
does equal (2 + (3 * 5)). Currently, a maximum of
20 nested levels of parenthesis is permitted. Also note that a
set of parenthesis is understood to mean "()", "[]", or "{}".
At the most basic level, EXPRESSION may just be an
item that is either a number, a pre-defined user variable, or a
vector element. More complex EXPRESSION's may be
generated using the operators and functions listed below. If
an item begins with '-', it is treated as a unary minus sign.
The current defined operations that act on two variables are:
+ add | / divide | max maximum - subtract | % modulo divide | min minimum * multiply | \ integer divide | ** exponentiation == equal to | > greater than | >= greater than or equal != not equal to | < less than | <= less than or equal || logical OR | && logical AND | ^ logical XORNote that
min and max are used as
(a min b) and (a max b). Also, note
that logical operations return 1 if true; 0 if false.
Current pre-defined functions (i.e. f(x)) are:
sqrt(x) square root | abs(x) absolute value
int(x) integer truncation | nint(x) nearest int
ln(x) natural logarithm | log(x) base-10 logarithm
exp(x) base-e antilogarithm | log10(x) base-10 logarithm
sin(x) sine in radians | sind(x) sine in degrees
asin(x) arcsine in radians | asind(x) arcsine in degrees
The four types of sin functions apply just as well for the
four functions of cos and tan.
Note that either log(x) or log10(x)
may be used for the log base 10. Many of the symbolic and user
variables are displayed using the SHOW
command, where symbolic names are displayed in CAPS. All other
variables can be displayed using the
ECHO command. All of the user
variable and vectors can then be used as arguments to any other
command.
NOTE: The macro arguments ($1, $2, ...) may be redefined using
this command but only if the macro argument is a numeric user variable.
SHOW lists the values of some the symbolic and user
variables, including the current location and plot region limits
in World (user) and Viewport (device) coordinates, the value of
the expansion and angle variables, the line style and width, etc.
If no arguments are present, then everything below is displayed.
If the optional argument is present, then it represents a string
used to define what will be shown. The options that are currently
available are:
B : Box attributes.
C : Coordinate system information.
D : Device, Printer, and Data file information.
G : Graphical attributes.
I : Image characteristics.
R : Register variables (\0 - \20).
More than one option may be selected (e.g. 'show bci')
and unknown options are ignored. The command
ECHO may also be used to display
user variable values.
SLEVEL is used to change the TYPE and
VALUE used to scale the contour level array.
Initially, TYPE (the user string variable "LEVTYPE")
is set to A and VALUE (the user variable
SLEVEL) is set to 1.0 so that no scaling is performed.
TYPE may only be either A or P
(all other values are treated as A) and defines the
type of contour scale factor. If TYPE is P,
then scaling is done by percentage; A for absolute
scaling. VALUE represents how much the array will
be scaled. For example, slevel P 1 will multiply
each contour level by 1% of the image peak value. Likewise,
slevel A 1E-4 would multiply each contour level
by 0.0001. If the parameter VALUE is not given,
SLEVEL will not change. The contour level array
affected is defined with the commands
LEVELS or
AUTOLEVS
and is altered internally every time the command
CONTOUR is called.
STRING allows certain string variables to be
redefined using data in an external file. STRING
reads one line (see the commands DATA
and LINES) and assigns the string
starting with word W1 and ending with W2
to the string variable NAME. If W1 is
omitted or set to 0, the entire line is assigned. If W1
is greater than 0, it represents the starting word of the
assignment. If W2 is not present, it is set to the
value of W1. If W2 is set to 0, it
corresponds to the end of the line; if it less than zero, the
absolute value represents the number of words to read; if it
is greater than zero, it specifies the last word to read.
Currently, the pre-defined string variables are: XBOX and YBOX
(which are the default X and Y arguments for a call to the
command BOX and are initially
set to "BCNST" and "BCNSTV", respectively); PRINT (which is
the default print command to spool a plot when the command
HARDCOPY or
PHARD is used); and
HELPFILE (which is the full name of the help file). Other
pre-defined string names include XHEADER and YHEADER (see
the command HEADER) and LEVTYPE
(see the command SLEVEL). New
string variables may be defined using the
NEW command, released with the
command FREE, and may also be
assigned to using the SET command.
SUBIMAGE allows the user to specify the indices
of a subimage read by the IMAGE
command. When IMAGE reads in
a new image, the minimum values are set to 1 and the maximum
values are set to the number of pixels in the X and Y directions
(user variables NX and NY). Use this command to select a subportion
of the image by entering the starting and ending pixels of
interest. Using the command HEADER
after the command SUBIMAGE will
reset the limits of the plot region (World coordinates) to the
entire subimage region selected.
SUBMARGIN may be used to fix the gap size between
individual frames when using the command
PANEL. The gap between
individual panels is controlled by the user variables
XSUBMAR and YSUBMAR (which are initially set to 2 in character
height units). This command is a convenience function to
facilitate setting these variables. The arguments XMARG
and YMARG are used to set each of the two user variables.
If this command is called with only one argument, it is used to
set both XSUBMAR and YSUBMAR.
N.
SYMBOL causes points to be drawn as the symbol
N, where N refers to the graph marker
or a Hershey symbol number. The symbol number corresponds to
the type of symbol drawn. If the symbol number is -1, it
draws a dot of the smallest possible size. If the symbol number
is between 0 and 31, it corresponds to a set of pre-defined symbols;
between 33 and 127, it corresponds to the ASCII character in the
currently selected font; and larger than 127, corresponds to the
Hershey symbol of the same number.
BOX command.
TICKSIZE determines tick intervals for the command
BOX. The argument NXSUB
refers to the number of intervals between major tick marks on
the X-axis and XTICK refers to the interval between
large ticks in World (user) coordinates. If XTICK
or NXSUB are 0, the box routine will supply it's
own intervals according to the World coordinate limits (at
least 3 major tick marks). Likewise for NYSUB and
YTICK, except for the Y-axis. Setting
NXSUB or NYSUB to 1 will inhibit any
minor tick marks regardless of the arguments to the
BOX command.
TRANSFER specifies the coordinate transformation
between indices I and J of the image array and World (user)
coordinates. All two dimensional plot commands (for example,
CONTOUR or
HALFTONE) require a
coordinate transformation function to place the image on the
plot surface. The World coordinates (X, Y) of the array point
(I, J) are related by:
X = T1 + (T2 * I) + (T3 * J)
Y = T4 + (T5 * I) + (T6 * J)
Usually T3 and T5 are zero unless
the coordinate transformation involves a rotation or sheer.
The default transformation is (0, 1, 0, 0, 0, 1). Calling
TRANSFER with no arguments resets the array to
these default values. Usually, the command
HEADER is used to set the
transformation matrix.
VECTOR draws a vector field as a number of arrows.
The tails of the arrows lie at points (x,y) read by
XCOLUMN and
YCOLUMN, the lengths of the
arrows "r" are read by PCOLUMN
and the direction of the arrow (counter-clockwise from +X in
degrees) is read with ECOLUMN.
See the command ARROW for a
description of the optional parameters ANGLE and
VENT.
NOTE: The use of PCOLUMN
in this context requires SYMBOL
to be re-executed before plotting points.
BOX will draw its grid).
Vectors and points are truncated at the edge of this plot region.
VIEWPORT specifies (in normalized device coordinates)
where the plot region is located. Viewport arguments for this
command range from 0 to 1, inclusive, in each direction for all
devices. Note that the command VSTAND
is called to reset the Viewport coordinates every time a new
device is opened.
VSIZE specifies (in inches) where the plot region
is located.
See also the VIEWPORT command.
VSTAND defines the standard viewport scale.
Currently, this is a box with margins on each side of about
4 character heights. This command is executed every time a
new device is chosen.
See also the VIEWPORT and
VSIZE commands.
WEDGE illustrates the range of values drawn by
the halftone command. The SIDE argument is
used to specify the size and orientation of the wedge.
The parameter SIDE must be either
`B', `L', `T', or `R' to specify the Bottom, Left, Top, or Right
side of the viewport. The DISP argument specifies
the displacement from the frame edge (in character height
units). If DISP is negative, then the wedge is
drawn inside the viewport. The parameter THICK
is the thickness of the wedge (in character height units).
The optional arguments MIN and MAX
allow the user to specify the intensity range of the wedge.
By default, MIN and MAX are the
values used by the most recent call to the
HALFTONE command.
Providing the values of MIN and MAX
will cause WEDGE to display a different range
of intensities when labeling the wedge box. The optional
argument BOXARG permits the user to control how
the box around the wedge is drawn (or omit it altogether).
By default, a simple box is drawn setting BOXARG
to BCSTN/M (depending on the orientation); to eliminate the box,
set BOXARG to 0 (for more information on permitted
box arguments, see the BOX command).
The arguments from the most recent call to the
TICKSIZE command are used
to draw a box around the wedge and numerically label it.
To use the optional BOXARG argument, the
MIN and MAX arguments must be provided.
WINADJ changes the World (user) limits and
adjusts the viewport so that the World coordinate scales are
equal in x and y. If the four optional parameters are present,
they are used as the new World coordinate values; otherwise,
the minimum and maximum values of the
XCOLUMN and
YCOLUMN arrays are used.
Typical usage is (after an image is loaded) to rescale the
viewport so that the image has the proper aspect ratio.
For example, using the command 'winadj 0 nx 0 ny'
after the IMAGE command BUT
before the HEADER command
will produce square pixels.
xxx to file "fspec".
WRITE the commands making up a macro to a file.
If the macro name XXX given is all,
all macros currently defined and the entire command buffer
(BUFFER) are written to the
file. If the macro name XXX is macros,
then only the currently defined macros are written to the file
(i.e. the command buffer BUFFER
is not written). Otherwise, XXX represents a list
of macro names to be written in the output file.
NOTE: This command will OVERWRITE any currently existing file.
N of the current file.
XCOLUMN reads column N from the
data file as the values of the X coordinates of the data points.
STR centered under the X axis.
XLABEL writes a string centered under the
X axis drawn by the command BOX.
Also see the command MTEXT.
N of the current file.
YCOLUMN reads column N from the
data file as the values of the Y coordinates of the data points.
STR centered left of the Y axis.
YLABEL writes a string centered left of the Y axis
drawn by the command BOX. Also
see the command MTEXT;
especially if the displacement of the text is insufficient to
avoid the axis numbers.