Документ взят из кэша поисковой машины. Адрес оригинального документа : http://vega.inp.nsk.su/~inest/OCAAS/cfitsio.pdf Дата изменения: Sun Oct 13 19:10:26 2002 Дата индексирования: Mon Oct 1 19:55:38 2012 Кодировка: Поисковые слова: trees

CFITSIO User's Guide
An Interface to FITS Format Files for C Programmers
Version 2.0

HEASARC Code 662 Goddard Space FlightCenter Greenbelt, MD 20771 USA

February 2000



Contents
1 Introduction 2 Creating the CFITSIO Library
2.1 Building the Library 2.1.1 Unix Systems 2.1.2 VMS 2.1.3 Windows PCs 2.1.4 OS/2 2.1.5 Macintosh PCs 2.2 Testing the Library 2.3 Linking Programs with CFITSIO 2.4 Getting Started with CFITSIO 2.5 Example Program 2.6 Acknowledgements
:::::::::::::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::

1 3
3 3 5 5 5 5 6 7 7 8 9

::::::::::::::::::::::::::::::::::::::::: ::::::::::::::::::::::::::::::::::::

:::::::::::::::::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::

::::::::::::::::::::::::::::::::::::: :::::::::::::::::::::::::::::

::::::::::::::::::::::::::::::

::::::::::::::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::

3 A FITS Primer 4 Extended File Name Syntax
4.1 Overview 4.2 Detailed Filename Syntax 4.2.1 Filetype 4.2.2 Base Filename 4.2.3 Output File Name when Opening an Existing File 4.2.4 Template File Name when Creating a New File 4.2.5 HDU Location Speci cation i
:::::::::::::::::::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::

11 13
13 15 16 19 20 21 25

::::::::::::::::::::::::::::::::::::::: ::::::::::::::::::::::::::::::::::: :::::::::::::::

:::::::::::::::::

::::::::::::::::::::::::::::


ii 4.2.6 4.2.7 4.2.8 4.2.9 5.1 5.2 5.3 5.4 5.5 5.6 5.7 5.8 5.9 5.10 5.11 5.12 5.13 5.14 Image Section Column and Keyword Filtering Speci cation Row Filtering Speci cation Binning or Histogramming Speci cation

CONTENTS
:::::::::::::::::::::::::::::::::::: ::::::::::::::::::

:::::::::::::::::::::::::::: :::::::::::::::::::::

26 27 28 35

5 CFITSIO Conventions and Guidelines

CFITSIO De nitions CFITSIO Size Limitations Multiple Access to the Same FITS File Current Header Data Unit (CHDU) Function Names and Datatypes Unsigned Integers Character Strings Implicit Data Type Conversion Data Scaling Error Status Values and the Error Message Stack Variable-Length Arrays in Binary Tables Support for IEEE Special Values When the Final Size of the FITS HDU is Unknown Local FITS Conventions supported by CFITSIO 5.14.1 Long String Keyword Values. 5.14.2 Arrays of Fixed-Length Strings in Binary Tables 5.14.3 Keyword Units Strings 5.14.4 HIERARCH Convention for Extended Keyword Names 5.15 Optimizing Code for Maximum Processing Speed 5.15.1 Background Information: How CFITSIO Manages Data I/O 5.15.2 Optimization Strategies 6.1 The Iterator Work Function 6.2 The Iterator Driver Function 6.3 Guidelines for Using the Iterator Function

39

:::::::::::::::::::::::::::::::::::: ::::::::::::::::::::::::::::::::: ::::::::::::::::::::::::::

:::::::::::::::::::::::::::

::::::::::::::::::::::::::::::

:::::::::::::::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::: ::::::::::::::::::::::::::::::

:::::::::::::::::::::::::::::::::::::::: ::::::::::::::::::::

:::::::::::::::::::::::::

::::::::::::::::::::::::::::: :::::::::::::::::::

::::::::::::::::::::

::::::::::::::::::::::::::: ::::::::::::::::

::::::::::::::::::::::::::::::: ::::::::::::

:::::::::::::::::::: :::::::::

::::::::::::::::::::::::::::::

39 41 42 42 42 44 46 47 47 47 48 50 50 51 51 52 52 53 54 54 55 60 62 63

6 The CFITSIO Iterator Function

59

:::::::::::::::::::::::::::::::: ::::::::::::::::::::::::::::::: ::::::::::::::::::::::::


CONTENTS

iii

