% @(#)extracimag.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:43:34 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      extracimag.hlq
%.AUTHOR     KB, IPG/ESO
%.KEYWORDS   MIDAS, help files, EXTRACT/IMAGE
%.PURPOSE    On-line help file for the command: EXTRACT/IMAGE
%.VERSION    1.0  14-FEB-1985 : Creation, KB
%----------------------------------------------------------------
\se
SECTION./IMAG
\es\co
EXTRACT/IMAGE						20-MAY-1997   KB
\oc\su
EXTRACT/IMAGE out = in intval
EXTRACT/IMAGE out = in center_spec loff roff
	extract a subimage from an image frame
\us\pu
Purpose: 
          Extract a subimage from an image frame.
\up\sy
Syntax: 
          EXTRACT/IMAGE out = in intval
          EXTRACT/IMAGE out = in center_spec loff roff
\ys\pa
          out = result frame
\ap\pa
          in = input frame
\ap\pa
          intval = [x1,y1,z1:x2,y2,z2] or [x1,y1,z1..x2,y2,z2]
              defines "lower left" and "upper right" corners in the input
              frame, the surrounding square brackets ([ and ]) are necessary

\ap\pa
          center_spec = [xc,yc,zc] central pixel, the surrounding square 
              brackets ([ and ]) are necessary
\ap\pa
          loff = xleft,yleft,zleft - the number of pixels to the "left"
              of the central pixel 
\ap\pa
          roff = xright,yright,zright - the number of pixels to the "right"
              of the central pixel 
\ap\no
Note:  
          The coordinates xi, yi, zi can be in any of the following formats:
\\
          a number, to indicate real world coords. 
\\
          a number preceded by @, to indicate a pixel no. 
\\
          the symbols. "<" and ">", to indicate start or end pixel.
\\
          If the central frame pixel option is used, the start and end pixels
          of the subframe to be extracted are calculated by subtracting the
          left offsets from the center and adding the right offsets to it.
\\
          If the world coordinates are expressed as `hh:min.sec' you have to 
          use the string `..' instead of `:' to separate start from end
          coordinates.
\\
          For backwards compatibility also the previous syntax of this
          command: EXTRACT/IMAGE out = inintval   or
          EXTRACT/IMAGE out = incenter_spec loff roff 
          (i.e. input file and coord interval (center) glued together in one
          parameter) is supported.
\on\sa
See also:
          INSERT/IMAGE, EXTRACT/CURSOR, EXTRACT/LINE, SHRINK/IMAGE
\as\no
Note:
          The user cuts (i.e. descriptor LHCUTS(1,2)) of subframe, the
          extracted frame, will remain the same as the input frame.
\on\exs
Examples:
\ex
          EXTRACT/IMAGE out = in [@20,@10:@119,@19]
            Extract subimage of 100 x 20 pixels from the 2-dim frame `in.bdf'
            and store it as frame `out.bdf'.
\xe\ex
          EXTRACT/IMAGE out = in [2:43:32.7,18:21:17.8..2:43:38.8,18:21:57.3]
            Extract subimage from the 2-dim frame `in.bdf' using world coords.
            to define the area and store it as frame `out.bdf'.
\\
            Note, that we used `..' as separator between start and end
            coordinates instead of `:' !
\xe\ex
          EXTRACT/IMAGE out = in [15.1:>]
            Extract subimage from 1-dim frame `in.bdf'. First pixel in 
            `out.bdf' is the pixel in `in.bdf' with world coordinate closest 
            to 15.1 and last pixel of `out.bdf' is tha last pixel of the input
            frame.
\xe\ex
          EXTRACT/IMAGE out = in [@101,@101] 100,40 22,39
            Extract subimage from 2-dim frame `in.bdf'. First pixel in 
            `out.bdf' is the pixel 1,61 and last pixel is 123,140. So `out.bdf'
            has 123 x 80 pixels.
\xe\ex
          EXTRACT/IMAGE out = in[@101,@101] 100,40 22,39
            As above using "old" syntax.
\xe\sxe