BUGS · SEE_ALSO

## NAME

pvector -- plot an arbitrary vector in a 2D image

## USAGE

`pvector image x1 y1 x2 y2`

## PARAMETERS

- image
- Input image containing data to be plotted.

- x1, y1
- Starting coordinates of the vector to be plotted.

- x2, y2
- Ending coordinates of the vector to be plotted.

- xc, yc
- The center coordinates of the vector to be plotted if the position
angle
*theta*is defined.

- width = 1
- Number of pixels perpendicular to the vector to average.

- 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
*xc*, and*yc*parameters must be specified instead of the starting and ending coordinates as in examples 3 and 4.

- length = INDEF
- The length of the vector to be plotted if
*theta*is defined. The default is to plot the vector from one edge of the frame to another.

- boundary = constant
- The type of boundary extension. The boundary extension options are:
- nearest
- Use the value of the nearest boundary pixel.

- constant
- Use a constant value.

- reflect
- Generate a value by reflecting around the boundary.

- wrap
- Generate a value by wrapping around to the opposite side of the image.

- constant = 0.
- The constant for constant valued boundary extension.

- 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
*out_type*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.

- 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.

- wx= 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.

- vx= 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.

- pointmode = no
- Plot individual points instead of a continuous line?

- marker = "box"
- If
**pointmode**= yes, the marker drawn at each point is set with this parameter. The choices are "point", "box", "plus", "cross" and "circle".

- szmarker = 0.005
- The size of the marker drawn when
**pointmode**= yes.

- logx = no, logy = no
- Draw the x or y axis in log units, versus linear?

- xlabel = "", ylabel = ""
- The x-axis and y-axis labels.

- 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.

- majrx = 5, minrx = 5, majry = 5, minry = 5
- The number of major and minor divisions along the x or y axis.

- round = no
- Round axes up to nice values?

- fill = yes
- Fill the output viewport regardless of the device aspect ratio?

- append = no
- Append to an existing plot?

- device = "stdgraph"
- Output device.

## 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 *vec_output*
and *out_type*
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 exceede 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 **append**
is enabled, previous values for **box**
,
**fill**
, **round**
, the plotting viewport (**vx1**
, **vx2**
,
**vy1**
, **vy2**
), and the plotting window (**wx1**
, **wx2**
,
**wy1**
, **wy2**
) are used.

If the plotting viewport was not set by the user, **pvector**
automatically sets a viewport centered on the device. The default value
of **fill**
= yes means the plot spans equal amounts of NDC space in
x and y. Setting
the value of **fill**
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 **fill = no**
, 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 *pvector*
appears extended in the x direction unless **fill**
= no.

## EXAMPLES

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

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

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

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

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.

cl> pvector crab.5009 0. 0. 0. 0. 256. 256. theta=45. or cl> pvector crab.5009 xc=256. xc=256. theta=45.

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

cl> pvector crab.5009 0. 0. 0. 0. 256. 256. theta=45. length=100. or cl> pvector crab.5009 xc=256. xc=256. theta=45. length=100.

## 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).

## BUGS