; SABOX
;---------------------------------------------------------------
;! create box file from source islands in facet images
;# Task IMAGING OOP
;-----------------------------------------------------------------------
;;  Copyright (C) 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
;-----------------------------------------------------------------------
SABOX     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
SABOX: Find Clean boxes in a set of images
                                   Input images
INNAME                                Image name (name)
INCLASS                               Image name (class)
INSEQ              0.0      9999.0    Image name (seq. #)
INDISK             0.0         9.0    Image disk drive #
NFIELD             1.0      4096.0 Number of facets per width
NGAUSS             0.0        10.0 Number Gaussian widths
BLC                0.0             Bottom left corner each facet
TRC                0.0             Top right corner each facet
BOXFILE                            Input box file name
OBOXFILE                           Output box file name
APARM                              (1) N sigma cutoff   0->3
                                   (2) edge skip in pixels  0->5
                                   (3) extend box size in pixels
                                   (4) box type: 0 choose
                                   (5) > 0 don't use ACTNOISE
                                   (6) > 0 forbid diagonal
                                       island connections
                                   (7) Min island size, 0 -> 2
                                   (8) > 0 don't delete overlaps
BADDISK          0.         36.    Disks to avoid for scratch
----------------------------------------------------------------
SABOX
Type: Task
Use: SABOX resembles SAD except that it does not fit the sources it
     finds.  Instead, it determines a Clean box to surround the source
     and writes it to an output "box file" for later input to IMAGR or
     other tasks which process box files.

     The input box file is copied to the output box file, omiting any
     Clean boxes.  Then the task loops over facets finding first the
     rms of the facet, second all source islands exceeding N*rms, and
     finally writing out boxes fit to those islands.  All boxes and
     the rms are found only for pixels within an inscribed ellipse in
     the facet.  Note that finding the rms is moderately expensive
     except when the ACTNOISE keyword  has been written into the
     header by IMEAN.
Adverbs:
  INNAME......The input image name.   Standard defaults.
  INCLASS.....The input image class.  The first 2-3 characters determine
              a base name and the last 4-3 are a numeric field number
              nnn (i.e. ICL001 or IIM012 or IC3245).  Class names for
              higher fields are nnn through nnn+NFIELD-1.  Old style
              names in which the last 2 characters represent the field
              number minus one in extended Hex are also supported.
  INSEQ.......The input image sequence number. 0 => high
  INDISK......The input image disk drive no. 0 => any
  NFIELD......The number of fields per Gaussian width.  The total
              number of facets will be NFIELD * NGAUSS <= 4096.
  NGAUSS......Number of Gaussian widths in the facets.
  BLC.........The bottom left-hand pixel of the input image(s) which
              becomes the bottom left corner of the subimage
              processed.  The value 0 means 1.  The output boxes will
              be in true image X,Y pixels.  Use this to select planes
              in a cube - but note that the plane number is not
              recorded in the box file.
  TRC.........The top right-hand pixel of the input image which
              becomes the top right corner of the subimage processed.
              The value 0 means to use the full axis dimension on that
              axis.
  BOXFILE.....Input box file - defines field centers and the like (see
              HELP IMAGR).  Any Clean boxes are discarded.
  OBOXFILE....Text file containing all non-box information from
              BOXFILE plus all boxes found by SABOX.
  APARM.......Control parameters:
              (1) Find islands down to APARM(1) * rms of facet.
                  0 => 3.
              (2) Inscribed ellipse radius is APARM(2) pixels less
                  than the image half width/height.  0 -> 5
                  If APARM(2) < 0, use abs(APARM(2)) as an edge skip
                  but consider all image pixels in the rectangular
                  area blc+edgskp to trc-edgskp.  Otherwise, pixels
                  outside an inscribed ellipse are discarded.
              (3) Extend box out from island by APARM(3) pixels.
                  No default (< 0 => 1).
              (4) -1 => use rectangular boxes always
                  +1 => use circular boxes always
                   0 => choose (circles if x,y sizes of island are
                        nearly the same, otherwise rectangles)
              (5) > 0 => find rms the hard way even if ACTNOISE
                  present.  The "hard" way works well since each
                  image is held in memory.  If you want the same RMS
                  to be used for each facet, then ACTNOISE should be
                  set to that RMS in each facet header and APARM(5)
                  set to 0.
              (6) > 0 => do not allow islands to join along diagonals
                  (not usually needed and can make odd shaped boxes)
              (7) Minimum linear size of islands in either axis.
                  Islands that are smaller are kept, but only if the
                  center pixel is > 3 * APARM(1) * rms.
              (8) After all the boxes are found, SABOX will compare
                  the boxes in each facet to those in the other
                  facets of the same resolution.  If overlaps are
                  found, the smaller of the 2 overlapped boxes will be
                  deleted.  If APARM(8) > 0, this test is not done.
  BADDISK.....Disks to avoid for the scratch files.
----------------------------------------------------------------
