; FILIT
;---------------------------------------------------------------
;! Interactive BOXFILE editing with facet images
;# Task IMAGING OOP TV
;-----------------------------------------------------------------------
;;  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
;-----------------------------------------------------------------------
FILIT     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
FILIT: 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
BOXFILE                            Input box file name
OBOXFILE                           Output box file name
TXINC              0.0       256.0 Load every TXINC'th column
TYINC              0.0       256.0 Load every TYINC'th row
TBLC               0.0             Bottom left corner each facet
TTRC               0.0             Top right corner each facet
PIXRANGE                           Min,Max  of image intensity
                                     0=>entire range
FUNCTYPE                           Image intensity transfer func
                                     'LN' Linear.  blank=> 'LN'
                                     'LG' Logarithmic
                                     'L2' More logarithmic
                                     'SQ' Square root
                                     'NE' Negative linear
                                     'NG' Negative logarithmic
                                     'N2' Negative more log.
                                     'NQ' Negative square root
PRTLEV             0.0         2.0 Display changed boxes?
IM2PARM                            Autoboxing parameters
                                   (1) allowed # per operation
                                   (2) island level: n * sigma
                                   (3) peak required m * sigma
                                   (4) limit = frac * max
                                   (5) extend boxes by j pixels
                                   (6) image edge skip
----------------------------------------------------------------
FILIT
Type: Task
Use: FILIT resembles verbs FILEBOX and DFILEBOX except that it does
     the loading of the TV, allows images larger than the TV display
     area, and loops through all facets.  It is driven by a menu that
     allows zooming, manipulation of display transfer functions and
     colors, roaming, switching between facets, and editing of the
     current Clean boxes.

     The input box file is copied to the output box file, saving any
     Clean boxes in memory.  Then the task loads the first facet to
     the TV - in a roam mode if needed.  When the roam manipulation
     ends, the current display is captured in a simple image.  The
     current boxes for that image are displayed along with a menu.
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*NGAUSS-1.  Old
              style names in which the last 2 characters represent the
              field number minus one in extended Hex are also
              supported.  If a facet other than the first is named
              here, the display with start with the facet number named
              in INCLASS.  However, all facets from 1 to NFIELD*NGAUSS
              will be available for processing.
  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.
              This should be the total number represented in the box
              files even if you wish to process only some of them.
  NGAUSS......Number of Gaussian widths in the facets.
  BOXFILE.....Input box file - defines field centers and the like (see
              HELP IMAGR) and the initial set of Clean boxes.
  OBOXFILE....Text file containing all non-box information from
              BOXFILE plus all boxes found by FILIT.  Must not exist
              prior to running FILIT and will be forced to be unequal
              BOXFILE (by appending letter O if needed).  Blank ->
              BOXFILE with appended letter oh.
  TXINC.......Load every TXINC'th column beginning at TBLC,  0 -> 1.
  TYINC.......Load every TYINC'th row beginning at TBLC,     0 -> 1
  TBLC........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.
  TTRC........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.
  PIXRANGE....Min,Max intensity to display. 0 => entire range.
  FUNCTYPE....Image intensity transfer function
              'LN' => linear;        'NE' => negative lin.
              'LG' => log;           'NG' => negative log;
              'L2' => extreme log;   'N2' => negative extra log;
              'SQ' => square root,;  'NQ' => negative square root;
              others => linear.
  PRTLEV......Display the changed boxes on each REBOX and DELBOX?
              0 => no display, 1 => on message terminal only,
              2 => in message file too
  IM2PARM.....Auto-Clean boxing, values can be changed interactively:
             (1) FILIT can create Clean boxes automatically.  It
                 will find no more than the strongest IM2PARM(1)
                 boxes each time it looks.  It ignores pixels
                 already in boxes.  Limit 200.
             (2) The auto-boxing starts by finding islands of emission
                 > IM2PARM(2) * rms in the residual image.  This
                 defines the size of the box if it is accepted.
                 ( 0 -> 3.0 )
             (3) A box can only be accepted if its peak brightness is
                 > IM2PARM(3) * rms in the residual.  A box is also
                 accepted only if the peak in it is not already in a
                 Clean box.    < IM2PARM(2) -> IM2PARM(2) + 2.0
             (4) A box is also only accepted if its peak brightness is
                 > IM2PARM(4) * maximum residual in the whole image
                 not already in a box.    < 0.01 or > 0.9 -> 0.1
             (5) The box determined by the island may be extended
                 outward in all directions by IM2PARM(5) pixels.
                 < -1 => 1.  Note that -1 means compressed by 1 in
                 radius or in all directions for rectangles.
             (6) The image is examined only in an ellipse (circle if
                 IMSIZE(1) = IMSIZE(2)) of radius in X of IMSIZE(1)/2
                 - IM2PARM(6) and in Y of IMSIZE(2)/2 - IM2PARM(6).
                 = 0 -> 5;   < 0 => no inscribed ellipse.
