; BOXFILE
;---------------------------------------------------------------
;! specifies name of Clean box text file
;# ADVERB IMAGING
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-1997, 2001-2002, 2008, 2014
;;  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
;-----------------------------------------------------------------------
BOXFILE   LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
----------------------------------------------------------------
BOXFILE
Type: Adverb  (String*48)
Use:  To specify the name of a disk text file outside the usual AIPS
      catalog system to be used to specify field parameters and Cleaning
      areas.  Up to 4096 fields may be specified and BOXFILE must be
      used for fields numbered > 64 to specify RASHIFT, DECSHIFT,
      FLDSIZE, or BCOMP.  To specify Clean boxes for fields numbered >
      1, the BOXFILE option is required.  IMAGR also allows the
      weights for the various spectral channels to be set using the
      BOXFILE.  A BOXFILE may be written or rewritten with verb
      FILEBOX and by IMAGR as OBOXFILE giving the results of
      interactive setting of the boxes.

      Each line of text is read from the file and leading and trailing
      blanks are discarded.  "Column 1" as used below actually means
      the first non-blank column on the card.

      The field parameters are specified by giving the letter F or f in
      column one, followed by the field number, the X and Y FLDSIZE, the
      RASHIFT and the DECSHIFT.  Values given in BOXFILE override those
      given by the corresponding adverbs (including 0s).

      Alternatively, the field parameters may be specified by giving the
      letter C or c in column one, followed by the field number, the X
      and Y FLDSIZE, and the field center right ascension (HH MM SS.S)
      and declination (signDD MM SS.S) separated by blanks.

      The boxes are specified by giving the field number left justified
      in column one followed by, for rectangular fields, the bottom left
      corner x and y and top right corner x and y pixel numbers of the
      field or, for circular fields, a -1 to signify circular, the
      radius in pixels, and the center x and y in pixel number for the
      field. The number of Clean boxes per field is limited to
              min [ 4096, (64*4096)/(NFIELD*NGAUSS) ]
      To specify that a field has no Clean boxes, specify the BLC and
      TRC as four zeros.

      In IMAGR only, to mark regions which should never be Cleaned,
      include lines beginning with U or u.  Following that character
      with at least one blank, enter the facet number and four values
      as for Clean boxes (i.e either rectangular or circular).  The
      UNClean boxes may be changed with the TV when DOTV is true.
      Thus, for example
         U 2 100 100 130 121
         u    001  -1   5 235 237
      will protect one area in each of facets 1 and 2 from Cleaning.
      This option is primarily used to isolate a source to one special
      facet and to keep it from being Cleaned in another facet.
      Modeling routines may then use the special facet - or all facets
      except the special one - to isolate the source.  Task CCEDT is
      also used for this purpose when UNClean boxes have not been
      used.

      The number of components to use at the restart of an IMAGR
      (BCOMP) may be given by putting the letter B or b in column one
      followed by the field number and the value of BCOMP to be used.

      When combining more than one spectral channel or IF, you may
      wish to alter their relative weights in a temporary fashion.
      The BOXFILE option allows this with W cards.  Put W or w in
      column 1, then a weight, then a channel number (0 -> all), and
      last an optional IF number (absent -> 0, 0 -> all).

      To have "stars" plotted on the TV along with an image, enter up
      to 100 lines of form beginning with S or s and containing
      S     HH MM SS.SS  DD MM SS.SS  Major  Minor  PA  Type
      where HH MM SS.SS is the right ascension, DD MM SS.SS is the
      declination, Major and Minor are the longer and shorted axes of
      the star in arc seconds, PA is the position angle in degrees
      (East of North), and Type is the integer "star" type
         1: Plus sign (default)   12: Five pointed star
         2: Cross (X)             13: Star of David
         3: Circle                14: Seven-pointed star
         4: Box                   15: Eight-pointed star
         5: Triangle              16: Nine-pointed star
         6: Diamond               17: Ten-pointed star
         7: Pentagon              18: 11-pointed star
         8: Hexagon               19: 12-pointed star
         9: Septagon              20: 13-pointed star
         10: Octagon              21: 14-pointed star
         11: Nine-gon             22: Plus with gap
                                  23: Vertical line
                                  24: Cross (X) with gap
      Defaults for Major, Minor, PA, and Type are 1, 1, 0, and 1.

      Lines in the file whose first non-blank character is anything
      besides F, f, C, c, B, b, W, w, S, s, or a number 0-9 are
      treated as comments.  The characters # $ % & * ; will never be
      used for data and hence are the safest comment-indicating
      characters.

