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. (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]
[--enable-sse2] [--enable-ssse3]
> 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 files to /usr1/local/include (assuming of course that the process has permission to write to these directories).
The optional –enable-sse2 and –enable-ssse3 flags will cause configure to attempt to build CFITSIO using faster byte-swapping algorithms. See the "Optimizing Programs" section of this manual for more information about these options.
By default, the Makefile will be configured to build 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 statically 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_3xxx_vcc.zip, where ’3xxx’ 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 it may be necessary to modify the file "cfortran.h" to support that particular combination of C and Fortran compilers, and then rebuild the CFITSIO dll library. This will require, however, some expertise in mixed language programming.
CFITSIO should be compatible with most current ANCI C and C++ compilers: Cray supercomputers are currently not supported.
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 compiler is typically called ’gfortran’. -
% gfortran -o testf77 testf77.f -L. -lcfitsio -lz -lcurl % 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 boundaries 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.
On Windows platforms, linking Fortran programs with a C library often depends on the particular compilers involved. Some users have found the following commands work when using the Intel Fortran compiler:
ifort /libs.dll cfitsio.lib /MD testf77.f /Gm
or possibly,
ifort /libs:dll cfitsio.lib /MD /fpp /extfpp:cfortran.h,fitsio.h
/iface:cvf testf77.f
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 performs 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
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 necessary to recompile, as well as relink, the programs that use CFITSIO, because the definitions in fitsio.h often change.
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.
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
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.
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 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.
Martin Reinecke (Max Planck Institute, Garching)) provided the modifications to cfortran.h that are necessary to support 64-bit integer values when calling C routines from fortran programs. The cfortran.h macros were originally developed by Burkhard Burow (CERN).
Julian Taylor (ESO, Garching) provided the fast byte-swapping algorithms that use the SSE2 and SSSE3 machine instructions available on x86_64 CPUs.
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.