Chapter 2 Creating FITSIO/CFITSIO
2.1 Building the Library
To use the FITSIO subroutines one must first build the CFITSIO library,
which requires a C compiler. gcc is ideal, or most other ANSI-C
compilers will also work. The CFITSIO code is contained in about 40 C
source files (*.c) and header files (*.h). On VAX/VMS systems 2
assembly-code files (vmsieeed.mar and vmsieeer.mar) are also needed.
The Fortran interface subroutines to the C CFITSIO routines are located
in the f77_wrap1.c, through f77_wrap4.c files. These are relatively simple
'wrappers' that translate the arguments in the Fortran subroutine into
the appropriate format for the corresponding C routine. This
translation is performed transparently to the user by a set of C macros
located in the cfortran.h file. Unfortunately cfortran.h does not
support every combination of C and Fortran compilers so the Fortran
interface is not supported on all platforms. This is especially true
for PC and Mac users (see further notes below).
A standard combination of C and Fortran compilers will be assumed by
default, but one may also specify a particular Fortran compiler by
doing:
> setenv CFLAGS -DcompilerName=1
(where 'compilerName' is the name of the compiler) before running
the configure command. The currently recognized compiler
names are:
g77Fortran
IBMR2Fortran
CLIPPERFortran
pgiFortran
NAGf90Fortran
f2cFortran
hpuxFortran
apolloFortran
sunFortran
CRAYFortran
mipsFortran
DECFortran
vmsFortran
CONVEXFortran
PowerStationFortran
AbsoftUNIXFortran
AbsoftProFortran
SXFortran
Alternatively, one may edit the CFLAGS line in the Makefile to add the
'-DcompilerName' flag after running the './configure' command.
The CFITSIO library is built on Unix systems by typing:
> ./configure [--prefix=/target/installation/path]
> make (or 'make shared')
> make install (this step is optional)
at the operating system prompt. The configure command customizes the
Makefile for the particular system, then the `make' command compiles the
source files and builds the library. Type `./configure' and not simply
`configure' to ensure that the configure script in the current directory
is run and not some other system-wide configure script. The optional
'prefix' argument to configure gives the path to the directory where
the CFITSIO library and include files should be installed via the later
'make install' command. For example,
> ./configure --prefix=/usr1/local
will cause the 'make install' command to copy the CFITSIO libcfitsio file
to /usr1/local/lib and the necessary include file to /usr1/local/include
(assuming of course that the process has permission to write to these
directories).
By default this also builds the set of Fortran-callable
wrapper routines whose calling sequences are described later in this
document.
The 'make shared' option builds a shared or dynamic version of the
CFITSIO library. 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 of using a shared
library are:
1. Less disk space if you build more than 1 program
2. 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.
3. 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).
4. No run-time penalty.
The disadvantages are:
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 penalty, 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.
On HP/UX systems, the environment variable CFLAGS should be set
to -Ae before running configure to enable "extended ANSI" features.
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 files). It is possible to
make both a dynamic and a static version of the CFITSIO library, but
network file access will not be possible using the static version.
On VAX/VMS and ALPHA/VMS systems the make_gfloat.com command file may
be executed to build the cfitsio.olb object library using the default
G-floating point option for double variables. The make_dfloat.com and
make_ieee.com files may be used instead to build the library with the
other floating 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.
On Windows IBM-PC type platforms the situation is more complicated
because of the wide variety of Fortran compilers that are available and
because of the inherent complexities of calling the CFITSIO C routines
from Fortran. Two different versions of the CFITSIO dll library are
available, compiled with the Borland C++ compiler and the Microsoft
Visual C++ compiler, respectively, in the files
cfitsiodll_2xxx_borland.zip and cfitsiodll_2xxx_vcc.zip, where
'2xxx' represents the current release number. Both these dll libraries
contain a set of Fortran wrapper routines which may be compatible with
some, but probably not all, available Fortran compilers. To test if
they are compatible, compile the program testf77.f and try linking to
these dll libraries. If these libraries do not work with a particular
Fortran compiler, then there are 2 possible solutions. The first
solution would be to modify the file cfortran.h for that particular
combination of C and Fortran compilers, and then rebuild the CFITSIO
dll library. This will require, however, a great deal of expertise in
mixed language programming which the author of CFITSIO cannot provide.
The other solution is to use the older v5.03 Fortran-77 implementation
of FITSIO that is still available from the FITSIO web-site. This
version is no longer supported, but it does provide the basic functions
for reading and writing FITS files and should be compatible with most
Fortran compilers.
CFITSIO has currently been tested on the following platforms:
OPERATING SYSTEM COMPILER
Sun OS gcc and cc (3.0.1)
Sun Solaris gcc and cc
Silicon Graphics IRIX gcc and cc
Silicon Graphics IRIX64 MIPS
Dec Alpha OSF/1 gcc and cc
DECstation Ultrix gcc
Dec Alpha OpenVMS cc
DEC VAX/VMS gcc and cc
HP-UX gcc
IBM AIX gcc
Linux gcc
MkLinux DR3
Windows 95/98/NT Borland C++ V4.5
Windows 95/98/NT/ME/XP Microsoft/Compaq Visual C++ v5.0, v6.0
Windows 95/98/NT Cygwin gcc
OS/2 gcc + EMX
MacOS 7.1 or greater Metrowerks 10.+
CFITSIO will probably run on most other Unix platforms. Cray
supercomputers are currently not supported.
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 file called `testprog.fit'
that is identical to the `testprog.std' FITS file included with this
release. The diagnostic messages (which were piped to the file
testprog.lis in the Unix example) should be identical to the listing
contained in the file testprog.out. The 'diff' and 'cmp' commands
shown above should not report any differences in the files. (There
may be some minor formatting differences, 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 the fortran compilation and link command
may be called 'f77' or 'g77', depending on the system.
% f77 -o testf77 testf77.f -L. -lcfitsio -lnsl -lsocket
or
% f77 -f -o testf77 testf77.f -L. -lcfitsio (under SUN O/S)
or
% f77 -o testf77 testf77.f -Wl,-L. -lcfitsio -lm -lnsl -lsocket (HP/UX)
or
% g77 -o testf77 -s testf77.f -lcfitsio -lcc_dynamic -lncurses (Mac OS-X)
% testf77 > testf77.lis
% diff testf77.lis testf77.out
% cmp testf77.fit testf77.std
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.
Also note that on some systems, the output listing of the testf77
program may differ 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 - examples of the CFITSIO iterator routine
The first 4 of these utility programs can be compiled and linked by typing
% make program_name
2.3 Linking Programs with FITSIO
When linking applications software with the FITSIO library, several system libraries usually need to be specified on the link comman
Unix systems, the most reliable way to determine what libraries are required
is to type 'make testprog' and see what libraries the configure script has
added. The typical libraries that may need to be added are -lm (the math
library) and -lnsl and -lsocket (needed only for FTP and HTTP file access).
These latter 2 libraries are not needed on VMS and Windows platforms,
because FTP file 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 definitions in fitsio.h often change.
2.4 Getting Started with FITSIO
In order to effectively use the FITSIO library as quickly as possible,
it is recommended that new users follow these steps:
1. Read the following `FITS Primer' chapter for a brief
overview of the structure of FITS files. This is especially important
for users who have not previously dealt with the FITS table and image
extensions.
2. Write a simple program to read or write a FITS file using the Basic
Interface routines.
3. Refer to the cookbook.f program that is included with this release
for examples of routines that perform various common FITS file
operations.
4. Read Chapters 4 and 5 to become familiar with the conventions and
advanced features of the FITSIO interface.
5. Scan through the more extensive set of routines that are provided
in the `Advanced Interface'. These routines perform more specialized
functions than are provided by the Basic Interface routines.
2.5 Example Program
The following listing shows an example of how to use the FITSIO
routines in a Fortran program. Refer to the cookbook.f program that
is included with the FITSIO distribution for examples of other
FITS programs.
program writeimage
C Create a FITS primary array containing a 2-D image
integer status,unit,blocksize,bitpix,naxis,naxes(2)
integer i,j,group,fpixel,nelements,array(300,200)
character filename*80
logical simple,extend
status=0
C Name of the FITS file to be created:
filename='ATESTFILE.FITS'
C Get an unused Logical Unit Number to use to create the FITS file
call ftgiou(unit,status)
C create the new empty FITS file
blocksize=1
call ftinit(unit,filename,blocksize,status)
C initialize parameters about the FITS image (300 x 200 16-bit integers)
simple=.true.
bitpix=16
naxis=2
naxes(1)=300
naxes(2)=200
extend=.true.
C write the required header keywords
call ftphpr(unit,simple,bitpix,naxis,naxes,0,1,extend,status)
C initialize the values in the image with a linear ramp function
do j=1,naxes(2)
do i=1,naxes(1)
array(i,j)=i+j
end do
end do
C write the array to the FITS file
group=1
fpixel=1
nelements=naxes(1)*naxes(2)
call ftpprj(unit,group,fpixel,nelements,array,status)
C write another optional keyword to the header
call ftpkyj(unit,'EXPOSURE',1500,'Total Exposure Time',status)
C close the file and free the unit number
call ftclos(unit, status)
call ftfiou(unit, status)
end
2.6 Legal Stuff
Copyright (Unpublished--all rights reserved under the copyright laws of
the United States), U.S. Government as represented by the Administrator
of the National Aeronautics and Space Administration. No copyright is
claimed in the United States under Title 17, U.S. Code.
Permission to freely use, copy, modify, and distribute this software
and its documentation without fee is hereby granted, provided that this
copyright notice and disclaimer of warranty appears in all copies.
(However, see the restriction on the use of the gzip compression code,
below).
DISCLAIMER:
THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND,
EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO,
ANY WARRANTY THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY
IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, AND FREEDOM FROM INFRINGEMENT, AND ANY WARRANTY THAT THE
DOCUMENTATION WILL CONFORM TO THE SOFTWARE, OR ANY WARRANTY THAT THE
SOFTWARE WILL BE ERROR FREE. IN NO EVENT SHALL NASA BE LIABLE FOR ANY
DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL OR
CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM, OR IN ANY WAY
CONNECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY,
CONTRACT, TORT , OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY
PERSONS OR PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED
FROM, OR AROSE OUT OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR
SERVICES PROVIDED HEREUNDER."
The file compress.c contains (slightly modified) source code that
originally came from gzip-1.2.4, copyright (C) 1992-1993 by Jean-loup
Gailly. This gzip code is distributed under the GNU General Public
License and thus requires that any software that uses the CFITSIO
library (which in turn uses the gzip code) must conform to the
provisions in the GNU General Public License. A copy of the GNU
license is included at the beginning of compress.c file.
An alternate version of the compress.c file (called
compress_alternate.c) is provided for users who want to use the CFITSIO
library but are unwilling or unable to publicly release their software
under the terms of the GNU General Public License. This alternate
version contains non-functional stubs for the file compression and
uncompression routines used by CFITSIO. Replace the file `compress.c'
with `compress_alternate.c' before compiling the CFITSIO library. This
will produce a version of CFITSIO which does not support reading or
writing compressed FITS files but is otherwise identical to the
standard version.
2.7 Acknowledgements
The development of many of 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
significant contributions:
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 simplified the low-level I/O, which in turn
made other new features in CFITSIO (e.g., support for compressed FITS
files and support for IRAF format image files) much easier to
implement. Jurek Borkowski wrote the Shared Memory driver, and Bruce
O'Neel wrote the drivers for accessing FITS files 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-fly filtering of FITS tables. This algorithm essentially
pre-compiles the user-supplied selection expression into a form that
can be rapidly evaluated for each row. 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 effort
also benefited from a much earlier lexical parsing routine that was
developed by Kent Blackburn (NASA/GSFC). More recently, Craig Markwardt
(NASA/GSFC) implemented additional functions (median, average, stddev)
and other enhancements to the lexical parser.
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 filtering or binning input FITS files 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 file decompression code were taken directly from the gzip (GNU zip)
program developed by Jean-loup Gailly and others.
Doug Mink, SAO, provided the routines for converting IRAF format
images into FITS format.
In addition, many other people have made valuable contributions to the
development of CFITSIO. These include (with apologies to others that may
have inadvertently been omitted):
Steve Allen, Carl Akerlof, Keith Arnaud, Morten Krabbe Barfoed, Kent
Blackburn, G Bodammer, Romke Bontekoe, Lucio Chiappetti, Keith Costorf,
Robin Corbet, John Davis, Richard Fink, Ning Gan, Emily Greene, 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, Jeff 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.