; 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.