7 Basic CFITSIO Interface Routines
7.1 7.2 7.3 7.4 7.5 7.6 7.7

7.8

7.9 7.10 7.11 7.12 7.13

CFITSIO Error Status Routines FITS File Access Routines HDU Access Routines Header Keyword Read/Write Routines Iterator Routines Primary Array or IMAGE Extension I/O Routines ASCII and Binary Table Routines 7.7.1 Column Information Routines 7.7.2 Routines to Edit Rows or Columns 7.7.3 Read and Write Column Data Routines Celestial Coordinate System Routines 7.8.1 Self-contained WCS Routines 7.8.2 WCS Routines that require the WCS library Hierarchical Grouping Convention Support Routines Row Selection and Calculator Routines File Checksum Routines Date and Time UtilityRoutines General Utility Routines

65

:::::::::::::::::::::::::::::

:::::::::::::::::::::::::::::::::

::::::::::::::::::::::::::::::::::: ::::::::::::::::::::::::::

:::::::::::::::::::::::::::::::::::::: :::::::::::::::::::

:::::::::::::::::::::::::::: :::::::::::::::::::::::::: ::::::::::::::::::::::: :::::::::::::::::::::

:::::::::::::::::::::::::: :::::::::::::::::::::::::: :::::::::::::::::: ::::::::::::::::::

::::::::::::::::::::::::::

:::::::::::::::::::::::::::::::::: :::::::::::::::::::::::::::::

:::::::::::::::::::::::::::::::::

65 66 69 71 74 76 77 78 80 81 83 84 85 87 92 93 95 96

8 Specialized CFITSIO Interface Routines

8.1 Specialized FITS File Access Routines 8.2 Specialized HDU Access Routines 8.3 Specialized Header Keyword Routines 8.3.1 Header Information Routines 8.3.2 Read and Write the Required Keywords 8.3.3 Specialized Write Keyword Routines 8.3.4 Insert Keyword Routines 8.3.5 Specialized Read Keyword Routines 8.3.6 Modify Keyword Routines 8.3.7 Specialized Update Keyword Routines 8.4 De ne Data Scaling and Unde ned Pixel Parameters

103
103 104 106 106 106 108 110 111 113 114 114

::::::::::::::::::::::::::

::::::::::::::::::::::::::::: ::::::::::::::::::::::::::

::::::::::::::::::::::::::: :::::::::::::::::::::

:::::::::::::::::::::::

::::::::::::::::::::::::::::: :::::::::::::::::::::::

:::::::::::::::::::::::::::: ::::::::::::::::::::: ::::::::::::::::::


iv 8.5 Specialized FITS Primary Arrayor IMAGE Extension I/O Routines 8.6 Specialized FITS ASCII and Binary Table Routines 8.6.1 Column Information Routines 8.6.2 Low-Level Table Access Routines 8.6.3 Specialized Write Column Data Routines 8.6.4 Specialized Read Column Data Routines

CONTENTS
::::::::: ::::::::::::::::::

::::::::::::::::::::::::::: :::::::::::::::::::::::: ::::::::::::::::::::

:::::::::::::::::::::

116 119 119 120 121 122

A Index of Routines B Parameter De nitions C CFITSIO Error Status Codes

127 131 137


Chapter 1

Introduction
CFITSIO is a machine-independent library of routines for reading and writing data les in the FITS (Flexible Image Transport System) data format. It can also read IRAF format image les by converting them on the y into a temporary FITS format le. This library is written in ANSI C and provides a powerful yet simple interface for accessing FITS les which will run on most commonly used computers and workstations. CFITSIO supports all the features described in the o cial NOST de nition of the FITS format and can read and write all the currently de ned types of extensions, including ASCII tables (TABLE), Binary tables (BINTABLE) and IMAGE extensions. The CFITSIO routines insulate the programmer from having to deal with the complicated formatting details in the FITS le, however, it is assumed that users have a general knowledge about the structure and usage of FITS les. CFITSIO also contains a set of Fortran callable wrapper routines which allow Fortran programs to call the CFITSIO routines. See the companion \FITSIO User's Guide" for the de nition of the Fortran subroutine calling sequences. These wrappers replace the older Fortran FITSIO library which is no longer supported. The CFITSIO package was initially developed by the HEASARC (High Energy Astrophysics Science Archive Research Center) at the NASA Goddard Space Flight Center to convert various existing and newly acquired astronomical data sets into FITS format and to further analyze data already in FITS format. New features continue to be added to CFITSIO in large part due to contributions of ideas or actual code from users of the package. The Integral Science Data Center in Switzerland, and the XMM/ESTEC pro ject in The Netherlands made especially signi cant contributions that resulted in many of the new features that appeared in v2.0 of CFITSIO. The latest version of the CFITSIO source code, documentation, and example programs are available on the World-Wide Web or via anonymous ftp from:
http://heasarc.gsfc.nasa.gov/fitsio ftp://legacy.gsfc.nasa.gov/software/fitsio/c

