/
fitsio.doc
6615 lines (6006 loc) · 319 KB
/
fitsio.doc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
FITSIO - An Interface to FITS Format Files for Fortran Programmers
William D Pence, HEASARC, NASA/GSFC
Version 3.0
[Note: This file contains various formatting command symbols in the first
column which are used when generating the LATeX version of this document.]
*I. Introduction
This document describes the Fortran-callable subroutine interface that
is provided as part of the CFITSIO library (which is written in ANSI
C). This is a companion document to the CFITSIO User's Guide which
should be consulted for further information about the underlying
CFITSIO library. In the remainder of this document, the terms FITSIO
and CFITSIO are interchangeable and refer to the same library.
FITSIO/CFITSIO is a machine-independent library of routines for reading
and writing data files in the FITS (Flexible Image Transport System)
data format. It can also read IRAF format image files and raw binary
data arrays by converting them on the fly into a virtual FITS format
file. This library was written to provide a powerful yet simple
interface for accessing FITS files which will run on most commonly used
computers and workstations. FITSIO supports all the features described
in the official definition of the FITS format and can read and
write all the currently defined types of extensions, including ASCII
tables (TABLE), Binary tables (BINTABLE) and IMAGE extensions. The
FITSIO subroutines insulate the programmer from having to deal with the
complicated formatting details in the FITS file, however, it is assumed
that users have a general knowledge about the structure and usage of
FITS files.
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 project in The Netherlands made especially significant
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
-
\newpage
Any questions, bug reports, or suggested enhancements related to the CFITSIO
package should be sent to the FTOOLS Help Desk at the HEASARC:
-
http://heasarc.gsfc.nasa.gov/cgi-bin/ftoolshelp
-
This User's Guide assumes that readers already have a general
understanding of the definition and structure of FITS format files.
Further information about FITS formats is available from the FITS Support
Office at {\tt http://fits.gsfc.nasa.gov}. In particular, the
'FITS Standard' gives the authoritative definition of the FITS data
format. Other documents available at that Web site
provide additional historical background
and practical advice on using FITS files.
The HEASARC also provides a very sophisticated FITS file analysis
program called `Fv' which can be used to display and edit the contents
of any FITS file as well as construct new FITS files from scratch.
Fv is freely available for
most Unix platforms, Mac PCs, and Windows PCs.
CFITSIO users may also be interested in the FTOOLS package of programs
that can be used to manipulate and analyze FITS format files.
Fv and FTOOLS are available from their respective Web sites at:
-
http://fv.gsfc.nasa.gov
http://heasarc.gsfc.nasa.gov/ftools
-
*II. Creating FITSIO/CFITSIO
**A. 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. (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.
**B. 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
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
-
**C. Linking Programs with FITSIO
When linking applications software with the FITSIO library, several system libraries usually need to be specified on the link command line. On
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.
**D. 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.
**E. 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
-
**F. 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.
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."
**G. Acknowledgments
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.
*III. A FITS Primer
This section gives a brief overview of the structure of FITS files.
Users should refer to the documentation available from the FITS Support Office, as
described in the introduction, for more detailed information on FITS
formats.
FITS was first developed in the late 1970's as a standard data
interchange format between various astronomical observatories. Since
then FITS has become the defacto standard data format supported by most
astronomical data analysis software packages.
A FITS file consists of one or more Header + Data Units (HDUs), where
the first 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. Six different primary
datatypes are supported: Unsigned 8-bit bytes, 16, 32, and 64-bit signed
integers, and 32 and 64-bit floating point reals. FITS also has a
convention for storing 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 array containing 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 defined by the FITS standard:
\begin{itemize}
\item
Image Extension - a N-dimensional array of pixels, like in a primary array
\item
ASCII Table Extension - rows and columns of data in ASCII character format
\item
Binary Table Extension - rows and columns of data in binary representation
\end{itemize}
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. Any unused space is padded
with fill characters (ASCII blanks or zeros).
Each Header Unit consists of any number of 80-character keyword records
or `card images' which have the general form:
-
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 by an 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 floating point
number, a character string (enclosed in single quotes), or a boolean
value (the letter T or F). A keyword may also have a null or undefined
value if there is no specified value string, as in the second example.
The last keyword in the header is always the `END' keyword which has no
value or comment fields. There are many rules governing the exact
format of a keyword record (see the FITS Standard) so it is better
to rely on standard interface software like FITSIO 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 HISTORY keywords are also
frequently added to further document the data file.
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 file, 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:
\begin{itemize}
\item
BITPIX -- defines the datatype of the array: 8, 16, 32, 64, -32, -64 for
unsigned 8--bit byte, 16--bit signed integer, 32--bit signed integer,
64--bit signed integer,
32--bit IEEE floating point, and 64--bit IEEE double precision floating
point, respectively.
\item
NAXIS -- the number of dimensions in the array, usually 0, 1, 2, 3, or 4.
\item
NAXISn -- (n ranges from 1 to NAXIS) defines the size of each dimension.
\end{itemize}
FITS tables start with the keyword XTENSION = `TABLE' (for ASCII
tables) or XTENSION = `BINTABLE' (for binary tables) and have the
following main keywords:
\begin{itemize}
\item
TFIELDS -- number of fields or columns in the table
\item
NAXIS2 -- number of rows in the table
\item
TTYPEn -- for each column (n ranges from 1 to TFIELDS) gives the
name of the column
\item
TFORMn -- the datatype of the column
\item
TUNITn -- the physical units of the column (optional)
\end{itemize}
Users should refer to the FITS Support Office at {\tt http://fits.gsfc.nasa.gov}
for further information about the FITS format and related software
packages.
*V. FITSIO Conventions and Guidelines
**A. CFITSIO Size Limitations
CFITSIO places few restrictions on the size of FITS files that it
reads or writes. There are a few limits, however, which may affect
some extreme cases:
1. The maximum number of FITS files that may be simultaneously opened by
CFITSIO is set by NMAXFILES, as defined in fitsio2.h. The current default
value is 1000, but this may be increased if necessary. Note that CFITSIO
allocates NIOBUF * 2880 bytes of I/O buffer space for each file that is
opened. The default value of NIOBUF is 40 (defined in fitsio.h), so this
amounts to more than 115K of memory for each opened file (or 115 MB for
1000 opened files). Note that the underlying operating system, may have a
lower limit on the number of files that can be opened simultaneously.
2. By default, CFITSIO can handle FITS files up to 2.1 GB in size (2**31
bytes). This file size limit is often imposed by 32-bit operating
systems. More recently, as 64-bit operating systems become more common, an
industry-wide standard (at least on Unix systems) has been developed to
support larger sized files (see http://ftp.sas.com/standards/large.file/).
Starting with version 2.1 of CFITSIO, larger FITS files up to 6 terabytes
in size may be read and written on supported platforms. In order
to support these larger files, CFITSIO must be compiled with the
'-D\_LARGEFILE\_SOURCE' and `-D\_FILE\_OFFSET\_BITS=64' compiler flags.
Some platforms may also require the `-D\_LARGE\_FILES' compiler flag.
This causes the compiler to allocate 8-bytes instead of
4-bytes for the `off\_t' datatype which is used to store file offset
positions. It appears that in most cases it is not necessary to
also include these compiler flags when compiling programs that link to
the CFITSIO library.
If CFITSIO is compiled with the -D\_LARGEFILE\_SOURCE
and -D\_FILE\_OFFSET\_BITS=64 flags on a
platform that supports large files, then it can read and write FITS
files that contain up to 2**31 2880-byte FITS records, or approximately
6 terabytes in size. It is still required that the value of the NAXISn
and PCOUNT keywords in each extension be within the range of a signed
4-byte integer (max value = 2,147,483,648). Thus, each dimension of an
image (given by the NAXISn keywords), the total width of a table
(NAXIS1 keyword), the number of rows in a table (NAXIS2 keyword), and
the total size of the variable-length array heap in binary tables
(PCOUNT keyword) must be less than this limit.
Currently, support for large files within CFITSIO has been tested
on the Linux, Solaris, and IBM AIX operating systems.
**B. Multiple Access to the Same FITS File
CFITSIO supports simultaneous read and write access to multiple HDUs in
the same FITS file. Thus, one can open the same FITS file twice within
a single program and move to 2 different HDUs in the file, and then
read and write data or keywords to the 2 extensions just as if one were
accessing 2 completely separate FITS files. Since in general it is
not possible to physically open the same file twice and then expect to
be able to simultaneously (or in alternating succession) write to 2
different locations in the file, CFITSIO recognizes when the file to be
opened (in the call to fits\_open\_file) has already been opened and
instead of actually opening the file again, just logically links the
new file to the old file. (This only applies if the file is opened
more than once within the same program, and does not prevent the same
file from being simultaneously opened by more than one program). Then
before CFITSIO reads or writes to either (logical) file, it makes sure
that any modifications made to the other file have been completely
flushed from the internal buffers to the file. Thus, in principle, one
could open a file twice, in one case pointing to the first extension
and in the other pointing to the 2nd extension and then write data to
both extensions, in any order, without danger of corrupting the file,
There may be some efficiency penalties in doing this however, since
CFITSIO has to flush all the internal buffers related to one file
before switching to the other, so it would still be prudent to
minimize the number of times one switches back and forth between doing
I/O to different HDUs in the same file.
**C. Current Header Data Unit (CHDU)
In general, a FITS file can contain multiple Header Data Units, also
called extensions. CFITSIO only operates within one HDU at any given
time, and the currently selected HDU is called the Current Header Data
Unit (CHDU). When a FITS file is first created or opened the CHDU is
automatically defined to be the first HDU (i.e., the primary array).
CFITSIO routines are provided to move to and open any other existing
HDU within the FITS file or to append or insert a new HDU in the FITS
file which then becomes the CHDU.
**D. Subroutine Names
All FITSIO subroutine names begin with the letters 'ft' to distinguish
them from other subroutines and are 5 or 6 characters long. Users should
not name their own subroutines beginning with 'ft' to avoid conflicts.
(The SPP interface routines all begin with 'fs'). Subroutines which read
or get information from the FITS file have names beginning with
'ftg...'. Subroutines which write or put information into the FITS file
have names beginning with 'ftp...'.
**E. Subroutine Families and Datatypes
Many of the subroutines come in families which differ only in the
datatype of the associated parameter(s) . The datatype of these
subroutines is indicated by the last letter of the subroutine name
(e.g., 'j' in 'ftpkyj') as follows:
-
x - bit
b - character*1 (unsigned byte)
i - short integer (I*2)
j - integer (I*4, 32-bit integer)
k - long long integer (I*8, 64-bit integer)
e - real exponential floating point (R*4)
f - real fixed-format floating point (R*4)
d - double precision real floating-point (R*8)
g - double precision fixed-format floating point (R*8)
c - complex reals (pairs of R*4 values)
m - double precision complex (pairs of R*8 values)
l - logical (L*4)
s - character string
-
When dealing with the FITS byte datatype, it is important to remember
that the raw values (before any scaling by the BSCALE and BZERO, or
TSCALn and TZEROn keyword values) in byte arrays (BITPIX = 8) or byte
columns (TFORMn = 'B') are interpreted as unsigned bytes with values
ranging from 0 to 255. Some Fortran compilers support a non-standard
byte datatype such as INTEGER*1, LOGICAL*1, or BYTE, which can sometimes
be used instead of CHARACTER*1 variables. Many machines permit passing a
numeric datatype (such as INTEGER*1) to the FITSIO subroutines which are
expecting a CHARACTER*1 datatype, but this technically violates the
Fortran-77 standard and is not supported on all machines (e.g., on a VAX/VMS
machine one must use the VAX-specific \%DESCR function).
One feature of the CFITSIO routines is that they can operate on a `X'
(bit) column in a binary table as though it were a `B' (byte) column.
For example a `11X' datatype column can be interpreted the same as a
`2B' column (i.e., 2 unsigned 8-bit bytes). In some instances, it can
be more efficient to read and write whole bytes at a time, rather than
reading or writing each individual bit.
The double precision complex datatype is not a standard Fortran-77
datatype. If a particular Fortran compiler does not directly support
this datatype, then one may instead pass an array of pairs of double
precision values to these subroutines. The first value in each pair
is the real part, and the second is the imaginary part.
**F. Implicit Data Type Conversion
The FITSIO routines that read and write numerical data can perform
implicit data type conversion. This means that the data type of the
variable or array in the program does not need to be the same as the
data type of the value in the FITS file. Data type conversion is
supported for numerical and string data types (if the string contains a
valid number enclosed in quotes) when reading a FITS header keyword
value and for numeric values when reading or writing values in the
primary array or a table column. CFITSIO returns status =
NUM\_OVERFLOW if the converted data value exceeds the range of the
output data type. Implicit data type conversion is not supported
within binary tables for string, logical, complex, or double complex
data types.
In addition, any table column may be read as if it contained string values.
In the case of numeric columns the returned string will be formatted
using the TDISPn display format if it exists.
**G. Data Scaling
When reading numerical data values in the primary array or a
table column, the values will be scaled automatically by the BSCALE and
BZERO (or TSCALn and TZEROn) header keyword values if they are
present in the header. The scaled data that is returned to the reading
program will have
-
output value = (FITS value) * BSCALE + BZERO
-
(a corresponding formula using TSCALn and TZEROn is used when reading
from table columns). In the case of integer output values the floating
point scaled value is truncated to an integer (not rounded to the
nearest integer). The ftpscl and fttscl subroutines may be used to
override the scaling parameters defined in the header (e.g., to turn
off the scaling so that the program can read the raw unscaled values
from the FITS file).
When writing numerical data to the primary array or to a table
column the data values will generally be automatically inversely scaled
by the value of the BSCALE and BZERO (or TSCALn and TZEROn) header
keyword values if they they exist in the header. These keywords must
have been written to the header before any data is written for them to
have any effect. Otherwise, one may use the ftpscl and fttscl
subroutines to define or override the scaling keywords in the header
(e.g., to turn off the scaling so that the program can write the raw
unscaled values into the FITS file). If scaling is performed, the
inverse scaled output value that is written into the FITS file will
have
-
FITS value = ((input value) - BZERO) / BSCALE
-
(a corresponding formula using TSCALn and TZEROn is used when
writing to table columns). Rounding to the nearest integer, rather
than truncation, is performed when writing integer datatypes to the
FITS file.
**H. Error Status Values and the Error Message Stack
The last parameter in nearly every FITSIO subroutine is the error
status value which is both an input and an output parameter. A
returned positive value for this parameter indicates an error was
detected. A listing of all the FITSIO status code values is given at
the end of this document.
The FITSIO library uses an `inherited status' convention for the status
parameter which means that if a subroutine is called with a positive
input value of the status parameter, then the subroutine will exit
immediately without changing the value of the status parameter. Thus,
if one passes the status value returned from each FITSIO routine as
input to the next FITSIO subroutine, then whenever an error is detected
all further FITSIO processing will cease. This convention can simplify
the error checking in application programs because it is not necessary
to check the value of the status parameter after every single FITSIO
subroutine call. If a program contains a sequence of several FITSIO
calls, one can just check the status value after the last call. Since
the returned status values are generally distinctive, it should be
possible to determine which subroutine originally returned the error
status.
FITSIO also maintains an internal stack of error messages (80-character
maximum length) which in many cases provide a more detailed explanation
of the cause of the error than is provided by the error status number
alone. It is recommended that the error message stack be printed out
whenever a program detects a FITSIO error. To do this, call the FTGMSG
routine repeatedly to get the successive messages on the stack. When the
stack is empty FTGMSG will return a blank string. Note that this is a
`First In -- First Out' stack, so the oldest error message is returned
first by ftgmsg.
**I. Variable-Length Array Facility in Binary Tables
FITSIO provides easy-to-use support for reading and writing data in
variable length fields of a binary table. The variable length columns
have TFORMn keyword values of the form `1Pt(len)' or `1Qt(len)' where `t' is the
datatype code (e.g., I, J, E, D, etc.) and `len' is an integer
specifying the maximum length of the vector in the table. If the value
of `len' is not specified when the table is created (e.g., if the TFORM
keyword value is simply specified as '1PE' instead of '1PE(400) ), then
FITSIO will automatically scan the table when it is closed to
determine the maximum length of the vector and will append this value
to the TFORMn value.
The same routines which read and write data in an ordinary fixed length
binary table extension are also used for variable length fields,
however, the subroutine parameters take on a slightly different
interpretation as described below.
All the data in a variable length field is written into an area called
the `heap' which follows the main fixed-length FITS binary table. The
size of the heap, in bytes, is specified with the PCOUNT keyword in the
FITS header. When creating a new binary table, the initial value of
PCOUNT should usually be set to zero. FITSIO will recompute the size
of the heap as the data is written and will automatically update the
PCOUNT keyword value when the table is closed. When writing variable
length data to a table, CFITSIO will automatically extend the size
of the heap area if necessary, so that any following HDUs do not
get overwritten.
By default the heap data area starts immediately after the last row of
the fixed-length table. This default starting location may be
overridden by the THEAP keyword, but this is not recommended.
If additional rows of data are added to the table, CFITSIO will
automatically shift the the heap down to make room for the new
rows, but it is obviously be more efficient to initially
create the table with the necessary number of blank rows, so that
the heap does not needed to be constantly moved.
When writing to a variable length field, the entire array of values for
a given row of the table must be written with a single call to FTPCLx.
The total length of the array is calculated from (NELEM+FELEM-1). One
cannot append more elements to an existing field at a later time; any
attempt to do so will simply overwrite all the data which was previously
written. Note also that the new data will be written to a new area of
the heap and the heap space used by the previous write cannot be
reclaimed. For this reason it is advised that each row of a variable
length field only be written once. An exception to this general rule
occurs when setting elements of an array as undefined. One must first
write a dummy value into the array with FTPCLx, and then call FTPCLU to
flag the desired elements as undefined. (Do not use the FTPCNx family
of routines with variable length fields). Note that the rows of a table,
whether fixed or variable length, do not have to be written
consecutively and may be written in any order.
When writing to a variable length ASCII character field (e.g., TFORM =
'1PA') only a single character string written. FTPCLS writes the whole
length of the input string (minus any trailing blank characters), thus
the NELEM and FELEM parameters are ignored. If the input string is
completely blank then FITSIO will write one blank character to the FITS
file. Similarly, FTGCVS and FTGCFS read the entire string (truncated
to the width of the character string argument in the subroutine call)
and also ignore the NELEM and FELEM parameters.
The FTPDES subroutine is useful in situations where multiple rows of a
variable length column have the identical array of values. One can
simply write the array once for the first row, and then use FTPDES to
write the same descriptor values into the other rows (use the FTGDES
routine to read the first descriptor value); all the rows will then
point to the same storage location thus saving disk space.
When reading from a variable length array field one can only read as
many elements as actually exist in that row of the table; reading does
not automatically continue with the next row of the table as occurs
when reading an ordinary fixed length table field. Attempts to read
more than this will cause an error status to be returned. One can
determine the number of elements in each row of a variable column with
the FTGDES subroutine.
**I. Support for IEEE Special Values
The ANSI/IEEE-754 floating-point number standard defines certain
special values that are used to represent such quantities as
Not-a-Number (NaN), denormalized, underflow, overflow, and infinity.
(See the Appendix in the FITS standard or the FITS User's
Guide for a list of these values). The FITSIO subroutines that read
floating point data in FITS files recognize these IEEE special values
and by default interpret the overflow and infinity values as being
equivalent to a NaN, and convert the underflow and denormalized values
into zeros. In some cases programmers may want access to the raw IEEE
values, without any modification by FITSIO. This can be done by
calling the FTGPVx or FTGCVx routines while specifying 0.0 as the value
of the NULLVAL parameter. This will force FITSIO to simply pass the
IEEE values through to the application program, without any
modification. This does not work for double precision values on
VAX/VMS machines, however, where there is no easy way to bypass the
default interpretation of the IEEE special values. This is also not
supported when reading floating-point images that have been compressed
with the FITS tiled image compression convention that is discussed in
section 5.6; the pixels values in tile compressed images are
represented by scaled integers, and a reserved integer value
(not a NaN) is used to represent undefined pixels.
**J. When the Final Size of the FITS HDU is Unknown
It is not required to know the total size of a FITS data array or table
before beginning to write the data to the FITS file. In the case of
the primary array or an image extension, one should initially create
the array with the size of the highest dimension (largest NAXISn
keyword) set to a dummy value, such as 1. Then after all the data have
been written and the true dimensions are known, then the NAXISn value
should be updated using the fits\_ update\_key routine before moving to
another extension or closing the FITS file.
When writing to FITS tables, CFITSIO automatically keeps track of the
highest row number that is written to, and will increase the size of
the table if necessary. CFITSIO will also automatically insert space
in the FITS file if necessary, to ensure that the data 'heap', if it
exists, and/or any additional HDUs that follow the table do not get
overwritten as new rows are written to the table.
As a general rule it is best to specify the initial number of rows = 0
when the table is created, then let CFITSIO keep track of the number of
rows that are actually written. The application program should not
manually update the number of rows in the table (as given by the NAXIS2
keyword) since CFITSIO does this automatically. If a table is
initially created with more than zero rows, then this will usually be
considered as the minimum size of the table, even if fewer rows are
actually written to the table. Thus, if a table is initially created
with NAXIS2 = 20, and CFITSIO only writes 10 rows of data before