% @(#)draw_circ.hlq	19.1 (ESO-IPG) 02/25/03 14:03:16
% @(#)draw_circ.hlq	13.1.1.3 (ESO-IPG) 11/27/98 10:26:28 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      draw_circ.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, DRAW/CIRCLE
%.PURPOSE    On-line help file for the command: DRAW/CIRCLE
%.VERSION    1.0  03-MAY-1984 : Creation, KB
%.VERSION    1.1  22-JUL-1991 : Update, KB
%----------------------------------------------------------------
\se
SECTION./CIRC
\es\co
DRAW/CIRCLE						28-NOV-1998  KB
\oc\su
DRAW/CIRCLE [in_spec] [coord_ref] [draw_opt] [draw_specs] 
            [nocurs] [key_flag] [arc_defs]
	draw circles in the overlay channel
\us\pu
Purpose: 
           Draw circles or arcs (parts of circles) in the overlay channel.
\up\sy
Syntax:  
           DRAW/CIRCLE [in_spec] [coord_ref] [draw_opt] [draw_specs] 
                       [nocurs] [key_flag] [arc_defs]
\ys\pa
           in_spec = input specification for circle, either as lower left and
                upper right corner of the circle or as center and radius;
\\
                (a) CURSOR if circle is chosen via the cursor(s);
\\
                (b1) name of table containing coordinates
\\
                (c1) x1,y1,x2,y2 defining the coords. of lower left and upper
                    right corner of a rectangle surrounding the required
                    circle, or
\\
                (c2) x1,y1,rad defining the coords. of center of circle and
                    radius of it;
\\
                    if `coord_ref' below = F, then x1,y1,x2,y2 are entered in
                    the usual Midas syntax for coordinates, the radius is in
                    screen pixels and therefore always entered as integer;
\\
                (d) name of integer keyword holding the coords of surrounding
                    rectangles; max. 40 values, i.e. max. 10 circles, 
                    see parameter 'key_flag'
\\
                defaulted to CURSOR
\ap\pa
           coord_ref = only applicable for `in_spec' option (b) and (c);
\\
                (b): F, P or S, to indicate that coordinates are read
                     as Frame (world) coordinates from columns labeled
                       :XSTART, :YSTART, :XEND and :YEND defining the coords of
                       lower left and upper right corner of a rectangle
                       surrounding the required circle, or
\\
                       :X_COORD, :Y_COORD and :RADIUS1 defining the center
                       and radius of the required circle (:RADIUS1 is always
                       interpreted as screen pixels!);
\\
                     as frame Pixel values from columns labeled
                       :XSTARTPIX, YSTARTPIX, :XENDPIX  and :YENDPIX, or
\\
                       :X_COORDPIX, :Y_COORDPIX and :RADIUS1 
\\
                     as screen pixels from columns labeled
                       :XSTART, :YSTART, :XEND and :YEND;
\\
                (c): F or S to indicate that coordinates are entered as Frame
                     related values, i.e. world coords or frame pixels (with
                     the usual MIDAS syntax)
\\
                     or directly as screen pixels
\\
                for (a) and (d) always screen pixels are used;
\\
                defaulted to S, only for (b) it is defaulted to F
\ap\pa
           draw_opt = F(ill) or N(ofill) the circle;
\\
                defaulted to N, also any "strange" input is interpreted as "N" 
\ap\pa
           draw_specs = color of drawing, defaulted to WHITE
\\
                for `in_spec' (b) only:
\\
                   the color is read from table column labeled :COLOR (real
                   column with colors as numbers, see Note below),
                   if such a column exists;
\ap\pa
           nocurs = no. of cursors to use, if you specify 1, only one cursor is
                used and you have to press ENTER twice for the center and the 
                radius of each circle;
\\
                if set to 2, a cursor circle is used; defaulted to 2
\ap\pa
           key_flag = K(ey) or N(okey) to indicate that 'in_spec' holds the
                name of an integer keyword which contains the rectangle corners
                for up to 10 circles, the last coord. must be followed by a -1;
\\
                defaulted to N
\ap\pa
           arc_defs = start-, end-angle (in degrees) of arc of circle to draw
\\
                0 deg. is along the positive x-axis and circle is increasing
                counter clockwise, i.e. 90 deg is along the positive y-axis; 
\\
                defaulted to 0,360
\ap\sa
See also: 
           DRAW/LINE, DRAW/SLIT, DRAW/ELLIPS, DRAW/RECTANGLE, DRAW/ARROW
\\
           DRAW/CROSS, DRAW/ANY
\as\no
Note: 
           The parameters may also be cross referenced via
\\
           INSPEC=, COOREF=, DROPT=, INTENS=, NOCURS= and KEY=
\\
           The following colors are supported (via name or number):
\\
           Black(1), White(2), Red(3), Green(4), Blue(5), Yellow (6),
           Magenta(7), Cyan(8).
	   In order to remove a drawn circle, use the same command with 
	   the option p4=0 
\\
           Screen pixels may be entered as absolute values (integer numbers)
           or normalized pixels (float numbers) with 0.0,0.0 the lower left
           and 1.0,1.0 the upper right corner.
\\
           If coord_ref = F or P, a frame must be loaded in the displayed
           channel.
\\
           The cursor circle is moved with the mouse and adjusted in size with
           the arrow keys. Use the ENTER and EXIT buttons on the mouse to draw
           the circle or to exit.
\\
           Setting the start+end angles in `arc_defs' only the part of the
           circle in that angle interval will be drawn.
\\
           Due to the redrawing of the cursor circle the underlying circle will
           not have immediately the desired color, but that will be corrected,
           once you exit from the command.
\on\exs
Examples:
\ex
           DRAW/CIRCLE
             Use cursor circle to define position and size and draw a white 
             circle. The radius of that circle is controlled via the arrow 
             keys of the terminal.
\xe\ex
           DRAW/CIRCLE coords F FILL red
             Use values from columns :xstart, :ystart, :xend, :yend of table
             `coords.tbl', interpret them as real world coordinates of the
             currently displayed frame and draw filled red circles.
\\
             Or use values from columns :x_coord, :y_coord and :radius1 of
             table `coords.tbl', interpret them as real world coordinates of
             of the currently displayed frame and draw the circles.
\xe\ex
           DRAW/CIRCLE coords P F red
             As above but use values from real columns :xstartpix, :ystartpix,
             :xendpix, :yendpix of table `coords.tbl' or (:x_coordpix, 
             :y_coordpix and :radius1).
\\
             If table `coords.tbl' also contains a column :color with colors
             as real numbers, these values would override the color given on
             the command line.
\xe\ex
           DRAW/CIRCLE 200,200,300,300 
             Draw a fitting circle into the rectangle with lower left corner at
             screen pixel (200,200) and upper right corner at (300,300).
\xe\ex
           DRAW/CIRCLE 256,246,25 s nofill black ? ? 210.,330.
             Construct a circle centered at the screen pixel 256,246 with a
             radius of 25 screen pixels.
             But only draw the arc beginning at angle of 210 deg. and ending
             at 330 deg., i.e. the lower, central arc of the circle. 
\xe\ex
           DRAW/CIRCLE 256,246,25 s nofill black ? ? 330.,390.
             As above, but draw the righthand, central arc of the circle.
\xe\ex
           DRAW/CIRCLE @200,@200,30 f
             Draw a circle centered at the screen pixel determined by the
             frame pixel (200,200) of the displayed image with a radius of
             30 screen pixels.
\xe\ex
           DRAW/CIRCLE @200,@200,30 f f
	     Draw the same circle as before, but fill it
\xe\ex
           DRAW/CIRCLE @200,@200,30 f f	0
	     Remove the circle which was plotted by the previous example        
\xe \sxe