Any questions, bug reports, or suggested enhancements related to the CFITSIO package should be sent to the primary author: 1


2
Dr. William Pence HEASARC, Code 662 NASA/Goddard Space Flight Center Greenbelt, MD 20771, USA

CHAPTER 1. INTRODUCTION
Telephone: (301) 286-4599 E-mail: pence@tetra.gsfc.nasa.gov

This User's Guide assumes that readers already have a general understanding of the de nition and structure of FITS format les. Further information about FITS formats is available in the `FITS User's Guide' and the `NOST FITS Standard', whichare available from the NASA Science O ce of Standards and Technology at the address given below. Both of these documents are available electronically from their Web site and via anonymous ftp at nssdc.gsfc.nasa.gov in the /pub/ ts directory. Any questions about FITS formats should be directed to the NOST, at:
NASA, Science Office of Standards and Technology Code 633.2, Goddard Space Flight Center Greenbelt MD 20771, USA WWW: http://www.gsfc.nasa.gov/astro/fits/fits_home.html E-mail: fits@nssdca.gsfc.nasa.gov (301) 286-2899

CFITSIO users may also be interested in the FTOOLS package of programs that can be used to manipulate and analyze FITS format les. Information about FTOOLS can be obtained on the Web or via anonymous ftp at:
http://heasarc.gsfc.nasa.gov/ftools ftp://legacy.gsfc.nasa.gov/software/ftools/release


Chapter 2

Creating the CFITSIO Library
2.1 Building the Library
The CFITSIO code is contained in about 40 C source les (*.c) and header les (*.h). On VAX/VMS systems 2 assembly-code les (vmsieeed.mar and vmsieeer.mar) are also needed. CFITSIO has currently been tested on the following platforms:
OPERATING SYSTEM Sun OS Sun Solaris Silicon Graphics IRIX Dec Alpha OSF/1 DECstation Ultrix Dec Alpha OpenVMS DEC VAX/VMS HP-UX IBM AIX Linux MkLinux Windows 95/98 Windows NT OS/2 MacOS 7.1 or greater COMPILER gcc and cc (3.0.1) gcc and cc gcc and cc gcc and cc gcc cc gcc and cc gcc gcc gcc DR3 Borland C++ V4.5 Microsoft Visual C++ v5.0, v6.0 gcc + EMX Metrowerks 10.+

CFITSIO will probably run on most other Unix platforms. Cray supercomputers and IBM mainframe computers are currently not supported.

2.1.1 Unix Systems
The CFITSIO library is built on Unix systems bytyping: 3


4
> ./configure > make

CHAPTER 2. CREATING THE CFITSIO LIBRARY

at the operating system prompt. Type ./con gure and not simply `con gure' to ensure that the con gure script in the current directory is run and not some other system-wide con gure script. The con gure command customizes the Make le for the particular system, then the `make' command compiles the source les and builds the library. On HP/UX systems, the environmentvariable CFLAGS should be set to -Ae before running congure to enable "extended ANSI" features. By default, a set of Fortran-callable wrapper routines are also built and included in the CFITSIO library. If these wrapper routines are not needed (i.e., the CFITSIO library will not be linked to any Fortran applications which call FITSIO subroutines) then they may be omitted from the build bytyping 'make all-no tsio' instead of simply typing 'make'. This will reduce the size of the CFITSIO library slightly. It may not be possible to staticly link programs that use CFITSIO on some platforms (namely, on Solaris 2.6) due to the network drivers (which provide FTP and HTTP access to FITS les). It is possible to make both a dynamic and a static version of the CFITSIO library, but network le access will not be possible using the static version. To build the dynamic libc tsio.so library (on solaris), type 'make clean', then edit the Make le to add -fPIC or -KPIC (gcc or cc) to the CFLAGS line, then rebuild the library with 'make'. Once you're done, build the shared library with
ld -G -z text -o libcfitsio.so *.o