Format: The name is usually given by specifying a logical name,
      followed by a colon, followed by the actual file name.  In
      Unix, logicals are environment variables.  The logical name
      must be set up before entering the AIPS program and is usually
      in upper case.  Thus, for example:
             % setenv MYAREA ~joeuser
      for the C shell, or
             $ myarea=$HOME; export MYAREA
      for bourne, korn, and bash shells.  Then in AIPS,
             BOXFILE = 'MYAREA:CASA.BOXES'
      Note that the Unix-standard $ ahead of the logical is omitted.
      Other forms are now acceptable as well:
             BOXFILE = 'FITS.DAT
      will find the file in the directory local when you started AIPS.
      A full path name may also be given
             INFILE = '/home/primate2/egreisen/AIPS/Text.prt
      if it fits in 48 characters.  Note that the trailing quote mark
      is left off and this is the last command on the input line so
      that the case is preserved.

Null value:  '          '
      Taken to mean no subsidiary file.  This is an error to FILEBOX and
      means no boxes files for IMAGR and WFCLN.

Verbs:
    FILEBOX......Modifies or creates a BOXFILE using the TV
Tasks:
    BOXES........Adds Clean boxes to BOXFILE around sources from a list
    CCEDT........Select CC components in BOXes and above mininum flux.
    CHKFC........Makes images of Clean boxes from Boxfile
    IMAGR........Fourier transforms and Cleans uv data with wide-field,
                 interactive TV, and data weighting options.
    SCIMG........Full-featured imaging plus self-calibration loop
    SETFC........Makes a BOXFILE for input to IMAGR
    WFCLN........Fourier transforms and Cleans uv data with wide-field
                 options.

Examples:
  To specify a field's parameters:
       F  2  450 450 -25.5 6.7
  specifies that field 2 is to have a FLDSIZE of 450x450 with an RASHIFT
  of -25.6 and a DECSHIFT of 6.7 arcsec.  If this is the only F card in
  the file, then fields 1, and 3 through NFIELD are set by the adverb
  values.  Alternatively,
       C  2  450 450  11 34 45.67 -00 14 23.1
  specifies that field 2 is to have a FLDSIZE of 450x450 with a center
  RA of 173.6902917 degrees and a center Declination of -0.23975
  degrees.  All 9 numbers must be given; the sign is optional for
  positive declinations and is given only on the degrees term.

  To set Clean boxes, specify one box per line, as field
       field  blc-x blc-y trc-x trc-y (5 integers) e.g.
       1      200   205   220   222
       1      230   232   240   241
       2      100   100   130   121
       ...
  or circular "boxes" as
       field -1  radius center-x center-y  (5 ints) e.g.
       001   -1  10     210      214
       001   -1  5      235      237
       3     -1  15     255      513
       ....
  Specifies 4 boxes for field 1 and one each for fields 2 and 3.
  See also IMAGR and FILEBOX.

  To set weights, for example:
       W  0.1   1
       W  0.5   2
       W  0.8   2  3
       W  0.1  63
  assigns weight 1 to all channels 3-62, weight 0.1 to all channels 1
  and 63, weight 0.5 to channel 2 except for 0.8 in channel 2, IF 3.
  These "weights" multiply the weights already assigned to the data.

  BCOMP values are also set.  For example, to include no components
  from field 98 and some from 99 include the lines:
       B   98     0
       B   99   243
  Fields 1 through NFIELD*(Number of scales) may be specified.
----------------------------------------------------------------
