; SLCOL
;---------------------------------------------------------------
;! Task to collate slice data and models.
;# TASK ANALYSIS
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2001, 2008-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
;-----------------------------------------------------------------------
SLCOL     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
SLCOL:   Task to collate slice data and models.
INNAME                             image name
INCLASS                            image name class
INSEQ          0.0       9999.0    image name seq #
INDISK         0.0          9.0    disk drive
OUTTEXT
                                   name of output text file.
INVERS         0.0      46655.0    version # of first  SL file.
                                   0 => all versions
NFILES         0.0      46655.0    No. of slice files to collate
                                   0 => 1
ZINC           0.0       4096.0    Save point every ZINC arcsecs
                                   0 => save all slice points
PIXXY                              Reference position in pixels
                                   0,0 -> use header ref pixel
OPCODE                             'SLVL' and 'MODL'
                                   '    ' => 'SLVL'
APARM                              A(1) <=0 => don't output
                                   slice points that are blank
                                   A(2) >0 Overwrite existing
                                   text file, <=0 create or
                                   append
----------------------------------------------------------------
SLCOL
Verb:  Collates SLICE file data.  The output is controlled by
       the opcode.  Two are available:

       'SLVL' : Each point in the slice is read and the distance
       of that point from the reference position calculated.
       Output is
              SLICE_POINT_NO., X, Y,  DIST, VAL
       where X and Y are the distances from the header reference
       pixel, DIST is the distance (arcsec) of the slice point
       from the reference position, VAL is the slice point
       value.  The sign of DIST is set by the X distance from the
       user-specified reference position; if the slice is made only in
       Y, then the Y distance from PIXXY is used instead.  The
       SLICE_POINT_NO is just that; there are 2**n (n=7-11)
       interpolated points in a slice, depending on exactly how many
       image pixels it spans. The adverb ZINC enables you to save a
       slice point at regular increments ALONG THE SLICE in
       arcseconds, since generally you don't want all those hundreds
       of slice points.  If OPCODE is blank, SLVL is selected.

       MODL : if Gaussian models are available, then the model
       data of the LAST one will be extracted.   It saves:
            isl m n   X   Y   DIST   PEAK   FWHM
       where isl is the slice number, m is the model number, n is the
       Gaussian component number, X and Y are the separations from the
       reference pixel (in the header) in asec, DIST is the distance
       from the user-provided PIXXY in asec, PEAK is the peak of the
       model, FWHM is the width (arcsec) of the model.  The same sign
       convention for DIST is used.  The adverbs ZINC and APARM(1) are
       not used for OPCODE = 'MODL'

       If you specify a disk file for output, you must include
       a LOGICAL name (VMS) or an ENVIROMENT variable (UNIX).
       You cannot spell out the full directory specification
       or path name. This is for reasons of portability of the
       code.  Examples:

       VMS:OUTTEXT = 'dba1:[neil.crap]file1.dat' is NOT allowed
           OUTTEXT = 'data:file1.dat'              is allowed,
                                                 where `data' is
                                                 a LOGICAL name
       You can define a VMS logical name at operating system
       level with a command like
               $ DEFINE DATA DBA1:[NEIL.CRAP]


       UNIX: OUTTEXT = '/mnt/neil/crap/file1.dat' is NOT allowed
             OUTTEXT = 'data:file1.dat'               is allowed
                                              where `DATA' is an
                                             enviroment variable
       You can define an environment variable at operating
       system level with a command like, for example, with the
       C-shell:
               % setenv DATA /mnt/neil/crap
       You must make sure the environment variable is upper
       case, because AIPS converts everything internally to
       upper case.

       Note also that you have the option to append to an
       existing text file, or overwrite it.

       Slice files are written to disk with the inverse of the
       image scale and offset factors applied.  Thus, the slice
       and model data are scaled by SLCOL on reading.  If you
       rescale your image after making a slice, then SLCOL will
       output the slice scaled by the new factors.

Adverbs:
  INNAME.....Input map file name (name).
  INCLASS....Input map file name (class).
  INSEQ......Input map file name (seq. #).
  INDISK.....Disk drive # of input map  file.
  OUTTEXT....Name of output text file. If blank, then the output
             is directed to the message terminal.
  INVER......Version number of first slice file, 0 => all
  NFILES.....No. of slice files to collate starting with INVERS,
             0 => 1
  ZINC.......Save a slice point every ZINC arcseconds along the
             slice when doing 'SLVL', 0 => save all slice points
  PIXXY......X,Y coordinates of a reference position (pixels)
             relative to which the distances are worked out.
             It is best to use the image reference pixel which you can
             get by setting PIXXY(1) = PIXXY(2) = 0.000.
  OPCODE.....Controls the operation
             MODL : writes CEN, DIST, PEAK, POS, FWHM, ISL
             SLVL : writes SL_P_NO., X, Y, DIST, VALUE,
  APARM......A(1) <=0 => Do not output slice points that are
             blanked.
  APARM......A(2) >0 => Overwrite pre-exsiting file,
             else create or append.
----------------------------------------------------------------