Then to get the staticly linkable libc tsio.a library le do another make clean, unde ne HAVE NET SERVICES on the CFLAGS line and rebuild. It's unimportant whether or not you use -fPIC for static builds. When using the shared library the executable code is not copied into your program at link time and instead the program locates the necessary library code at run time, normally through LD LIBRARY PATH or some other method. The advantages are:
1. 2. Less disk space if you build more than 1 program Less memory if more than one copy of a program using the shared library is running at the same time since the system is smart enough to share copies of the shared library at run time. Possibly easier maintenance since a new version of the shared library can be installed without relinking all the software that uses it (as long as the subroutine names and calling sequences remain unchanged). No run-time penalty.

3.

4.

The disadvantages are:


2.1. BUILDING THE LIBRARY
1. More hassle at runtime. You have to either build the programs specially or have LD_LIBRARY_PATH set right. 2. There may be a slight start up penality, depending on where you are reading the shared library and the program from and if your CPU is either really slow or really heavily loaded.

5

2.1.2 VMS
On VAX/VMS and ALPHA/VMS systems the make.com command le may be used to build the c tsio.olb ob ject library using the default G- oating point option for double variables. The make d oat.com and make ieee.com les may be used instead to build the library with the other oating point options. Note that the getcwd function that is used in the group.c module may require that programs using CFITSIO be linked with the ALPHA$LIBRARY:VAXCRTL.OLB library. See the example link line in the next section of this document.

2.1.3 Windows PCs
A precompiled DLL version of CFITSIO is available for IBM-PC users in the le c tsio dll.zip. This zip archivealsocontains other les and instructions on how to use the CFITSIO DLL library. The CFITSIO library may be built using a suitable compiler. The makepc.bat le gives an example of how to build CFITSIO with the Borland C++ v4.5 compiler. This le will probably need to be edited to include the appropriate command switches if a di erent C compiler or linker is used. The les c tsio.dsp, c tsio.dsw, and cookbook.dsp contain the Microsoft Developer workspace les for building CFITSIO and the cookbook example program on WindowsNT using Microsoft Visual C++ 5.0 or 6.0.

2.1.4 OS/2
On OS/2 systems, CFITSIO can be built by typing 'make -f make le.os2'. This make le requires the GCC compiler and EMX library, which are available from manyInternet sites containing OS/2 software, suchas
ftp-os2.nmsu.edu/pub/os2/dev/emx/v0.9c and ftp.leo.org/pub/comp/os/os2/leo/devtools/emx+gcc.

2.1.5 Macintosh PCs
The MacOS version of the CFITSIO library can be built by (1) un binhex and unstu c tsio mac.sit.hqx, (2) put CFitsioPPC.mcp in the c tsio directory, and (3) load CFitsioPPC.mcp into CodeWarrior Pro 2 and make. This builds the c tsio library for PPC. There are also targets for both the test program and the speed test program.


6

CHAPTER 2. CREATING THE CFITSIO LIBRARY

To use the MacOS port you can add C tsio PPC.lib to your CodeWarrior Pro 2 pro ject. Note that this only has been tested for the PPC and probably won't work on 68k Macs.

2.2 Testing the Library
The CFITSIO library should be tested by building and running the testprog.c program that is included with the release. On Unix systems, type:
% % % % make testprog testprog > testprog.lis diff testprog.lis testprog.out cmp testprog.fit testprog.std

On VMS systems, (assuming cc is the name of the C compiler command), type:
$ cc testprog.c $ link testprog, cfitsio/lib, alpha$library:vaxcrtl/lib $ run testprog

The testprog program should produce a FITS le called `testprog. t' that is identical to the `testprog.std' FITS le included with this release. The diagnostic messages (whichwere piped to the le testprog.lis in the Unix example) should be identical to the listing contained in the le testprog.out. The 'di ' and 'cmp' commands shown above should not report any di erences in the les. (There may be some minor formating di erences, such as the presence or absence of leading zeros, or 3 digit exponents in numbers, which can be ignored). The Fortran wrappers in CFITSIO may be tested with the testf77 program on Unix systems with:
% f77 -o testf77 testf77.f -L. -lcfitsio -lnsl -lsocket or % f77 -f -o testf77 testf77.f -L. -lcfitsio or % f77 -o testf77 testf77.f -Wl,-L. -lcfitsio -lm -lnsl -lsocket (HP/UX) % testf77 > testf77.lis % diff testf77.lis testf77.out % cmp testf77.fit testf77.std (under SUN O/S)

