% @(#)draw_rect.hlq	13.1.1.3 (ESO-IPG) 11/27/98 10:26:30 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      draw_rect.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, DRAW/RECTANGLE
%.PURPOSE    On-line help file for the command: DRAW/RECTANGLE
%.VERSION    1.0  03-MAY-1984 : Creation, KB
%.VERSION    1.1  23-JUL-1991 : Update, KB
%----------------------------------------------------------------
\se
SECTION./RECT
\es\co
DRAW/RECTANGLE						26-NOV-1998  KB
\oc\su
DRAW/RECTANGLE [in_spec] [coord_ref] [draw_opt] [intens] [nocurs] [key_flag]
	draw rectangles in the overlay channel
\us\pu
Purpose: 
           Draw rectangles in the overlay channel.
\up\sy
Syntax:  
           DRAW/RECTANGLE [in_spec] [coord_ref] [draw_opt] [intens] [nocurs]
                       [key_flag]
\ys\pa
           in_spec = input specification for lower left and upper right corner
                of the rectangle;
\\
                (a) CURSOR if coordinates 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 the rectangle;
\\
                (d) name of integer keyword holding the coords, max. 40 values,
                    i.e. 10 rectangles, 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  rectangle;
\\
                defaulted to N, also any "strange" input is interpreted as "N" !
\ap\pa
           intens = color of drawing, rotation angle (in degrees) 
\\
                the rectangle 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 each rectangle;
\\
                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 corners for
                up to 10 rectangles, the last coord. must be followed by a -1;
\\
                defaulted to N
\ap\sa
See also:
           DRAW/LINE, DRAW/CIRCLE, DRAW/ELLIPS, DRAW/SLIT, 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).
\\
           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 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 or to exit.
\\
           Due to the redrawing of the cursor rectangle the underlying 
           rectangle will not have immediately the desired color, but that
           will be corrected, once you exit from the command.
\on\exs
Examples:
\ex
           DRAW/RECTANGLE
             Use cursor rectangle to define corners and draw a white rectangle.
\xe\ex
           DRAW/RECTANGLE coords F F 3,45.
             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 rectangles with
             red color;
\\
             finally rotate them by 45 degrees counter-clockwise around their 
             center.
\xe\ex
           DRAW/RECTANGLE 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/RECTANGLE 200,200,300,300 
             Draw a rectangle with lower left corner at screen pixel (200,200)
             and upper right corner at (300,300).
\xe\ex
           DRAW/RECTANGLE 0.4,0.4,0.6,0.6
             Draw a rectangle with lower left corner at screen pixel (200,200)
             and upper right corner at (300,300), if display size = 500 x 500.
\xe\ex
           DRAW/RECTANGLE 200,200,220,220 ? ? erase
             Erase any drawn rectangle with lower left corner at screen pixel
             (200,200). Note, that the size does not matter, only the offset.
             Thus, the rectancle of the example above would be erased.
\xe \sxe