idlastro / TV Display Procedures: TVCIRCLE

[Source code]

NAME
TVCIRCLE
PURPOSE
Draw circle(s) of specified radius at specified position(s) 
EXPLANATION
If a position is not specified, and device has a cursor, then a circle
is drawn at the current cursor position.    By default, TVCIRCLE now
(since Jan 2012) assumes data coordinates if !X.crange is set.
CALLING SEQUENCE
TVCIRCLE, rad, x, y, color, [ /DATA, /FILL, _EXTRA  =  ]         
INPUTS
RAD - radius of circle(s) to be drawn, positive numeric scalar
OPTIONAL INPUT
X - x position for circle center, vector or scalar
Y - y position for circle center, vector or scalar
         If X and Y are not specified, and the device has a cursor, 
         then program will draw a circle at the current cursor position
COLOR -  color name or intensity value(s) (0 - !D.N_COLORS) used to draw
         the circle(s).   If COLOR is a scalar then all circles are drawn
         with the same color value.   Otherwise, the Nth circle is drawn
         with the  Nth value of color.  See cgCOLOR() for a list of color
         names.  Default = 'opposite' (i.e. color opposite the 
         background).   
OPTIONAL KEYWORD INPUTS
/DATA - if this keyword is set and non-zero, then the circle 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).    TVCIRCLE will
       internally convert to device coordinates before drawing the
       circle, in order to maintain optimal smoothness.    The default
       is to assume data coordinates if !X.CRANGE is set.    Force
       device coordinates by setting DATA = 0 or /DEVICE
/DEVICE - If set, then force use of device coordinates..
/FILL  - If set, fill the circle using cgCOLORFILL
        Any keyword recognized by cgPLOTS (or cgCOLORFILL if /FILL is 
        set) is also recognized by TVCIRCLE.   In particular, the color,
        linestyle, thickness and clipping of the circles are controlled
        by the  COLOR, LINESTYLE, THICK and NOCLIP keywords.  (Clipping
        is turned off by default, set NOCLIP=0 to activate it.)
        If /FILL is set then available keywords are LINE_FILL and 
        FILL_PATTERN. 
OUTPUTS
None
RESTRICTIONS
(1) Some round-off error may occur when non-integral values are 
    supplied for both the radius and the center coordinates
(2) TVCIRCLE does not accept /NORMAL coordinates.
(3) TVCIRCLE always draws a circle --- even when in data coordinates 
    and the X and Y data scales are unequal.    (The X data scale is 
    used to define the circle radius.)     If this is not the behaviour
    you want, then use TVELLIPSE instead.
EXAMPLE
(1) Draw circles of radius 9 pixels at the positions specified by 
    X,Y vectors, using double thickness lines
    IDL> tvcircle, 9, x, y, THICK = 2
    Now fill in the circles using the LINE_FILL method
    IDL> tvcircle, 9, x, y, /FILL, /LINE_FILL
METHOD
The method used is that of Michener's, modified to take into account
the fact that IDL plots arrays faster than single points.   See
"Fundamental of Interactive Computer Graphics" by Foley and Van Dam"
p. 445 for the algorithm.
REVISON HISTORY
Original version   written by B. Pfarr  STX   10-88 
Major rewrite adapted from CIRCLE by Allyn Saroyan   LNLL
Wayne Landsman   STX     Sep. 91
Added DATA keyword   Wayne Landsman  HSTX    June 1993
Added FILL keyword.  R. S. Hill, HSTX, 4-Nov-1993
Always convert to device coords, add _EXTRA keyword, allow vector
colors.   Wayne Landsman, HSTX,  May 1995
Allow one to set COLOR = 0,   W. Landsman, HSTX, November 1995
Check if data axes reversed.  P. Mangifico, W. Landsman  May 1996
Use strict_extra to check input keywords W. Landsman  July 2005
Update documentation to note NOCLIP=0 option W.L.  Oct. 2006
Make all integers default to LONG  W. Landsman  Dec 2006
Use Coyote Graphics procedures W. Landsman Feb 2011
Default to data coordinates if !X.crange present  WL Jan 2012
Add /DEVICE coords, fix Jan 2012 update.   Mar 2012