On machines running SUN O/S, Fortran programs must be compiled with the '-f ' option to force double precision variables to be aligned on 8-byte boundarys to make the fortran-declared variables compatible with C. A similar compiler option may be required on other platforms. Failing to use this option may cause the program to crash on FITSIO routines that read or write double precision variables.


2.3. LINKING PROGRAMS WITH CFITSIO

7

Also note that on some systems, the output listing of the testf77 program may di er slightly from the testf77.std template, if leading zeros are not printed by default before the decimal point when using F format. A few other utility programs are included with CFITSIO:
speed - measures the maximum throughput (in MB per second) for writing and reading FITS files with CFITSIO. listhead - lists all the header keywords in any FITS file fitscopy - copies any FITS file (especially useful in conjunction with the CFITSIO's extended input filename syntax). cookbook - a sample program that peforms common read and write operations on a FITS file. iter_a, iter_b, iter_c - tests of the CFITSIO iterator routine

The rst 4 of these utility programs can be compiled and linked bytyping
% make program_name

2.3 Linking Programs with CFITSIO
When linking applications software with the CFITSIO library,several system libraries usually need to be speci ed on the link comma Unix systems, the most reliable way to determine what libraries are required is to type 'make testprog' and see what libraries the con gure script has added. The typical libraries that need to be added are -lm (the math library) and -lnsl and -lsocket (needed only for FTP and HTTP le access). These latter 2 libraries are not needed on VMS and Windows platforms, because FTP le access is not currently supported on those platforms. Note that when upgrading to a newer version of CFITSIO it is usually necessay to recompile, as well as relink, the programs that use CFITSIO, because the de nitions in tsio.h often change.

2.4 Getting Started with CFITSIO
In order to e ectively use the CFITSIO library as quickly as possible, it is recommended that new users follow these steps: 1. Read the following `FITS Primer' chapter for an overview of the structure of FITS les. This is especially important for users who are unfamiliar with the FITS table and image extensions. 2. Review the various topics discussed in Chapters 4 and 5 to become familiar with the conventions and advanced features of the CFITSIO interface.


8

CHAPTER 2. CREATING THE CFITSIO LIBRARY

3. Refer to the cookbook.c, listhead.c, and tscopy.c programs that are included with this release for examples of routines that perform various common FITS le operations. Type 'make program name' to compile and link these programs on Unix systems. 4. Write a simple program to read or write a FITS le using the Basic Interface routines described in Chapter 7. 5. Scan through the more specialized routines that are described in Chapter 8 to become familiar with the functionality that they provide.

2.5 Example Program
The following listing shows an example of how to use the CFITSIO routines in a C program. The error checking of the returned status value has been omitted for the sake of clarity. Refer to the cookbook.c program that is included with the CFITSIO distribution for other example programs. This program creates a new FITS le, containing a FITS image. An `EXPOSURE' keyword is written to the header, then the image data are writen to the FITS le before closing the FITS le.
#include "fitsio.h" /* required by every program that uses CFITSIO */ main() { fitsfile *fptr /* pointer to the FITS file defined in fitsio.h */ int status, ii, jj long fpixel = 1, naxis = 2, nelements, exposure long naxes 2] = { 300, 200 } /* image is 300 pixels wide by 200 rows */ short array 200] 300] status = 0 /* initialize status before calling fitsio routines */ fits_create_file(&fptr, "testfile.fits", &status) /* create new file */ /* Create the primary array image (16-bit short integer pixels */ fits_create_img(fptr, SHORT_IMG, naxis, naxes, &status) /* Write a keyword must pass the ADDRESS of the value */ exposure = 1500. fits_update_key(fptr, TLONG, "EXPOSURE", &exposure, "Total Exposure Time", &status) /* Initialize the values in the image with a linear ramp function */ for (jj = 0 jj < naxes 1] jj++) for (ii = 0 ii < naxes 0] ii++) array jj] ii] = ii + jj nelements = naxes 0] * naxes 1] /* number of pixels to write */


2.6. ACKNOWLEDGEMENTS
/* Write the array of integers to the image */ fits_write_img(fptr, TSHORT, fpixel, nelements, array 0], &status) fits_close_file(fptr, &status) fits_report_error(stderr, status) return( status ) } /* close the file */ /* print out any error messages */

9