----------------------------------------------------------------
FILIT:  Interactive editing of Clean boxes for a set of facet images
Documenter:  E. W. Greisen NRAO
Related Programs: SABOX, BOXES, FIXBX
Related Verbs:    TVBOX, REBOX, DELBOX, FILEBOX, DFILEBOX, DRAWBOX

FILIT combines a number of Clean-box manipulation operations in a
convenient TV-menu driven operation.  It accepts a group of related
images, usually facets, named with class XXXnnn, for nnn given by
INCLASS to nnn + NFIELD-1.  It begins by loading INCLASS to the AIPS
TV, either as a normal TVLOAD if the full image fits on the TV screen
or in a TVROAM mode.  In the latter, the TV cursor controls the
selection of the subimage that is visible.  When button D is hit, the
roam stops and the visible image is captured to image plane 1.  The
current Clean boxes (defined by BOXFILE) are displayed if they are
visible in the current subimage.  A variety of box editing and image
enhancement operations are available from a TV menu.  Hit button A, B,
or C to select an operation or button D for on-line help information.
The image may be REROAMed to allow selection of another subimage and
continued box editing.  The number of boxes and their values when a
facet is selected are saved and may be restored until a new facet is
selected.  The menu then allows you to switch to the next higher or
lower numbered facet - again beginning in roam mode if necessary.

     The interactive options appear in one column.  They are
-----------------
| EXIT          |  to write the revised Clean boxes to OBOXFILE
                   and exit the task
| OFFZOOM       |  turn off any zoom magnification
| OFFTRAN       |  turn off any black & white enhancement
| OFFCOLOR      |  turn off any pseudo-coloring
| TVFIDDLE      |  as in AIPS, allows zoom, pseudo-color or
                   black and white enhancement
| TVZOOM        |  interactive zoom magnification and center
| TVTRAN        |  black and white enhancement as in AIPS
| TVPSEUDO      |  many pseudo-colorings as in AIPS
| TVFLAME       |  flame-like pseudo-colorings as in AIPS
| CURVALUE      |  display image intensity, pixel x/y at cursor
| REBOX         |  box editing mode as in AIPS to create or change
                   boxes
| DELBOX        |  box editing mode as in AIPS to delete boxes
| AUTOBOX       |  find some new boxes auto-magically
| AUTOBOX PARMS |  change the auto-box control parameters
| DEL ALL BOXES |  delete all boxes for this facet
| RESET BOXES   |  restore boxes to state when this facet was selected
| CHECK BOXES   |  delete boxes that overlap in separate facets
| NEXT FACET    |  to switch to displaying/editing the next higher
                   numbered facet
| LAST FACET    |  to switch to displaying/editing the next lower
                   numbered facet
| ENTER FACET   |  to type in the facet number for the next facet to
                   review/edit
| REROAM        |  to roam in the current image to select a new
                   subimage (option appears only for large images)
----------------

RESET BOXES is a special function.  When facet n is chosen, the boxes
for that facet are remembered and may be restored replacing any
changes so long as you do not select a new facet.  You can DEL ALL
BOXES and get them back, you can add lots of boxes with AUTOBOX and
get rid of them, etc. --- so long as you do not select another facet.
You can freeze in the current boxes for facet n by selecting another
facet (e.g. n+1) and then coming back to n.  The initial boxes from
the previous visit to n are forgotten and replaced first by the boxes
in facet n+1 and then by the current boxes in facet n.
