% @(#)load_imag.hlq	13.1.1.1 (ESO-IPG) 06/02/98 18:14:21 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      load_imag.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, LOAD/IMAGE
%.PURPOSE    On-line help file for the command: LOAD/IMAGE
%.VERSION    1.0  31-JAN-1990 : Creation, KB
%.VERSION    1.1  12-JUL-1991 : update Note, KB
%.VERSION    1.2  22-JUL-1992 : add new cuts strategies, KB
%----------------------------------------------------------------
\se
SECTION./IMAG
\es\co
LOAD/IMAGE						07-MAY-1998  KB
\oc\su
LOAD/IMAGE frame_spec [chanl] [scale] [center] [cuts] [dirs] [fix]
	load image into display device
\us\pu
Purpose: 
          Load image into display device
\up\sy
Syntax:   
          LOAD/IMAGE frame_spec [chanl] [scale] [center] [cuts] [dirs] [fix]
\ys\pa
          frame_spec = frame[,1st_plane..last_plane,delay] with name of frame
              to be loaded and the first plane and last plane to load, 
              applicable if `frame' is a 3-dim image
\ap\pa
          chanl = memory channel selected for storing the image, defaulted to
              currently displayed channel;
\\
              if you load several planes of a 3-dim frame, they are usually
              loaded into the same channel;
\\
              if you use `chanl,...' as channel no. the planes will be loaded
              into chanl, chanl+1, chanl+2, ... until last plane or last
              channel is reached;
\ap\pa
          scale = xscale,yscale[,av_opt] - scaling factors in x, y and
              average option or simply scale[,av_opt] if same scaling factor
              is used in x,y;
\\
              x, yscale must be integer values and av_opt may be AVERAGE or
              MINIMUM or MAXIMUM
\\
              for scaling factors larger than 1, the image is magnified, for
              s. f. smaller than -1, the image is reduced when loaded.
\\
              for scaling the image such that it fits fully in the currently
              active display window, use scale=full
\\
              For image reduction (s.f. < -1), rows/columns are just omitted,
              unless the average option is added:
\\
              for av_opt = AV, the average over the subwindow with
              -xscale pixels and -yscale lines is taken;
\\
              for av_opt = MIN or MAX the minimum or maximum in the subwindow
              is taken.
\\
              Default = 1,1 .
\ap\pa
          center = centx,centy - coordinates of image pixels to be put on
              screen-center, any previously given center pixels (from earlier
              LOAD/IMA commands) are used or the center of the image will be
              used as default; 
\\
              the center pixels are entered in the usual MIDAS syntax, e.g. as
              real world coords. or frame pixels preceded by @.
\\
              centx or centy may also be set to C,C , if the image should be
              recentered on the screen
\ap\pa
          cuts = optional low, high cutvalues for loading or the method
              with which to compute these cut values;
              the method is entered via `D,method' or `F,method';
              D(efault) means that the cuts are only calculated if no valid
              cuts exist yet (i.e. real descriptor LHCUTS does not exist or
              LHCUTS(1) .GE. LHCUTS(2)),
              whereas F(orce),method will always calculate the cuts according
              to the given method;
              method is defaulted to 3SIGMA (see Note below);
              if low, high cuts are given and low cut .GE. high cut, then the
              cuts are set to min, max of frame (for backward compatibility);
              thus, setting e.g. the cuts to 0.0,0.0 has the same effect as
              entering F,MIN (see Note below)
              if the parameter cutvals is specified, the descriptor LHCUTS is
              updated accordingly
\ap\pa
          dirs = load directives - 2 strings separated by a comma:
              1. string = U(p) or D(own), for loading the image bottom-up or
              top-down (e.g. IUE);
              2. string = N(o) or O(verwrite), for cleaning up image channel
              before loading or for overwriting existing data without updating
              the channel data structures;
              defaulted to Up,No
\ap\pa
          fix = fx,fy,sx,sy - pixel numbers of the fixpoint, a point in the
              image and the screen which should coincide;
              i.e. the image is positioned on the screen in such a way that
              frame pixel (fx,fy) is at screen pixel (sx,sy).
              Frame pixels are entered as integers (e.g `fy' in [1,NPIX(2)]),
              and screen pixels either as absolute integers 
              (e.g. `sx' in [0,(x_screensize-1)]) or 
              as normalized floats (e.g. `sy' in [0.0,1.0]).
              This overrides the center specifications described above!
\ap\sa
See also:
          VIEW/IMAGE, CUTS/IMAGE, GET/IMAGE, GET/CURSOR, LOAD/LUT, LOAD/ITT
          SHOW/CHANNEL, DISPLAY/CHANNEL, ASSIGN/DISPLAY, COPY/DISPLAY
\as\no
Note: 
          The parameters may also be referenced via:
          FRAME= CHANL= SCALE= CENTER= CUTS= DIRS= FIX=
          If you are loading the image into the currently displayed
          image channel, the alphanumeric information is also updated.
             If you use the OVERWRITE option (2.string of par. `dirs' = Over),
          all subsequent commands will still assume that the original image
          is loaded; e.g. GET/CURSOR will return incorrect values!
          If the keyword MID$SPEC(7:10) is set = CUTS, the command will ask
          for new cut values in the end and reload the image with these
          cut values.
             If the descr. LHCUTS does not exist and the parameter `cutvals' 
          is not specified, the min and max of the frame is computed and 
          the cuts are set to mean-3*sigma, mean+3*sigma.
          For the calculation of the cut values (if not given explicitly) you
          may use the following methods: 
             MIN - use min, max as cuts.
             xSIGMA - use mean +- x*sigma as cuts (x = 0,1,...,9).
             xSIGMA,ySIGMA - use mean-x*sigma and mean+y*sigma as cuts.
             HIGH - use mean-0.1*max and max as cuts. Default is 3SIGMA.
             IHAP - use the IHAP algorithm for CCD frames (IHAP batch KDISP)
                    to calculate cuts
             For 3-dim frames the planes are counted beginning with 1;
          the last plane can also be specified via -1. 
          Instead of "planea..planeb" also a single plane may be given, 
          and the string "all" will load all planes.
          If the optional delay time (in secs) is given, that time is waited
          between the loading of different planes of the frame.
          All relevant planes are loaded into the image channel given as
          2nd parameter.
             To explore (view) an image in depth (using zoomed subwindows and
          graphics) use the command VIEW/IMAGE.
\on\exs
Examples:
\ex
          LOAD/IMAGE galaxy 0
            Load image `galaxy.bdf' into channel 0
\xe\ex
          LOAD/IMAGE FRAME=ngc1234 CUTS=0.33,2.34
            Load image `ngc134.bdf' into currently active channel, use cut
            values 0.33,2.34
\xe\ex
          LOAD/IMAGE FRAME=vaca CENT=@220,@380
            Load image `vaca.bdf' with x-pixel no. 220 and y-pixel no. 380
            of the image placed in the center of the display.
            This also shows that you can abbreviate the reference labels...
\xe\ex
          LOAD/IMAGE frame=vaca center=47.3,180.3
            Load image `vaca.bdf' with x-pixel corresponding to world 
            coordinate 47.3 and y-pixel corresponding to world coord. 180.3 of
            the image placed in the center of the display.
\xe\ex
          LOAD/IMAGE frame=toro cuts=D,2sigma
            Load image `toro.bdf', if no descr. LHCUTS exists or user cuts out
            of order (i.e. low_cut .GE. high_cut), set the cuts to
            mean-2*sigma and mean+2*sigma, update descr. LHCUTS.
            If instead of the `D,2sigma' we had `F,2sigma' then the cuts would
            always be set and LHCUTS updated accordingly.
\xe\ex
          LOAD/IMAGE frame=toro[<,<:@200,@100] fix=1,1,0,0
            Load sub-image of `toro.bdf' in the lower left corner of the 
            display.
\xe\ex
          LOAD/IMAGE ternero,2..8,2
            Load planes no. 2, ..., 8 of 3-dim image `ternero.bdf'. After the
            loading of each plane wait 2 seconds. Subsequent cursor readings
            of the display will refer to frame pixels in the 8th plane.
\xe\ex
          LOAD/IMAGE ternero,4
            Load 4th plane of 3-dim image `ternero.bdf'. 
\xe\ex
          LOAD/IMAGE ternero,all 1
            Load all planes of 3-dim image `ternero.bdf' into channel 1. 
\xe\ex
          LOAD/IMAGE ternero,all 2,...
            Load the planes of 3-dim image `ternero.bdf' (beginning with the
            first plane) into the channels 2, 3, 4, ... 
            There is no wrap around after the last channel of the display is
            used, instead the command stops even if not all planes have been
            loaded yet. 
\xe\ex
          LOAD/IMAGE FRAME=becerra SCALE=-3,A
            Load image `becerra.bdf' into currently active channel, average
            over a 3*3 subwindow to get the pixel value for loading.
\xe\ex
          LOAD/IMAGE FRAME=vaca SCALE=-2,-4,min
            Load image `vaca.bdf' into currently active channel, take minimum
            over a 2*4 subwindow to get the pixel value for loading.
\xe \sxe
