; IMTXT
;---------------------------------------------------------------
;! Write an image to an external text file.
;# Task Imaging
;-----------------------------------------------------------------------
;;  Copyright (C) 1995
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
IMTXT     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
IMTXT     Write an image to an external text file.
INNAME                             Input image name (name)
INCLASS                            Input image name (class)
INSEQ            -1.0     9999.0   Input image name (seq. #)
INDISK            0.0        9.0   Input image disk unit #.
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
FACTOR                             Multiplication factor. 0 => 1
TRANSCOD                           Fortran format (e.g. 'F5.1')
X                                  Value of blanked pixel.
OUTFILE                            Output file name (Non-AIPS)
----------------------------------------------------------------
IMTXT
Task:  Write an image to an external text file.  The format used
       is that used by FETCH in reading images.
       Each row in the image will be written to a single line in
       the output file and there is a limit of 1000 characters
       in a line in the output file
Adverbs:
  INNAME.....Input image name (name).     Standard behavior
  INCLASS....Input image name (class).    Standard defaults.
  INSEQ......Input image name (seq. #).   0 => highest.
  INDISK.....Disk drive # of input image. 0 => highest number
  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.
  FACTOR.....The pixel values will be multiplied by FACTOR
             before writing.  0 => 1.0
  TRANSCOD...The Fortran format to be used.  This format should
             be appropriate for a single value and will be
             replicated as necessary. 
             NOTE: the format should NOT include the repeat
             count, this will be determined from the subimage
             size.  An example is 'F10.5'.
             The appropriate format codes are 'F', 'E' and 'I'.
  X..........The value to be used for blanked pixels; this is
             the value to be written and is not multiplied by
             FACTOR. 
             NOTE: this value must be kept exactly by the
             specified format, e.g., don't use -999.99 and
             TRANSCOD='I5'. 
  OUTFILE....A file external to the AIPS system into which the
             image is to be written.
---------------------------------------------------------------
IMTXT:  Task writes an AIPS image to an external, formatted
        file. 
DOCUMENTOR: W. D. Cotton, NRAO.
RELATED PORGRAMS: FETCH
 
                          PURPOSE
 
     IMTXT converts a subimage of an AIPS image to an external
text file.  This file contains the information in a form that
can be read by task FETCH. The pixel values are encoded one line
per row in the image after possibly scaling using a specified
Fortran format (TRANSCODE).  Blanked pixels will be replaced by
a specified value.  All data from a row in the selected subimage
must fit in a single line in the output image which may not
exceed 1000 characters.
   The output file begins with a small amount of descriptive
information.  This is described below.


                        COMMENTS

OUTFILE:
     The user must specify a text file for the image.
The header section of the output file contains a series of
keyword-value pairs to define the image followed by the data in
row order.  The output file can be specified as follows shown in
the following example: 
         OUTFILE='myarea:image.dat'
            where MYAREA is an environment variable set before
            starting AIPS e.g.:
            %setenv MYAREA /mnt/username
            Note also: in UNIX all files whose names are passed
            to AIPS should have names containing only upper case
            characters.

   The header portion of the image file contains a number of
keyword-value pairs:

     NAXIS = n          (The number of axes in the image, up to
                         7 are allowed)
     DIM = m1, m2, ...  (The dimension of each axis used.)
     FORMAT = 'r?w.d'   (The FORTRAN format used to encode the
                         pixel values; derived from TRANSCODE.
     OBJECT = 'name'     (The name of the object)
     TELESCOP = 'name'   (The name of the telescope used)
     INSTRUME ='name'    (The instrument used)
     OBSERVER='name'     (The observers name)
     UNITS = 'units'     (The units of the image)
     EPOCH = xxxx.x      (The mean Epoch of the coordinates)
     CRTYPE='a','b'...   (The axis type (label) of each axis)
     CRVAL = x.x, y.y... (The coordinate values at the reference
                          pixel on each axis, angles are in
                          degrees.)
     CRINC = x.x, y.y ...(The increment in coordinate values
                          between successive pixels. )
     CRREF = x.x, y.y... (The reference pixel on each axis, need
                          not be an integer.)
     CRROT = x.x, y.y... (The rotation; by convention the
                          rotation angle on the sky is
                          associated with the declination or
                          latitude-like axis.)
     SCALE = x.x          (A scale factor to be applied to the
                           values read)
     OFFSET = y.y         (An offset to be added to the values
                           read after any scaling.)
     BLANK = b.b          The blanked (undefined) value BEFORE
                          any scaling and offset.

   The header section is terminated by a '/'.  Following this is
the data stored by row (first axis) with the other axes given
with the lower numbered axes varying the fastest.

                 ERROR CONDITIONS

   Most possible errors have more-or-less explanatory messages.
However, if either a scaled pixel value blows the format or a
line exceeds the maximum number (1000) of characters then the
message: "ERROR WRITING OUTPUT TEXT LINE" will be issued and the
task will die.