% @(#)draw_elli.hlq	19.1 (ESO-IPG) 02/25/03 14:03:17 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      draw_elli.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, DRAW/ELLIPS
%.PURPOSE    On-line help file for the command: DRAW/ELLIPS
%.VERSION    1.0  03-MAY-1984 : Creation, KB
%.VERSION    1.1  23-JUL-1991 : Update, KB
%----------------------------------------------------------------
\se
SECTION./ELLI
\es\co
DRAW/ELLIPS						25-NOV-1998  KB
\oc\su
DRAW/ELLIPS [in_spec] [coord_ref] [draw_opt] [draw_specs]
            [nocurs] [key_flag] [arc_defs]
	draw ellipses in the overlay channel
\us\pu
Purpose: 
           Draw ellipses or arcs (parts of circles) in the overlay channel.
\up\sy
Syntax:  
           DRAW/ELLIPS [in_spec] [coord_ref] [draw_opt] [draw_specs]
                       [nocurs] [key_flag] [arc_defs]
\ys\pa
           in_spec = input specification for lower left and upper right corner
                of the ellipses;
\\
                (a) CURSOR if coordinates of a rectangle surrounding the 
                    required ellipse are chosen via the cursor rectangle;
\\
                (b) name of table containing coordinates
\\
                (c) x1,y1,x2,y2 defining the coords. of lower left and upper
                    right corner of a rectangle surrounding the required
                    ellipse;
\\
                (d) name of integer keyword holding the coords, max. 40 values,
                    i.e. 10 ellipses, 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;
\\
                     as frame Pixel values from columns labeled 
                     :XSTARTPIX, YSTARTPIX, :XENDPIX  and :YENDPIX 
\\
                     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 ellipses;
\\
                defaulted to N, also any "strange" input is interpreted as "N" !
\ap\pa
           draw_specs = color of drawing, rotation angle (in degrees)
\\
                the ellipse is first built up from the specs and in the
                very end rotated counter-clockwise by the rotation angle around
                its center;
\\
                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;
\\
                   the rotation angle is read from table column labeled
                   :ROTANG, if such a column exists;
\\
                defaulted to WHITE,0
\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 lower-left and
                upper-right corner of the surrounding rectangle for each
                ellipse;
\\
                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 ellipses, 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/CIRCLE, DRAW/SLIT, 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).
\\
           If coord_ref = F or P, a frame must be loaded in the displayed
           channel.
\\
           The cursor rectangle 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 ellipse or to exit.
\\
           Due to the redrawing of the cursor rectangle some parts of the
           ellipse will not have immediately the desired color, but that
           will be corrected, once you exit from the command.
\on\exs
Examples:
\ex
           DRAW/ELLIPS
             Use cursor rectangle to define corners and draw a white ellipses.
\xe\ex
           DRAW/ELLIPS coords F F red,45.
             Use values from real columns :xstart, :ystart, :xend, :yend of
             table `coords.tbl', interpret them as real world coordinates of
             the currently displayed frame and draw filled ellipses with red.
\\
             Finally rotate the ellipses counter-clockwise by 45.0 degrees
             around their center.
\xe\ex
           DRAW/ELLIPS coords P F red,45.
             As above but use values from real columns :xstartpix, :ystartpix,
             :xendpix, :yendpix of table `coords.tbl'.
\\
             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. The same applies, if a real column :rotang
             exists.
\xe\ex
           DRAW/ELLIPS 120,200,240,280 s nofill black,0 ? ? 210.,330.
             Construct an ellips in the rectangle with lower left corner
             at screen pixel (120,200) and upper right corner at (240,280).
             But only draw the arc beginning at angle of 210 deg. and ending
             at 330 deg., i.e. the lower, central arc of the ellips.
\xe\ex
           DRAW/ELLIPS 120,200,240,280 s nofill black,0 ? ? 330.,390.
             As above, but draw the righthand, central arc of the ellips.
\xe\ex
           DRAW/ELLIPS 200,200,300,300 
             Draw a fitting ellipses into the rectangle with lower left corner
             at screen pixel (200,200) and upper right corner at (300,300).
\xe \sxe
