; SUBIM
;---------------------------------------------------------------
;! Task to select a subimage from up to a 7-dim. image
;# TASK IMAGING
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1997, 2009
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
SUBIM     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
SUBIM:  Task to select a subimage from upto a 7-dim. image
INNAME                             Input name(name).
INCLASS                            Input name(class).
INSEQ           0.0      9999.0    Input name(seq. #). 0=>high
INDISK                             Input disk drive #. 0=>any
OUTNAME                            Output name(name).
OUTCLASS                           Output name(class).
OUTSEQ         -1.0      9999.0    Output name(seq. #).
                                     0 => highest unique
OUTDISK                            Output image disk drive #
                                     0 => highest with room
BLC             0.0      4096.0    Bottom left corner of image
                                     0=>entire image
TRC             0.0      4096.0    Top right corner of image
                                     0=>entire image
XINC            0.0      1000.0    Select every XINC col. 0=>1
YINC            0.0      1000.0    Select every YINC rows. 0=>1
OPCODE                             '   ' select XINC, YINC pixel
                                   'AVE' average XINC,YINC box
                                   'MIN' Min in  XINC,YINC box
                                   'MAX' Max in  XINC,YINC box
----------------------------------------------------------------
SUBIM
Type: Task
Use:  SUBIM will copy a subarray of a cataloged file to an output file
      and insert a catalog entry for the output file.  SUBIM can handle
      up to 7-dimensions.  If there are Clean Components files attached
      to the input image, they are copied to the output image.  SUBIM
      checks and resets the peak brightnesses and the blanking info.
      SUBIM can read a SCratch file, but always creates an MA file.
Adverbs:
  INNAME......Input name of image(name).     Standard defaults.
  INCLASS.....Input name of image(class).    Standard defaults.
  INSEQ.......Input name of image(seq. #).   0 => highest.
  INDISK......Disk drive # of image.         0 => any.
  OUTNAME.....Output name of image(name).    Standard defaults.
  OUTCLASS....Output name of image(class).   Standard defaults.
  OUTSEQ......Output name of image(seq. #).  0 => highest unique
  OUTDISK.....Disk drive # of Output image.  0 => highest with
              space.
  BLC.........The bottom left-hand pixel of the input image
              which becomes the bottom left corner of the
              subimage.  The value (0,0) means (1,1).
  TRC.........The top right-hand pixel of the input image
              which becomes the top right corner of the
              subimage.  The value (0,0) means take the top
              right hand corner of the image.
  XINC........The X increment to use when selecting columns
              from the source file.        0 => 1.
  YINC........The Y increment to use when selecting lines from
              the source file.             0 => 1.
  OPCODE......Four Options, '   ' = select the XINC, YINC pixel
              'AVE' average non-blanked pixels in XINC, YINC box
              'MIN' Select Minimum value in XINC, YINC box
              'MAX' Select Maximum value in XINC, YINC box
----------------------------------------------------------------
SUBIM: Task which selects a subregion of an image with some
       optional processing and creates an output image.
DOCUMENTERS:  G. Langston NRAO

                        PURPOSE

SUBIM is useful for copying images and reducing the size of
images.  SUBIM also can be used to smooth an image by averaging
the pixels with the XINC, YINC regions.

Below is an example the results of SUBIM for the various
OPCODEs.

Assume the input image has the following pixels
                X-Pixel
Y Pixel  1   2   3   4   5  6
   6    61  62  63  64  65 66
   5    51  52  53  54  55 56
   4    41  42  43  44  45 46
   3    31  32  33  34  35 36
   2    21  22  23  24  25 26
   1     1   2   3   4   5  6

For BLC=0,0, TRC=5,5, XINC=2, YINC=2,
The following results are produced by the OPCODEs:

OPCODE = '    '                OPCODE = 'MIN'
          X-Pixel                     X-Pixel
Y Pixel  1   2   3           Y Pixel  1   2   3
   3    51  53  55              3    51  53  55
   2    31  33  35              2    31  33  35
   1     1   3   5              1     1   3   5

OPCODE = 'AVE'                 OPCODE = 'MAX'
          X-Pixel                     X-Pixel
Y Pixel   1     2    3       Y Pixel  1   2   3
   3    51.5  53.5  55          3    52  54  55
   2    36.5  38.5  40          2    42  44  45
   1    11.5  13.5  15          1    22  24  25

Note that because the input block starting at pixel 5,5 only
contains 1 pixel, all OPCODEs produce the same result.
Also note that there is a shift of the data for OPCODEs other
than '   ', because the input pixels 1,1 1,2 2,1 and 2,2 all
are combined to produce output pixel 1,1  etc.
