pvector: Plot an arbitrary vector in a 2D image

Package: plot

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.

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.

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.

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

marker = "box": Marker or line type to be drawn. If pointmode = yes the markers are "point", "box", "cross", "plus", "circle", "hebar", "vebar", "hline", "vline" or "diamond". Any other value defaults to "box". If drawing lines, pointmode = 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).

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