% @(#)plot_gray.hlq	19.1 (ESO-IPG) 02/25/03 14:03:35 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      plot_gray.hlq
%.AUTHOR     RHW, IPG/ESO
%.KEYWORDS   MIDAS, help files, PLOT/GRAY
%.PURPOSE    On-line help file for the command: PLOT/GRAY
%.VERSION    1.0  06-AUG-1987 : Creation, RHW
%----------------------------------------------------------------
\se
SECTION./GRAY
\es\co
PLOT/GRAY                                                       06-AUG-1987 RHW
\oc\su
PLOT/GRAY frame [coord_str] [x_sc,y_sc[,x_off,y_off]] [gray_lev] 
                [sm_par] [gray_ness] [gray_opt]
	plot gray scale map of 2-dim. image with smoothing option
\us\pu
Purpose:    
            Plot gray scale map of 2-dim. image (with a smoothing option)
\up\sy
Syntax:     
            PLOT/GRAY frame [coord_str] [x_sc,y_sc[,x_off,y_off]] [gray_lev] 
                      [sm_par] [gray_ness] [gray_opt]
\ys\pa
            frame     = name of image file
\ap\pa
            coord_str = area to be plotted in standard MIDAS notation; see 
                        MIDAS Users Guide Volume A chapter 6. Default is the 
                        manual setting done with the command SET/GRAPHICS 
                        (if present), or the whole area.
\ap\pa
            x_sc,y_sc,x_off,y_off = scale or size in the x- and y-direction,
                        offset in the x- and y-direction. For the scaling x_sc
                        and y-sc, positive numbers are interpreted as scale
                        parameters (world units/mm), negative numbers as size
                        parameters (axis will be made sc_* mm. long). A
                        combination of a positive and negative number is
                        allowed. By default the plot fills the device area. \\
                        x_off and y_off determine the distance of the lower
                        left corner of the plot to the lower left corner of the
                        graphic device, measured in mm. By default, the plot
                        is put at the top left of the graphic device, allowing
                        space for the various labels.
\ap\pa
            gray_lev  = gray levels; in case of a continueous gray scale
                        plot two values are required (lev1,lev2); in case of
                        stepwise increment of the gray scale plot input can
                        be given as cstart:cend:cincr or lev1,lev2,lev3 or
                        any combination of these two possibilities separated
                        by a comma; defaults cut levels are the values stored
                        in the decriptor LHCUTS.
\ap\pa
            sm_par    = smoothing parameter i.e. the number of pixels "around"
                        the central pixel which define the neighbourhood of
                        that pixel. 
\\
                        Total number of pixels is then: (2*sm_par + 1)**2 
                        Only integer numbers are allowed. Default is 0
\ap\pa
            gray_ness = grayness parameter between 0.0 and 1.0; the value 1
                        gives the maximum blackness; 0 means white;
                        default is 1.0
\ap\pa
            gray_opt  = plot options to be specified as option1,option2,...;
                        possible options are:\\
                        LOG:  logarithmicaly increasing grayness;\\
                       	LIN:  linear increasing grayness (default);\\
                        STEP: stepwise gray scales;\\
                        CONT: contineously increasing gray scales;\\
                        NEG:  change sign of data points;\\
                        POS:  leave signs unchanged (default);\\
                        ABS:  take absolute values;\\
                        CUT:  intensity levels above the highest contour level
                              will be white. The default is that these levels
                              will have a grayness corresponding the highest 
                              contour level.
\ap\no
Note:       
            The coordinates for the area are optional. If one specifies a "?",
            the area will be take for the manual frame settings for the x-
            and y-axis. If a "C" is given, the window is selected interactively
            on the display screen using the cursor facilities. The cursor will
            be set on automatically, if it is not already. To pick up the
            coordinates, switch the cursors ON and press ENTER. To exit,
            switch the cursors OFF and press ENTER.
\on\see
See also:
            OVERPLOT/GRAY, SHOW/GRAPHICS, SET/GRAPHICS, PLOT/AXES, 
            PLOT/CONTOUR, OVERPLOT/CONTOUR, PLOT/VECTOR, OVERPLOT/VECTOR
\ees\exs
Examples:
\ex
            PLOT/GRAY spiral [@281,@281:@320,@320] ? 1,5
            Plot a gray scale plot of the frame spiral.bdf with default scales;
            the gray levels will be continuous in the range from pixel values
            1 to 5.
\xe\ex
            PLOT/GRAY spiral [@281,@281:@320,@320] 25.,25. 1:5 1 1. ABS,LOG
            Same as the previous example but a logarithmic scaling is done to
            the absolute values of the data points. A 3*3 box smooth is done 
            on the data before the plot is made.
\xe\ex
            PLOT/GRAY spiral C ? 1:5:0.5 ? .75 STEP
            In this case the gray levels will increase stepwise. To get the 
            plot less black the grayness parameter is set to 0.75. 
\xe \sxe
