TVBOX
Name
TVBOX
Purpose
Draw a box(es) or rectangle(s) of specified width
Explanation
Positions can be specified either by the cursor position or by
supplying a vector of X,Y positions. By default, TVBOX now
(since Jan 2012) assumes data coordinates if !X.crange is set.
Calling Sequence
TVBOX, width, [ x, y, color, /DATA, ANGLE= ,COLOR =, _EXTRA = ]
Inputs
WIDTH - either a scalar giving the width of a box, or a 2 element
vector giving the length and width of a rectangle.
Optional Inputs
X - x position for box center, scalar or vector
Y - y position for box center, scalar or vector. If vector, then Y
must have the same number of elements as X
Positions are specified in device coordinates unless /DATA is set
If X and Y are not specified, and device has a cursor, then
TVBOX will draw a box at current cursor position
COLOR - String or integer specifying the color to draw the box(es)
If COLORS is a scalar then all boxes are drawn with the same
color value. Otherwise, the Nth box is drawn with the
Nth value of color. Color can also be specified as
string (e.g.'red'). See cgCOLOR for a list of available
color names. Default = "opposite".
Outputs
None
Optional Keyword Inputs
ANGLE - numeric scalar specifying the clockwise rotation of
the boxes or rectangles.
COLOR - Scalar or vector, overrides the COLOR input parameter
Color can be specified as a string (e.g. 'red') or intensity
value. See cgCOLOR() for a list of color names.
Default = 'opposite' (i.e. color opposite the background).
/DATA - if this keyword is set and non-zero, then the box width and
X,Y position center are interpreted as being in DATA
coordinates. Note that data coordinates must be previously
defined (with a PLOT or CONTOUR call). The default
is to assume data coordinates if !X.CRANGE is set. Force
device coordinates by setting DATA = 0 or /DEVICE
/DEVICE Set this keyword to force use of device coordinates
/FILL - If set, fill the box using cgCOLORFILL
/SQUARE - If set, then a square is drawn, even if in data coordinates
with unequal X and Y axes. The X width is used for the
square width, and the Y width is ignored.
Any keyword recognized by cgPLOTS (or cgCOLORFILL if /FILL is set)
is also recognized by TVBOX.
In particular, the linestyle, thickness and clipping of the boxes
is controlled by the LINESTYLE, THICK and NOCLIP keywords.
(Clipping is turned off by default, set NOCLIP=0 to activate it.)
If /FILL is set then available keywords include LINE_FILL and
FILL_PATTERN.
Side Effects
A square or rectangle will be drawn on the device
For best results WIDTH should be odd when using the default DEVICE
coordinates. (If WIDTH is even, the actual size of the box will be
WIDTH + 1, so that box remains centered.)
Examples
(1) Draw a double thick box of width 13, centered at 221,256 in the
currently active window
IDL> tvbox, 13, 221, 256, thick=2
(2) Overlay a "slit" with dimension 52" x 2" on a previously displayed
image at a position angle (East of North) of 32 degrees. The
slit is to be centered at XC, YC and the plate scale
arcsec_per_pixel is known.
IDL> w = [2.,52.]/arcsec_per_pixel ;Convert slit size to pixel units
IDL> tvbox,w,XC,YC,ang=-32 ;Draw slit
Restrictions
Allows use of only device (default) or data (if /DATA is set)
coordinates. Normalized coordinates are not allowed
Procedures Used
cgpolygon, zparcheck
Revison History
Written, W. Landsman STX Co. 10-6-87
Modified to take vector arguments. Greg Hennessy Mar 1991
Fixed centering of odd width W. Landsman Sep. 1991
Let the user specify COLOR=0, accept vector color, W. Landsman Nov. 1995
Fixed typo in _EXTRA keyword W. Landsman August 1997
Added ANGLE keyword W.Landsman February 2000
Make sure ANGLE is a scalar W. Landsman September 2001
Don't round coordinates if /DATA is set. M. Perrin August 2005
Use STRICT_EXTRA to flag valid keywords W. Landsman Sep 2005
Check that width has only 1 or 2 elements W. Landsman August 2010
Use Coyote Graphcis W. Landsman February 2011
Added /FILL keyword W. Landsman July 2011
Default to data coordinates if !X.crange present WL Jan 2012
Added Square keyword WL. April 2012