idlastro / TV Display Procedures: TVBOX

[Source code]

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