2.6 Acknowledgements
The development of manyof the powerful features in CFITSIO was made possible through collaborations with many people or organizations from around the world. The following, in particular, have made especially signi cantcontributions: Programmers from the Integral Science Data Center, Switzerland (namely, Jurek Borkowski, Bruce O'Neel, and Don Jennings), designed the concept for the plug-in I/O drivers that was introduced with CFITSIO 2.0. The use of `drivers' greatly simpli ed the low-level I/O, which in turn made other new features in CFITSIO (e.g., support for compressed FITS les and support for IRAF format image les) much easier to implement. Jurek Borkowski wrote the Shared Memory driver, and Bruce O'Neel wrote the drivers for accessing FITS les over the network using the FTP,HTTP, and ROOT protocols. The ISDC also provided the template parsing routines (written by Jurek Borkowski) and the hierarchical grouping routines (written by Don Jennings). The ISDC DAL (Data Access Layer) routines are layered on top of CFITSIO and make extensive use of these features. Uwe Lammers (XMM/ESA/ESTEC, The Netherlands) designed the high-performance lexical parsing algorithm that is used to do on-the- y ltering of FITS tables. This algorithm essentially pre-compiles the user-supplied selection expression into a form that can be rapidly evaluated for eachrow. Peter Wilson (RSTX, NASA/GSFC) then wrote the parsing routines used by CFITSIO based on Lammers' design, combined with other techniques such as the CFITSIO iterator routine to further enhance the data processing throughput. This e ort also bene tted from a much earlier lexical parsing routine that was developed byKentBlackburn (NASA/GSFC). The CFITSIO iterator function is loosely based on similar ideas developed for the XMM Data Access Layer. Peter Wilson (RSTX, NASA/GSFC) wrote the complete set of Fortran-callable wrappers for all the CFITSIO routines, which in turn rely on the CFORTRAN macro developed by Burkhard Burow. The syntax used by CFITSIO for ltering or binning input FITS les is based on ideas developed for the AXAF Science Center Data Model by Jonathan McDowell, Antonella Fruscione, Aneta Siemiginowska and Bill Joye. See http://heasarc.gsfc.nasa.gov/docs/journal/axaf7.html for further description of the AXAF Data Model. The le decompression code were taken directly from the gzip (GNU zip) program developed by Jean-loup Gailly and others.


10

CHAPTER 2. CREATING THE CFITSIO LIBRARY

Doug Mink, SAO, provided the routines for converting IRAF format images into FITS format. In addition, many other people havemade valuable contributions to the development of CFITSIO. These include (with apologies to others that mayhave inadvertently been omitted): Steve Allen, Carl Akerlof, Keith Arnaud, Morten Krabbe Barfoed, Kent Blackburn, G Bodammer, RomkeBontekoe, Lucio Chiappetti, Keith Costorf, Robin Corbet, John Davis, Richard Fink, Ning Gan, Emily Greene, Gretchen Green, Joe Harrington, Cheng Ho, Phil Hodge, Jim Ingham, Yoshitaka Ishisaki, Diab Jerius, Mark Levine, Todd Karakaskian, Edward King, Scott Koch, Claire Larkin, Rob Managan, Eric Mandel, John Mattox, Carsten Meyer, Emi Miyata, Stefan Mochnacki, Mike Noble, Oliver Oberdorf, Clive Page, Arvind Parmar, Je Pedelty, Tim Pearson, Maren Purves, Scott Randall, Chris Rogers, Arnold Rots, Barry Schlesinger, Robin Stebbins, Andrew Szymkowiak, Allyn Tennant, Peter Teuben, James Theiler, Doug Tody, Shiro Ueno, Steve Walton, Archie Warnock, Alan Watson, Dan Whipple, Wim Wimmers, Peter Young, Jianjun Xu, and Nelson Zarate.


Chapter 3

A FITS Primer
This section gives a brief overview of the structure of FITS les. Users should refer to the documentation available from the NOST, as described in the introduction, for more detailed information on FITS formats. FITS was rst developed in the late 1970's as a standard data interchange format between various astronomical observatories. Since then FITS has become the standard data format supported by most astronomical data analysis software packages. A FITS le consists of one or more Header + Data Units (HDUs), where the rst HDU is called the `Primary HDU', or `Primary Array'. The primary array contains an N-dimensional array of pixels, such as a 1-D spectrum, a 2-D image, or a 3-D data cube. Five di erent primary datatypes are supported: Unsigned 8-bit bytes, 16 and 32-bit signed integers, and 32 and 64-bit oating point reals. FITS also has a convention for storing 16 and 32-bit unsigned integers (see the later section entitled `Unsigned Integers' for more details). The primary HDU may also consist of only a header with a null arraycontaining no data pixels. Any number of additional HDUs may follow the primary array these additional HDUs are called FITS `extensions'. There are currently 3 types of extensions de ned by the FITS standard: Image Extension - a N-dimensional array of pixels, like in a primary array ASCII Table Extension - rows and columns of data in ASCII character format Binary Table Extension - rows and columns of data in binary representation In each case the HDU consists of an ASCII Header Unit followed by an optional Data Unit. For historical reasons, each Header or Data unit must be an exact multiple of 2880 8-bit bytes long. Anyunused space is padded with ll characters (ASCII blanks or NULs depending on the type of unit). Each Header Unit consists of anynumber of 80-character keyword records or `card images' (reminiscent of the 80-column punched cards whichwere prevalent when the FITS standard was developed) whichhave the general form: 11


12

CHAPTER 3. A FITS PRIMER
KEYNAME = value / comment string NULLKEY = / comment: This keyword has no value

The keyword names may be up to 8 characters long and can only contain uppercase letters, the digits 0-9, the hyphen, and the underscore character. The keyword name is (usually) followed byan equals sign and a space character (= ) in columns 9 - 10 of the record, followed by the value of the keyword which may be either an integer, a oating point number, a character string (enclosed in single quotes), or a boolean value (the letter T or F). A keyword may also haveanull or unde ned value if there is no speci ed value string, as in the second example. The last keyword in the header is always the `END' keyword which has no value or comment elds. There are manyrules governing the exact format of a keyword record (see the NOST FITS Standard) so it is better to rely on standard interface software like CFITSIO to correctly construct or to parse the keyword records rather than try to deal directly with the raw FITS formats. Each Header Unit begins with a series of required keywords which depend on the type of HDU. These required keywords specify the size and format of the following Data Unit. The header may contain other optional keywords to describe other aspects of the data, such as the units or scaling values. Other COMMENT or HISTORYkeywords are also frequently added to further document the data le. The optional Data Unit immediately follows the last 2880-byte block in the Header Unit. Some HDUs do not have a Data Unit and only consist of the Header Unit. If there is more than one HDU in the FITS le, then the Header Unit of the next HDU immediately follows the last 2880-byte block of the previous Data Unit (or Header Unit if there is no Data Unit). The main required keywords in FITS primary arrays or image extensions are: BITPIX { de nes the datatype of the array: 8, 16, 32, -32, -64 for unsigned 8{bit byte, 16{bit integer, 32{bit integer, 32{bit IEEE oating point, and 64{bit IEEE double precision oating point, respectively. NAXIS { the number of dimensions in the array, usually 0, 1, 2, 3, or 4. NAXISn { (n ranges from 1 to NAXIS) de nes the size of each dimension. FITS tables start with the keyword XTENSION = `TABLE' (for ASCII tables) or XTENSION = `BINTABLE' (for binary tables) and have the following main keywords: TFIELDS { number of elds or columns in the table NAXIS2 { number of rows in the table TTYPEn { for each column (n ranges from 1 to TFIELDS) gives the name of the column TFORMn { the datatype of the column TUNITn { the physical units of the column (optional) Users should refer to the NOST documentation for more details about the required keywords and their allowed values.


Chapter 4

Extended File Name Syntax
4.1 Overview
CFITSIO supports an extended syntax when specifying the name of the data le to be opened or created that includes the following features: CFITSIO can read IRAF format images which have header le names that end with the '.imh' extension, as well as reading and writing FITS les, This feature is implemented in CFITSIO by rst converting the IRAF image into a temporary FITS format le in memory, then opening the FITS le. Any of the usual CFITSIO routines then may be used to read the image header or data. FITS les on the internet can be read (and sometimes written) using the FTP, HTTP, or ROOT protocols. FITS les can be piped between tasks on the stdin and stdout streams. FITS les can be read and written in shared memory. This can potentially achievemuch better data I/O performance compared to reading and writing the same FITS les on magnetic disk. Compressed FITS les in gzip or Unix COMPRESS format can be directly read. FITS table columns can be created, modi ed, or deleted 'on-the- y' as the table is opened by CFITSIO. This creates a virtual FITS le c