.help pvector Oct91 plot
.ih
NAME
pvector -- plot an arbitrary vector in a 2D image
.ih
USAGE
pvector image x1 y1 x2 y2
.ih
PARAMETERS
.ls image
Input image containing data to be plotted.
.le
.ls x1, y1
Starting coordinates of the vector to be plotted.
.le
.ls x2, y2
Ending coordinates of the vector to be plotted.
.le
.ls xc, yc
The center coordinates of the vector to be plotted if the position
angle \fItheta\fR is defined.
.le
.ls width = 1
Number of pixels perpendicular to the vector to average.
.le
.ls theta = INDEF
The postion angle of the vector to be plotted measured counter-clockwise
from the positive x axis. Theta must be between 0.0 and 360.0 degrees.
If theta is specified, the \fIxc\fR, and \fIyc\fR parameters
must be specified instead of the starting and ending coordinates
as in examples 3 and 4.
.le
.ls length = INDEF
The length of the vector to be plotted if \fItheta\fR is defined. The
default is to plot the vector from one edge of the frame to another.
.le
.ls boundary = constant
The type of boundary extension. The boundary extension options are:
.ls nearest
Use the value of the nearest boundary pixel.
.le
.ls constant
Use a constant value.
.le
.ls reflect
Generate a value by reflecting around the boundary.
.le
.ls wrap
Generate a value by wrapping around to the opposite side of the image.
.le
.le
.ls constant = 0.
The constant for constant valued boundary extension.
.le
.ls vec_output = ""
File or image name if output vector is desired.  If this parameter is
non-null, then the computed vector will be output to the named file of
the type specified by the \fIout_type\fR parameter.  If set to STDOUT
or STDERR, a listing of the pixels (i.e. text format) will be output to 
either of these streams.  Plotting is disabled if vector output is selected.
.le
.ls out_type = "text"
Type of output format (image|text). If an image is created, then a new
header keyword, "VSLICE", will be appended to the new image describing
the endpoints of the vector, the width, and the parent image name. The 
parent image header will be copied to the new image.
.le
.ls wx1 = 0., wx2 = 0., wy1 = 0., wy2 = 0.
The range of world coordinates to be included in the plot.  If the
range of values in x or y is zero, the plot is automatically scaled from the
minimum to maximum data values along the degenerate axis.
.le
.ls vx1 = 0., vx2 = 0., vy1 = 0., vy2 = 0.
NDC coordinates (0-1) of the device plotting window.  If not set by user,
a suitable viewport which allows sufficient room for all labels is used.
.le
.ls pointmode = no
Plot individual points instead of a continuous line?
.le
.ls marker = "box"
Marker or line type to be drawn.  If \fBpointmode\fR = yes the markers are
"point", "box", "cross", "plus", "circle", "hebar", "vebar", "hline",
"vline" or "diamond".  Any other value defaults to "box".  If drawing lines,
\fBpointmode\fR = no, the values are "line", "lhist", "bhist".  Any other
value defaults to "line".  "bhist" (box histogram) draws lines to the
bottom of the graph while "lhist" does not.  In both cases the
horizontal histogram lines run between the half way points (reflected
at the ends).
.le
.ls szmarker = 0.005
The size of the marker drawn when \fBpointmode\fR = yes.
.le
.ls logx = no, logy = no
Draw the x or y axis in log units, versus linear?
.le
.ls xlabel = "", ylabel = ""
The x-axis and y-axis labels.
.le
.ls title = "imtitle"
Title for plot.  If not changed from the default, the title string from the
image header, appended with the vector endpoints, is used.
.le
.ls majrx = 5, minrx = 5, majry = 5, minry = 5
The number of major and minor divisions along the x or y axis.
.le
.ls round = no
Round axes up to nice values?
.le
.ls fill = yes
Fill the output viewport regardless of the device aspect ratio?
.le
.ls append = no
Append to an existing plot?
.le
.ls device = "stdgraph"
Output device.
.le
.ih
DESCRIPTION
Plot an arbitrary vector of data from an image.  The vector can be
specified by either defining the two endpoints of the vector or 
by specifying the center position, length and position angle of the vector.
The user can specify
the plot size and placement, the scaling and labeling of axes.  Data can be
plotted as a continuous line or individual points with a specified marker.
Optionally, the computed vector may be output to a named image or text file
(as specified by the \fIvec_output\fR and \fIout_type\fR parameters).

The vector is extracted as a straight line between the given
coordinates, sampled at a spacing along that line equivalent to that
between adjacent pixels in the x or y direction (e.g. the length of a
diagonal endpoint vector from a square image is n*sqrt(2)).
It is possible to specify an averaging width
which determines how many pixels perpendicular to the vector are averaged.
This averaging window is centered
on the vector pixel.  When this window is greater than one pixel, it
is possible that the extraction process might try to exceed the
image boundary, in which case the specified type of boundary extension
is employed. The extraction algorithm uses bilinear interpolation to
evaluate points at non-integral pixel positions.

If \fBappend\fR is enabled, previous values for \fBbox\fR,
\fBfill\fR, \fBround\fR, the plotting viewport (\fBvx1\fR, \fBvx2\fR, 
\fBvy1\fR, \fBvy2\fR), and the plotting window (\fBwx1\fR, \fBwx2\fR, 
\fBwy1\fR, \fBwy2\fR) are used.

If the plotting viewport was not set by the user, \fBpvector\fR 
automatically sets a viewport centered on the device.  The default value
of \fBfill\fR = yes means the plot spans equal amounts of NDC space in
x and y.  Setting
the value of \fBfill\fR  to "no" means the viewport will be adjusted so 
that the square plot will span equal physical lengths in x and y
when plotted.  That is, when \fBfill = no\fR, a unity aspect ratio is 
enforced, and plots
appear square regardless of the device aspect ratio.  On devices with non 
square full device viewports (e.g., the vt640), a plot drawn by \fIpvector\fR
appears extended in the x direction unless \fBfill\fR = no.

.ih
EXAMPLES
1. Plot from the lower left to upper right of 512 square image crab.5009.

.nf
    cl> pvector crab.5009 1. 1. 512. 512.
.fi

2. Plot the same vector but with the sampling width = 3.

.nf
    cl> pvector crab.5009 1. 1. 512. 512. width=3
.fi

3. Plot a vector in same image with center position 256, 256, and a position
angle of 45 degrees which extends from one edge of the frame to the other.

.nf
    cl> pvector crab.5009 0. 0. 0. 0. 256. 256. theta=45.
.fi    

or

.nf
    cl> pvector crab.5009 xc=256. xc=256. theta=45.
.fi

4. Plot the above vector with a length of 100 pixels.

.nf
    cl> pvector crab.5009 0. 0. 0. 0. 256. 256. theta=45. length=100.
.fi

or

.nf
    cl> pvector crab.5009 xc=256. xc=256. theta=45. length=100.
.fi

.ih
TIME REQUIREMENTS
It takes approximately 6.7 cpu seconds to compute and plot the twenty
pixel wide diagonal of a 512 square real image. (VAX/VMS 750 with fpa).
.ih
BUGS
.ih
SEE ALSO
prow, pcol, prow, pcols
.endhelp