; FETCH
;---------------------------------------------------------------
;! Reads an image from an external text file.
;# Task Imaging
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2008
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
FETCH     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
FETCH     Task to read an external image in a flexible format
DATAIN                             Input file name (Non-AIPS)
OUTNAME                            Output image name (name)
OUTCLASS                           Output image name (class)
OUTSEQ           -1.0     9999.0   Output image name (seq. #)
OUTDISK           0.0        9.0   Output image disk unit #.
----------------------------------------------------------------
FETCH
Task:  Task to read an image from an external text file.  This
       file contains a header section defining to image followed
       by the image.
Adverbs:
  DATAIN.....A file external to the AIPS system from which the image
             can be read.  Use of DATAIN depends on the host operating
             system.
  OUTNAME....Output image name (name).     Standard behavior
             with default = 'FETCH MAP'.
  OUTCLASS...Output image name (class).    Standard defaults.
  OUTSEQ.....Output image name (seq. #).   0 => highest unique.
  OUTDISK....Disk drive # of output image. 0 => highest number
             with sufficient space.
----------------------------------------------------------------
FETCH:  Task reads an external, formatted file containing an
        image and converts it to an AIPS image file.
DOCUMENTOR: W. D. Cotton, NRAO.
RELATED PORGRAMS: AIPS, All AIPS image tasks.

                          PURPOSE

     FETCH is designed as a skeleton task to allow a user to
put an image or image-like data into the AIPS system.  The image
is expected to be stored in row order in a formatted text file
and to contain a header section which describes the image (see
below).  The data may be written in a variety of formats.
Blanking is supported.
Currently the data must not wrap accross multiple lines of the
text file


                        COMMENTS

DATAIN:
     The user must supply a text file containing the image and
its description.  The header section of the input file contains
a series of keyword-value pairs to define the image followed by
the data in row order.  The input file can be specified as
follows shown in the following examples:
         DATAIN='disk$res:[username]image.dat'     (VMS)
         DATAIN='myarea:image.dat'                 (Unix)
            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 pased
            to AIPS should have names containing only upper case
            characters.

   The header portion of the image file contains a number of
keyword-value pairs in free format and in arbitrary order
terminating with a '/' character.  Keywords which MUST appear in
every image are:

     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 to be used to read
                         the data. r = the repeat count; ? may
                         be either I, F, E, or D; w = the width
                         of each value in characters; d = the
                         location of the decimal point.  This
                         format will be repeated as many timeas
                         as necessary, starting a new line each
                         time, to read a row of the image.

Optional keywords are:

     OBJECT = 'name'     (The name of the object 8 char. max)
     TELESCOP = 'name'   (The name of the telescope used 8 char
                          max)
     INSTRUME ='name'    (The instrument used, 8 char. max)
     OBSERVER='name'     (The observers name, 8 char. max.)
     UNITS = 'units'     (The units of the image, 8 char max)
     EPOCH = xxxx.x      (The mean Epoch of the coordinates)
     CRTYPE='a','b'...   (The axis type (label) of each axis,
                          8 char. max.)
     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. Note: use a
                          negative increment for the RA axis.)
     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 mostly useful when the
                           data is in integer form.)
     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 '/'.  Comments may be
included preceded 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.  A simple example follows:

! Required keywords
NAXIS = 2  DIM = 5,5  FORMAT='5F5.2'
! Optional keywords
OBJECT='junk'  TELESCOP='thin air'  UNITS='JY/STR'
OBSERVER='Phantom'
EPOCH=2000.0
CRTYPE='RA---TAN','DEC--TAN'
CRVAL=180.0,40.0
CRINC=-0.1,0.1
CRREF=3.0,3.0
 /
 1.10 1.20 1.30 1.40 1.50
 2.10 2.20 2.30 2.40 2.50
 3.10 3.20 3.30 3.40 3.50
 2.10 2.20 2.30 2.40 2.50
 1.10 1.20 1.30 1.40 1.50

SIZE RESTRICTIONS
=================
Currently, FETCH will read images with dimensions less than or equal
to 1024 on a side with up to 16384 characters on each line.
