TVCIRCLE
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