« back to all changes in this revision
Viewing changes to fitsio.doc
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Gopal Narayanan
- Date: 2002-02-26 11:27:29 UTC
- Revision ID: james.westby@ubuntu.com-20020226112729-3q2o993rhh81ipp4
Tags: upstream-2.401
Import upstream version 2.401
- files added:
added
removed
fitsio.doc
1
FITSIO - An Interface to FITS Format Files for Fortran Programmers
2
3
William D Pence, HEASARC, NASA/GSFC
4
Version 2.2
5
6
7
[Note: This file contains various formatting command symbols in the first
8
column which are used when generating the LATeX version of this document.]
9
10
*I. Introduction
11
12
This document describes the Fortran-callable subroutine interface that
13
is provided as part of the CFITSIO library (which is written in ANSI
14
C). This is a companion document to the CFITSIO User's Guide which
15
should be consulted for further information about the underlying
16
CFITSIO library. In the remainder of this document, the terms FITSIO
17
and CFITSIO are interchangable and refer to the same library.
18
19
FITSIO/CFITSIO is a machine-independent library of routines for reading
20
and writing data files in the FITS (Flexible Image Transport System)
21
data format. It can also read IRAF format image files and raw binary
22
data arrays by converting them on the fly into a virtual FITS format
23
file. This library was written to provide a powerful yet simple
24
interface for accessing FITS files which will run on most commonly used
25
computers and workstations. FITSIO supports all the features described
26
in the official NOST definition of the FITS format and can read and
27
write all the currently defined types of extensions, including ASCII
28
tables (TABLE), Binary tables (BINTABLE) and IMAGE extensions. The
29
FITSIO subroutines insulate the programmer from having to deal with the
30
complicated formatting details in the FITS file, however, it is assumed
31
that users have a general knowledge about the structure and usage of
32
FITS files.
33
34
The CFITSIO package was initially developed by the HEASARC (High Energy
35
Astrophysics Science Archive Research Center) at the NASA Goddard Space
36
Flight Center to convert various existing and newly acquired
37
astronomical data sets into FITS format and to further analyze data
38
already in FITS format. New features continue to be added to CFITSIO
39
in large part due to contributions of ideas or actual code from users
40
of the package. The Integral Science Data Center in Switzerland, and
41
the XMM/ESTEC project in The Netherlands made especially significant
42
contributions that resulted in many of the new features that appeared
43
in v2.0 of CFITSIO.
44
45
The latest version of the CFITSIO source code, documentation, and
46
example programs are available on the World-Wide Web or via anonymous
47
ftp from:
48
-
49
http://heasarc.gsfc.nasa.gov/fitsio
50
ftp://legacy.gsfc.nasa.gov/software/fitsio/c
51
-
52
\newpage
53
Any questions, bug reports, or suggested enhancements related to the CFITSIO
54
package should be sent to the primary author:
55
-
56
Dr. William Pence Telephone: (301) 286-4599
57
HEASARC, Code 662 E-mail: pence@tetra.gsfc.nasa.gov
58
NASA/Goddard Space Flight Center
59
Greenbelt, MD 20771, USA
60
-
61
This User's Guide assumes that readers already have a general
62
understanding of the definition and structure of FITS format files.
63
Further information about FITS formats is available in the `FITS User's
64
Guide' and the `NOST FITS Standard', which are available from the NASA
65
Science Office of Standards and Technology at the address given below.
66
Both of these documents are available electronically from their Web
67
site and via anonymous ftp at nssdc.gsfc.nasa.gov in the /pub/fits
68
directory. Any questions about FITS formats should be directed to the
69
NOST, at:
70
-
71
NASA, Science Office of Standards and Technology
72
Code 633.2,
73
Goddard Space Flight Center
74
Greenbelt MD 20771, USA
75
WWW: http://fits.gsfc.nasa.gov/
76
E-mail: fits@fits.gsfc.nasa.gov
77
(301) 286-2899
78
-
79
CFITSIO users may also be interested in the FTOOLS package of programs
80
that can be used to manipulate and analyze FITS format files.
81
Information about FTOOLS can be obtained on the Web or via anonymous
82
ftp at:
83
-
84
http://heasarc.gsfc.nasa.gov/ftools
85
ftp://legacy.gsfc.nasa.gov/software/ftools/release
86
-
87
88
*II. Creating FITSIO/CFITSIO
89
90
**A. Building the Library
91
92
To use the FITSIO subroutines one must first build the CFITSIO library,
93
which requires a C compiler. gcc is ideal, or most other ANSI-C
94
compilers will also work. The CFITSIO code is contained in about 40 C
95
source files (*.c) and header files (*.h). On VAX/VMS systems 2
96
assembly-code files (vmsieeed.mar and vmsieeer.mar) are also needed.
97
98
The Fortran interface subroutines to the C CFITSIO routines are located
99
in the f77\_wrap1.c and f77\_wrap2.c files. These are relatively simple
100
'wrappers' that translate the arguments in the Fortran subroutine into
101
the appropriate format for the corresponding C routine. This
102
translation is performed transparently to the user by a set of C macros
103
located in the cfortran.h file. Unfortunately cfortran.h does not
104
support every combination of C and Fortran compilers so the Fortran
105
interface is not supported on all platforms. This is especially true
106
for PC and Mac users (see further notes below).
107
108
The CFITSIO library is built on Unix systems by typing:
109
-
110
> ./configure
111
> make
112
or
113
> ./configure
114
> make shared
115
-
116
at the operating system prompt. Type ./configure and not simply
117
`configure' to ensure that the configure script in the current
118
directory and not some other system-wide configure script. The
119
configure command customizes the Makefile for the particular system,
120
then the `make' command compiles the source files and builds the
121
library. By default this also builds the set of Fortran-callable
122
wrapper routines whose calling sequences are described later in this
123
document.
124
125
The 'make shared' option builds a shared or dynamic version of the
126
CFITSIO library. When using the shared library the executable code is
127
not copied into your program at link time and instead the program
128
locates the necessary library code at run time, normally through
129
LD\_LIBRARY\_PATH or some other method. The advantages of using a shared
130
library are:
131
-
132
1. Less disk space if you build more than 1 program
133
2. Less memory if more than one copy of a program using the shared
134
library is running at the same time since the system is smart
135
enough to share copies of the shared library at run time.
136
3. Possibly easier maintenance since a new version of the shared
137
library can be installed without relinking all the software
138
that uses it (as long as the subroutine names and calling
139
sequences remain unchanged).
140
4. No run-time penalty.
141
-
142
The disadvantages are:
143
-
144
1. More hassle at runtime. You have to either build the programs
145
specially or have LD_LIBRARY_PATH set right.
146
2. There may be a slight start up penalty, depending on where you are
147
reading the shared library and the program from and if your CPU is
148
either really slow or really heavily loaded.
149
-
150
151
The CFITSIO library file (libcfitsio.a or libcfitsio.so), and 2 include
152
files, fitsio.h and longnam.h, should then be copied to the appropriate
153
directory(s) for use when compiling application programs.
154
Alternatively, one could set 2 environment variables, FTOOLS\_LIB and
155
FTOOLS\_INCLUDE, to specify the paths to the installation directories,
156
(e.g., `setenv FTOOLS\_INCLUDE /usr/local/include') and then run `make
157
install' to build and install the CFITSIO library.
158
159
On HP/UX systems, the environment variable CFLAGS should be set
160
to -Ae before running configure to enable "extended ANSI" features.
161
162
It may not be possible to staticly link programs that use CFITSIO on
163
some platforms (namely, on Solaris 2.6) due to the network drivers
164
(which provide FTP and HTTP access to FITS files). It is possible to
165
make both a dynamic and a static version of the CFITSIO library, but
166
network file access will not be possible using the static version.
167
168
On VAX/VMS and ALPHA/VMS systems the make\_gfloat.com command file may
169
be executed to build the cfitsio.olb object library using the default
170
G-floating point option for double variables. The make\_dfloat.com and
171
make\_ieee.com files may be used instead to build the library with the
172
other floating point options. Note that the getcwd function that is
173
used in the group.c module may require that programs using CFITSIO be
174
linked with the ALPHA\$LIBRARY:VAXCRTL.OLB library. See the example
175
link line in the next section of this document.
176
177
On Windows IBM-PC type platforms the situation is more complicated
178
because of the wide variety of Fortran compilers that are available and
179
because of the inherent complexities of calling the CFITSIO C routines
180
from Fortran. Two different versions of the CFITSIO dll library are
181
available, compiled with the Borland C++ compiler and the Microsoft
182
Visual C++ compiler, respectively, in the files
183
cfitsiodll\_2xxx\_borland.zip and cfitsiodll\_2xxx\_vcc.zip, where
184
'2xxx' represents the current release number. Both these dll libraries
185
contain a set of Fortran wrapper routines which may be compatible with
186
some, but probably not all, available Fortran compilers. To test if
187
they are compatible, compile the program testf77.f and try linking to
188
these dll libraries. If these libraries do not work with a particular
189
Fortran compiler, then there are 2 possible solutions. The first
190
solution would be to modify the file cfortran.h for that particular
191
combination of C and Fortran compilers, and then rebuild the CFITSIO
192
dll library. This will require, however, a great deal of expertise in
193
mixed language programming which the author of CFITSIO cannot provide.
194
The other solution is to use the older v5.03 Fortran-77 implementation
195
of FITSIO that is still available from the FITSIO web-site. This
196
version is no longer supported, but it does provide the basic functions
197
for reading and writing FITS files and should be compatible with most
198
Fortran compilers.
199
200
CFITSIO has currently been tested on the following platforms:
201
-
202
OPERATING SYSTEM COMPILER
203
Sun OS gcc and cc (3.0.1)
204
Sun Solaris gcc and cc
205
Silicon Graphics IRIX gcc and cc
206
Silicon Graphics IRIX64 MIPS
207
Dec Alpha OSF/1 gcc and cc
208
DECstation Ultrix gcc
209
Dec Alpha OpenVMS cc
210
DEC VAX/VMS gcc and cc
211
HP-UX gcc
212
IBM AIX gcc
213
Linux gcc
214
MkLinux DR3
215
Windows 95/98/NT Borland C++ V4.5
216
Windows 95/98/NT Microsoft/Compaq Visual C++ v5.0, v6.0
217
Windows 95/98/NT Cygwin gcc
218
OS/2 gcc + EMX
219
MacOS 7.1 or greater Metrowerks 10.+
220
-
221
CFITSIO will probably run on most other Unix platforms. Cray
222
supercomputers are currently not supported.
223
224
**B. Testing the Library
225
226
The CFITSIO library should be tested by building and running
227
the testprog.c program that is included with the release.
228
On Unix systems type:
229
-
230
% make testprog
231
% testprog > testprog.lis
232
% diff testprog.lis testprog.out
233
% cmp testprog.fit testprog.std
234
-
235
On VMS systems,
236
(assuming cc is the name of the C compiler command), type:
237
-
238
$ cc testprog.c
239
$ link testprog, cfitsio/lib, alpha$library:vaxcrtl/lib
240
$ run testprog
241
-
242
The testprog program should produce a FITS file called `testprog.fit'
243
that is identical to the `testprog.std' FITS file included with this
244
release. The diagnostic messages (which were piped to the file
245
testprog.lis in the Unix example) should be identical to the listing
246
contained in the file testprog.out. The 'diff' and 'cmp' commands
247
shown above should not report any differences in the files. (There
248
may be some minor formating differences, such as the presence or
249
absence of leading zeros, or 3 digit exponents in numbers,
250
which can be ignored).
251
252
The Fortran wrappers in CFITSIO may be tested with the testf77
253
program on Unix systems with:
254
-
255
% f77 -o testf77 testf77.f -L. -lcfitsio -lnsl -lsocket
256
or
257
% f77 -f -o testf77 testf77.f -L. -lcfitsio (under SUN O/S)
258
or
259
% f77 -o testf77 testf77.f -Wl,-L. -lcfitsio -lm -lnsl -lsocket (HP/UX)
260
261
% testf77 > testf77.lis
262
% diff testf77.lis testf77.out
263
% cmp testf77.fit testf77.std
264
-
265
On machines running SUN O/S, Fortran programs must be compiled with the
266
'-f' option to force double precision variables to be aligned on 8-byte
267
boundarys to make the fortran-declared variables compatible with C. A
268
similar compiler option may be required on other platforms. Failing to
269
use this option may cause the program to crash on FITSIO routines that
270
read or write double precision variables.
271
272
Also note that on some systems, the output listing of the testf77
273
program may differ slightly from the testf77.std template, if leading
274
zeros are not printed by default before the decimal point when using F
275
format.
276
277
A few other utility programs are included with CFITSIO:
278
-
279
speed - measures the maximum throughput (in MB per second)
280
for writing and reading FITS files with CFITSIO
281
282
listhead - lists all the header keywords in any FITS file
283
284
fitscopy - copies any FITS file (especially useful in conjunction
285
with the CFITSIO's extended input filename syntax)
286
287
cookbook - a sample program that peforms common read and
288
write operations on a FITS file.
289
290
iter_a, iter_b, iter_c - examples of the CFITSIO iterator routine
291
-
292
293
The first 4 of these utility programs can be compiled and linked by typing
294
-
295
% make program_name
296
-
297
298
**C. Linking Programs with FITSIO
299
300
When linking applications software with the FITSIO library, several system libraries usually need to be specified on the link command line. On
301
Unix systems, the most reliable way to determine what libraries are required
302
is to type 'make testprog' and see what libraries the configure script has
303
added. The typical libraries that may need to be added are -lm (the math
304
library) and -lnsl and -lsocket (needed only for FTP and HTTP file access).
305
These latter 2 libraries are not needed on VMS and Windows platforms,
306
because FTP file access is not currently supported on those platforms.
307
308
Note that when upgrading to a newer version of CFITSIO it is usually
309
necessay to recompile, as well as relink, the programs that use CFITSIO,
310
because the definitions in fitsio.h often change.
311
312
**D. Getting Started with FITSIO
313
314
In order to effectively use the FITSIO library as quickly as possible,
315
it is recommended that new users follow these steps:
316
317
1. Read the following `FITS Primer' chapter for a brief
318
overview of the structure of FITS files. This is especially important
319
for users who have not previously dealt with the FITS table and image
320
extensions.
321
322
2. Write a simple program to read or write a FITS file using the Basic
323
Interface routines.
324
325
3. Refer to the cookbook.f program that is included with this release
326
for examples of routines that perform various common FITS file
327
operations.
328
329
4. Read Chapters 4 and 5 to become familiar with the conventions and
330
advanced features of the FITSIO interface.
331
332
5. Scan through the more extensive set of routines that are provided
333
in the `Advanced Interface'. These routines perform more specialized
334
functions than are provided by the Basic Interface routines.
335
336
**E. Example Program
337
338
The following listing shows an example of how to use the FITSIO
339
routines in a Fortran program. Refer to the cookbook.f program that
340
is included with the FITSIO distribution for examples of other
341
FITS programs.
342
-
343
program writeimage
344
345
C Create a FITS primary array containing a 2-D image
346
347
integer status,unit,blocksize,bitpix,naxis,naxes(2)
348
integer i,j,group,fpixel,nelements,array(300,200)
349
character filename*80
350
logical simple,extend
351
352
status=0
353
C Name of the FITS file to be created:
354
filename='ATESTFILE.FITS'
355
356
C Get an unused Logical Unit Number to use to create the FITS file
357
call ftgiou(unit,status)
358
359
C create the new empty FITS file
360
blocksize=1
361
call ftinit(unit,filename,blocksize,status)
362
363
C initialize parameters about the FITS image (300 x 200 16-bit integers)
364
simple=.true.
365
bitpix=16
366
naxis=2
367
naxes(1)=300
368
naxes(2)=200
369
extend=.true.
370
371
C write the required header keywords
372
call ftphpr(unit,simple,bitpix,naxis,naxes,0,1,extend,status)
373
374
C initialize the values in the image with a linear ramp function
375
do j=1,naxes(2)
376
do i=1,naxes(1)
377
array(i,j)=i+j
378
end do
379
end do
380
381
C write the array to the FITS file
382
group=1
383
fpixel=1
384
nelements=naxes(1)*naxes(2)
385
call ftpprj(unit,group,fpixel,nelements,array,status)
386
387
C write another optional keyword to the header
388
call ftpkyj(unit,'EXPOSURE',1500,'Total Exposure Time',status)
389
390
C close the file and free the unit number
391
call ftclos(unit, status)
392
call ftfiou(unit, status)
393
end
394
-
395
396
**F. Legal Stuff
397
398
Copyright (Unpublished--all rights reserved under the copyright laws of
399
the United States), U.S. Government as represented by the Administrator
400
of the National Aeronautics and Space Administration. No copyright is
401
claimed in the United States under Title 17, U.S. Code.
402
403
Permission to freely use, copy, modify, and distribute this software
404
and its documentation without fee is hereby granted, provided that this
405
copyright notice and disclaimer of warranty appears in all copies.
406
407
DISCLAIMER:
408
409
THE SOFTWARE IS PROVIDED 'AS IS' WITHOUT ANY WARRANTY OF ANY KIND,
410
EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO,
411
ANY WARRANTY THAT THE SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY
412
IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
413
PURPOSE, AND FREEDOM FROM INFRINGEMENT, AND ANY WARRANTY THAT THE
414
DOCUMENTATION WILL CONFORM TO THE SOFTWARE, OR ANY WARRANTY THAT THE
415
SOFTWARE WILL BE ERROR FREE. IN NO EVENT SHALL NASA BE LIABLE FOR ANY
416
DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL OR
417
CONSEQUENTIAL DAMAGES, ARISING OUT OF, RESULTING FROM, OR IN ANY WAY
418
CONNECTED WITH THIS SOFTWARE, WHETHER OR NOT BASED UPON WARRANTY,
419
CONTRACT, TORT , OR OTHERWISE, WHETHER OR NOT INJURY WAS SUSTAINED BY
420
PERSONS OR PROPERTY OR OTHERWISE, AND WHETHER OR NOT LOSS WAS SUSTAINED
421
FROM, OR AROSE OUT OF THE RESULTS OF, OR USE OF, THE SOFTWARE OR
422
SERVICES PROVIDED HEREUNDER."
423
424
The file compress.c contains (slightly modified) source code that
425
originally came from gzip-1.2.4 which is freely distributed under the
426
GNU General Public Licence. A copy of the GNU licence is included
427
at the beginning of that file.
428
429
**G. Acknowledgements
430
431
The development of many of the powerful features in CFITSIO was made
432
possible through collaborations with many people or organizations from
433
around the world. The following, in particular, have made especially
434
significant contributions:
435
436
Programmers from the Integral Science Data Center, Switzerland (namely,
437
Jurek Borkowski, Bruce O'Neel, and Don Jennings), designed the concept
438
for the plug-in I/O drivers that was introduced with CFITSIO 2.0. The
439
use of `drivers' greatly simplified the low-level I/O, which in turn
440
made other new features in CFITSIO (e.g., support for compressed FITS
441
files and support for IRAF format image files) much easier to
442
implement. Jurek Borkowski wrote the Shared Memory driver, and Bruce
443
O'Neel wrote the drivers for accessing FITS files over the network
444
using the FTP, HTTP, and ROOT protocols.
445
446
The ISDC also provided the template parsing routines (written by Jurek
447
Borkowski) and the hierarchical grouping routines (written by Don
448
Jennings). The ISDC DAL (Data Access Layer) routines are layered on
449
top of CFITSIO and make extensive use of these features.
450
451
Uwe Lammers (XMM/ESA/ESTEC, The Netherlands) designed the
452
high-performance lexical parsing algorithm that is used to do
453
on-the-fly filtering of FITS tables. This algorithm essentially
454
pre-compiles the user-supplied selection expression into a form that
455
can be rapidly evaluated for each row. Peter Wilson (RSTX, NASA/GSFC)
456
then wrote the parsing routines used by CFITSIO based on Lammers'
457
design, combined with other techniques such as the CFITSIO iterator
458
routine to further enhance the data processing throughput. This effort
459
also benefitted from a much earlier lexical parsing routine that was
460
developed by Kent Blackburn (NASA/GSFC).
461
462
The CFITSIO iterator function is loosely based on similar ideas
463
developed for the XMM Data Access Layer.
464
465
Peter Wilson (RSTX, NASA/GSFC) wrote the complete set of
466
Fortran-callable wrappers for all the CFITSIO routines, which in turn
467
rely on the CFORTRAN macro developed by Burkhard Burow.
468
469
The syntax used by CFITSIO for filtering or binning input FITS files is
470
based on ideas developed for the AXAF Science Center Data Model by
471
Jonathan McDowell, Antonella Fruscione, Aneta Siemiginowska and Bill
472
Joye. See http://heasarc.gsfc.nasa.gov/docs/journal/axaf7.html for
473
further description of the AXAF Data Model.
474
475
The file decompression code were taken directly from the gzip (GNU zip)
476
program developed by Jean-loup Gailly and others.
477
478
Doug Mink, SAO, provided the routines for converting IRAF format
479
images into FITS format.
480
481
In addition, many other people have made valuable contributions to the
482
development of CFITSIO. These include (with apologies to others that may
483
have inadvertently been omitted):
484
485
Steve Allen, Carl Akerlof, Keith Arnaud, Morten Krabbe Barfoed, Kent
486
Blackburn, G Bodammer, Romke Bontekoe, Lucio Chiappetti, Keith Costorf,
487
Robin Corbet, John Davis, Richard Fink, Ning Gan, Emily Greene, Joe
488
Harrington, Cheng Ho, Phil Hodge, Jim Ingham, Yoshitaka Ishisaki, Diab
489
Jerius, Mark Levine, Todd Karakaskian, Edward King, Scott Koch, Claire
490
Larkin, Rob Managan, Eric Mandel, John Mattox, Carsten Meyer, Emi
491
Miyata, Stefan Mochnacki, Mike Noble, Oliver Oberdorf, Clive Page,
492
Arvind Parmar, Jeff Pedelty, Tim Pearson, Maren Purves, Scott Randall,
493
Chris Rogers, Arnold Rots, Barry Schlesinger, Robin Stebbins, Andrew
494
Szymkowiak, Allyn Tennant, Peter Teuben, James Theiler, Doug Tody,
495
Shiro Ueno, Steve Walton, Archie Warnock, Alan Watson, Dan Whipple, Wim
496
Wimmers, Peter Young, Jianjun Xu, and Nelson Zarate.
497
498
499
*III. A FITS Primer
500
501
This section gives a brief overview of the structure of FITS files.
502
Users should refer to the documentation available from the NOST, as
503
described in the introduction, for more detailed information on FITS
504
formats.
505
506
FITS was first developed in the late 1970's as a standard data
507
interchange format between various astronomical observatories. Since
508
then FITS has become the defacto standard data format supported by most
509
astronomical data analysis software packages.
510
511
A FITS file consists of one or more Header + Data Units (HDUs), where
512
the first HDU is called the `Primary HDU', or `Primary Array'. The
513
primary array contains an N-dimensional array of pixels, such as a 1-D
514
spectrum, a 2-D image, or a 3-D data cube. Five different primary
515
datatypes are supported: Unsigned 8-bit bytes, 16 and 32-bit signed
516
integers, and 32 and 64-bit floating point reals. FITS also has a
517
convention for storing 16 and 32-bit unsigned integers (see the later
518
section entitled `Unsigned Integers' for more details). The primary HDU
519
may also consist of only a header with a null array containing no
520
data pixels.
521
522
Any number of additional HDUs may follow the primary array; these
523
additional HDUs are called FITS `extensions'. There are currently 3
524
types of extensions defined by the FITS standard:
525
526
\begin{itemize}
527
\item
528
Image Extension - a N-dimensional array of pixels, like in a primary array
529
\item
530
ASCII Table Extension - rows and columns of data in ASCII character format
531
\item
532
Binary Table Extension - rows and columns of data in binary representation
533
\end{itemize}
534
535
In each case the HDU consists of an ASCII Header Unit followed by an optional
536
Data Unit. For historical reasons, each Header or Data unit must be an
537
exact multiple of 2880 8-bit bytes long. Any unused space is padded
538
with fill characters (ASCII blanks or zeros).
539
540
Each Header Unit consists of any number of 80-character keyword records
541
or `card images' which have thegeneral form:
542
-
543
KEYNAME = value / comment string
544
NULLKEY = / comment: This keyword has no value
545
-
546
The keyword names may be up to 8 characters long and can only contain
547
uppercase letters, the digits 0-9, the hyphen, and the underscore
548
character. The keyword name is (usually) followed by an equals sign and
549
a space character (= ) in columns 9 - 10 of the record, followed by the
550
value of the keyword which may be either an integer, a floating point
551
number, a character string (enclosed in single quotes), or a boolean
552
value (the letter T or F). A keyword may also have a null or undefined
553
value if there is no specified value string, as in the second example.
554
555
The last keyword in the header is always the `END' keyword which has no
556
value or comment fields. There are many rules governing the exact
557
format of a keyword record (see the NOST FITS Standard) so it is better
558
to rely on standard interface software like FITSIO to correctly
559
construct or to parse the keyword records rather than try to deal
560
directly with the raw FITS formats.
561
562
Each Header Unit begins with a series of required keywords which depend
563
on the type of HDU. These required keywords specify the size and
564
format of the following Data Unit. The header may contain other
565
optional keywords to describe other aspects of the data, such as the
566
units or scaling values. Other COMMENT or HISTORY keywords are also
567
frequently added to further document the data file.
568
569
The optional Data Unit immediately follows the last 2880-byte block in
570
the Header Unit. Some HDUs do not have a Data Unit and only consist of
571
the Header Unit.
572
573
If there is more than one HDU in the FITS file, then the Header Unit of
574
the next HDU immediately follows the last 2880-byte block of the
575
previous Data Unit (or Header Unit if there is no Data Unit).
576
577
The main required keywords in FITS primary arrays or image extensions are:
578
\begin{itemize}
579
\item
580
BITPIX -- defines the datatype of the array: 8, 16, 32, -32, -64 for
581
unsigned 8--bit byte, 16--bit signed integer, 32--bit signed integer,
582
32--bit IEEE floating point, and 64--bit IEEE double precision floating
583
point, respectively.
584
\item
585
NAXIS -- the number of dimensions in the array, usually 0, 1, 2, 3, or 4.
586
\item
587
NAXISn -- (n ranges from 1 to NAXIS) defines the size of each dimension.
588
\end{itemize}
589
590
FITS tables start with the keyword XTENSION = `TABLE' (for ASCII
591
tables) or XTENSION = `BINTABLE' (for binary tables) and have the
592
following main keywords:
593
\begin{itemize}
594
\item
595
TFIELDS -- number of fields or columns in the table
596
\item
597
NAXIS2 -- number of rows in the table
598
\item
599
TTYPEn -- for each column (n ranges from 1 to TFIELDS) gives the
600
name of the column
601
\item
602
TFORMn -- the datatype of the column
603
\item
604
TUNITn -- the physical units of the column (optional)
605
\end{itemize}
606
607
Users should refer to the NOST documentation for more details about the
608
required keywords and their allowed values.
609
610
611
*IV. Extended File Name Syntax
612
613
**A. Overview
614
615
CFITSIO supports an extended syntax when specifying the name of the
616
data file to be opened or created that includes the following
617
features:
618
619
\begin{itemize}
620
\item
621
CFITSIO can read IRAF format images which have header file names that
622
end with the '.imh' extension, as well as reading and writing FITS
623
files, This feature is implemented in CFITSIO by first converting the
624
IRAF image into a temporary FITS format file in memory, then opening
625
the FITS file. Any of the usual CFITSIO routines then may be used to
626
read the image header or data. Similarly, raw binary data arrays can
627
be read by converting them on the fly into virtual FITS images.
628
629
\item
630
FITS files on the internet can be read (and sometimes written) using the FTP,
631
HTTP, or ROOT protocols.
632
633
\item
634
FITS files can be piped between tasks on the stdin and stdout streams.
635
636
\item
637
FITS files can be read and written in shared memory. This can potentially
638
achieve much better data I/O performance compared to reading and
639
writing the same FITS files on magnetic disk.
640
641
\item
642
Compressed FITS files in gzip or Unix COMPRESS format can be directly read.
643
644
\item
645
Output FITS files can be written directly in compressed gzip format,
646
thus saving disk space.
647
648
\item
649
FITS table columns can be created, modified, or deleted 'on-the-fly' as
650
the table is opened by CFITSIO. This creates a virtual FITS file containing
651
the modifications that is then opened by the application program.
652
653
\item
654
Table rows may be selected, or filtered out, on the fly when the table
655
is opened by CFITSIO, based on an arbitrary user-specified expression.
656
Only rows for which the expression evaluates to 'TRUE' are retained
657
in the copy of the table that is opened by the application program.
658
659
\item
660
Histogram images may be created on the fly by binning the values in
661
table columns, resulting in a virtual N-dimensional FITS image. The
662
application program then only sees the FITS image (in the primary
663
array) instead of the original FITS table.
664
\end{itemize}
665
666
The latter 3 features in particular add very powerful data processing
667
capabilities directly into CFITSIO, and hence into every task that uses
668
CFITSIO to read or write FITS files. For example, these features
669
transform a very simple program that just copies an input FITS file to
670
a new output file (like the `fitscopy' program that is distributed with
671
CFITSIO) into a multipurpose FITS file processing tool. By appending
672
fairly simple qualifiers onto the name of the input FITS file, the user
673
can perform quite complex table editing operations (e.g., create new
674
columns, or filter out rows in a table) or create FITS images by
675
binning or histogramming the values in table columns. In addition,
676
these functions have been coded using new state-of-the art algorithms
677
that are, in some cases, 10 - 100 times faster than previous widely
678
used implementations.
679
680
Before describing the complete syntax for the extended FITS file names
681
in the next section, here are a few examples of FITS file names that
682
give a quick overview of the allowed syntax:
683
684
\begin{itemize}
685
\item
686
{\tt 'myfile.fits'}: the simplest case of a FITS file on disk in the current
687
directory.
688
689
\item
690
{\tt 'myfile.imh'}: opens an IRAF format image file and converts it on the
691
fly into a temporary FITS format image in memory which can then be read with
692
any other CFITSIO routine.
693
694
\item
695
{\tt rawfile.dat[i512,512]}: opens a raw binary data array (a 512 x 512
696
short integer array in this case) and converts it on the fly into a
697
temporary FITS format image in memory which can then be read with any
698
other CFITSIO routine.
699
700
\item
701
{\tt myfile.fits.gz}: if this is the name of a new output file, the '.gz'
702
suffix will cause it to be compressed in gzip format when it is written to
703
disk.
704
705
\item
706
{\tt 'myfile.fits.gz[events, 2]'}: opens and uncompresses the gzipped file
707
myfile.fits then moves to the extension which has the keywords EXTNAME
708
= 'EVENTS' and EXTVER = 2.
709
710
\item
711
{\tt '-'}: a dash (minus sign) signifies that the input file is to be read
712
from the stdin file stream, or that the output file is to be written to
713
the stdout stream.
714
715
\item
716
{\tt 'ftp://legacy.gsfc.nasa.gov/test/vela.fits'}: FITS files in any ftp
717
archive site on the internet may be directly opened with read-only
718
access.
719
720
\item
721
{\tt 'http://legacy.gsfc.nasa.gov/software/test.fits'}: any valid URL to a
722
FITS file on the Web may be opened with read-only access.
723
724
\item
725
{\tt 'root://legacy.gsfc.nasa.gov/test/vela.fits'}: similar to ftp access
726
except that it provides write as well as read access to the files
727
across the network. This uses the root protocol developed at CERN.
728
729
\item
730
{\tt 'shmem://h2[events]'}: opens the FITS file in a shared memory segment and
731
moves to the EVENTS extension.
732
733
\item
734
{\tt 'mem://'}: creates a scratch output file in core computer memory. The
735
resulting 'file' will disappear when the program exits, so this
736
is mainly useful for testing purposes when one does not want a
737
permanent copy of the output file.
738
739
\item
740
{\tt 'myfile.fits[3; Images(10)]'}: opens a copy of the image contained in the
741
10th row of the 'Images' column in the binary table in the 3th extension
742
of the FITS file. The application just sees this single image as the
743
primary array.
744
745
\item
746
{\tt 'myfile.fits[1:512:2, 1:512:2]'}: opens a section of the input image
747
ranging from the 1st to the 512th pixel in X and Y, and selects every
748
second pixel in both dimensions, resulting in a 256 x 256 pixel image
749
in this case.
750
751
\item
752
{\tt 'myfile.fits[EVENTS][col Rad = sqrt(X**2 + Y**2)]'}: creates and opens
753
a temporary file on the fly (in memory or on disk) that is identical to
754
myfile.fits except that it will contain a new column in the EVENTS
755
extension called 'Rad' whose value is computed using the indicated
756
expresson which is a function of the values in the X and Y columns.
757
758
\item
759
{\tt 'myfile.fits[EVENTS][PHA > 5]'}: creates and opens a temporary FITS
760
files that is identical to 'myfile.fits' except that the EVENTS table
761
will only contain the rows that have values of the PHA column greater
762
than 5. In general, any arbitrary boolean expression using a C or
763
Fortran-like syntax, which may combine AND and OR operators,
764
may be used to select rows from a table.
765
766
\item
767
{\tt 'myfile.fits[EVENTS][bin (X,Y)=1,2048,4]'}: creates a temporary FITS
768
primary array image which is computed on the fly by binning (i.e,
769
computing the 2-dimensional histogram) of the values in the X and Y
770
columns of the EVENTS extension. In this case the X and Y coordinates
771
range from 1 to 2048 and the image pixel size is 4 units in both
772
dimensions, so the resulting image is 512 x 512 pixels in size.
773
774
\item
775
The final example combines many of these feature into one complex
776
expression (it is broken into several lines for clarity):
777
-
778
'ftp://legacy.gsfc.nasa.gov/data/sample.fits.gz[EVENTS]
779
[col phacorr = pha * 1.1 - 0.3][phacorr >= 5.0 && phacorr <= 14.0]
780
[bin (X,Y)=32]'
781
-
782
In this case, CFITSIO (1) copies and uncompresses the FITS file from
783
the ftp site on the legacy machine, (2) moves to the 'EVENTS'
784
extension, (3) calculates a new column called 'phacorr', (4) selects
785
the rows in the table that have phacorr in the range 5 to 14, and
786
finally (5) bins the remaining rows on the X and Y column coordinates,
787
using a pixel size = 32 to create a 2D image. All this processing is
788
completely transparent to the application program, which simply sees
789
the final 2-D image in the primary array of the opened file.
790
\end{itemize}
791
792
The full extended CFITSIO FITS file name can contain several different
793
components depending on the context. These components are described in
794
the following sections:
795
-
796
When creating a new file:
797
filetype://BaseFilename(templateName)
798
799
When opening an existing primary array or image HDU:
800
filetype://BaseFilename(outName)[HDUlocation][ImageSection]
801
802
When opening an existing table HDU:
803
filetype://BaseFilename(outName)[HDUlocation][colFilter][rowFilter][binSpec]
804
-
805
The filetype, BaseFilename, outName, HDUlocation, and ImageSection
806
components, if present, must be given in that order, but the colFilter,
807
rowFilter, and binSpec specifiers may follow in any order. Regardless
808
of the order, however, the colFilter specifier, if present, will be
809
processed first by CFITSIO, followed by the rowFilter specifier, and
810
finally by the binSpec specifier.
811
812
**A. Filetype
813
814
The type of file determines the medium on which the file is located
815
(e.g., disk or network) and, hence, which internal device driver is used by
816
CFITSIO to read and/or write the file. Currently supported types are
817
-
818
file:// - file on local magnetic disk (default)
819
ftp:// - a readonly file accessed with the anonymous FTP protocol.
820
It also supports ftp://username:password@hostname/...
821
for accessing password-protected ftp sites.
822
http:// - a readonly file accessed with the HTTP protocol. It
823
does not support username:password like the ftp driver.
824
root:// - uses the CERN root protocol for writing as well as
825
reading files over the network.
826
shmem:// - opens or creates a file which persists in the computer's
827
shared memory.
828
mem:// - opens a temporary file in core memory. The file
829
disappears when the program exits so this is mainly
830
useful for test purposes when a permanent output file
831
is not desired.
832
-
833
If the filetype is not specified, then type file:// is assumed.
834
The double slashes '//' are optional and may be omitted in most cases.
835
836
***1. Notes about the root filetype
837
838
The original rootd server can be obtained from:
839
\verb-ftp://root.cern.ch/root/rootd.tar.gz-
840
but, for it to work correctly with CFITSIO one has to use a modified
841
version which supports a command to return the length of the file.
842
This modified version is available in rootd subdirectory
843
in the CFITSIO ftp area at
844
-
845
ftp://legacy.gsfc.nasa.gov/software/fitsio/c/root/rootd.tar.gz.
846
-
847
848
This small server is started either by inetd when a client requests a
849
connection to a rootd server or by hand (i.e. from the command line).
850
The rootd server works with the ROOT TNetFile class. It allows remote
851
access to ROOT database files in either read or write mode. By default
852
TNetFile assumes port 432 (which requires rootd to be started as root).
853
To run rootd via inetd add the following line to /etc/services:
854
-
855
rootd 432/tcp
856
-
857
and to /etc/inetd.conf, add the following line:
858
-
859
rootd stream tcp nowait root /user/rdm/root/bin/rootd rootd -i
860
-
861
Force inetd to reread its conf file with "kill -HUP <pid inetd>".
862
You can also start rootd by hand running directly under your private
863
account (no root system priviliges needed). For example to start
864
rootd listening on port 5151 just type: \verb+rootd -p 5151+
865
Notice: no \& is needed. Rootd will go into background by itself.
866
-
867
Rootd arguments:
868
-i says we were started by inetd
869
-p port# specifies a different port to listen on
870
-d level level of debug info written to syslog
871
0 = no debug (default)
872
1 = minimum
873
2 = medium
874
3 = maximum
875
-
876
Rootd can also be configured for anonymous usage (like anonymous ftp).
877
To setup rootd to accept anonymous logins do the following (while being
878
logged in as root):
879
-
880
- Add the following line to /etc/passwd:
881
882
rootd:*:71:72:Anonymous rootd:/var/spool/rootd:/bin/false
883
884
where you may modify the uid, gid (71, 72) and the home directory
885
to suite your system.
886
887
- Add the following line to /etc/group:
888
889
rootd:*:72:rootd
890
891
where the gid must match the gid in /etc/passwd.
892
893
- Create the directories:
894
895
mkdir /var/spool/rootd
896
mkdir /var/spool/rootd/tmp
897
chmod 777 /var/spool/rootd/tmp
898
899
Where /var/spool/rootd must match the rootd home directory as
900
specified in the rootd /etc/passwd entry.
901
902
- To make writeable directories for anonymous do, for example:
903
904
mkdir /var/spool/rootd/pub
905
chown rootd:rootd /var/spool/rootd/pub
906
-
907
That's all. Several additional remarks: you can login to an anonymous
908
server either with the names "anonymous" or "rootd". The password should
909
be of type user@host.do.main. Only the @ is enforced for the time
910
being. In anonymous mode the top of the file tree is set to the rootd
911
home directory, therefore only files below the home directory can be
912
accessed. Anonymous mode only works when the server is started via
913
inetd.
914
915
***2. Notes about the shmem filetype:
916
917
Shared memory files are currently supported on most Unix platforms,
918
where the shared memory segments are managed by the operating system
919
kernel and `live' independently of processes. They are not deleted (by
920
default) when the process which created them terminates, although they
921
will disappear if the system is rebooted. Applications can create
922
shared memory files in CFITSIO by calling:
923
-
924
fit_create_file(&fitsfileptr, "shmem://h2", &status);
925
-
926
where the root `file' names are currently restricted to be 'h0', 'h1',
927
'h2', 'h3', etc., up to a maximumn number defined by the the value of
928
SHARED\_MAXSEG (equal to 16 by default). This is a prototype
929
implementation of the shared memory interface and a more robust
930
interface, which will have fewer restrictions on the number of files
931
and on their names, may be developed in the future.
932
933
When opening an already existing FITS file in shared memory one calls
934
the usual CFITSIO routine:
935
-
936
fits_open_file(&fitsfileptr, "shmem://h7", mode, &status)
937
-
938
The file mode can be READWRITE or READONLY just as with disk files.
939
More than one process can operate on READONLY mode files at the same
940
time. CFITSIO supports proper filelocking (both in READONLY and
941
READWRITE modes), so calls to fits\_open\_file may be locked out until
942
another other process closes the file.
943
944
When an application is finished accessing a FITS file in a shared
945
memory segment, it may close it (and the file will remain in the
946
system) with fits\_close\_file, or delete it with fits\_delete\_file.
947
Physical deletion is postponed until the last process calls
948
ffclos/ffdelt. fits\_delete\_file tries to obtain a READWRITE lock on
949
the file to be deleted, thus it can be blocked if the object was not
950
opened in READWRITE mode.
951
952
A shared memory management utility program called `smem', is included
953
with the CFITSIO distribution. It can be built by typing `make smem';
954
then type `smem -h' to get a list of valid options. Executing smem
955
without any options causes it to list all the shared memory segments
956
currently residing in the system and managed by the shared memory
957
driver. To get a list of all the shared memory objects, run the system
958
utility program `ipcs [-a]'.
959
960
**B. Base Filename
961
962
The base filename is the name of the file optionally including the
963
director/subdirectory path, and in the case of `ftp', `http', and `root'
964
filetypes, the machine identifier. Examples:
965
-
966
myfile.fits
967
!data.fits
968
/data/myfile.fits
969
fits.gsfc.nasa.gov/ftp/sampledata/myfile.fits.gz
970
-
971
972
When creating a new output file on magnetic disk (of type file://) if
973
the base filename begins with an exclamation point (!) then any
974
existing file with that same basename will be deleted prior to creating
975
the new FITS file. Otherwise if the file to be created already exists,
976
then CFITSIO will return an error and will not overwrite the existing
977
file. Note that the exclamation point, '!', is a special UNIX character,
978
so if it is used on the command line rather than entered at a task
979
prompt, it must be preceded by a backslash to force the UNIX
980
shell to pass it verbatim to the application program.
981
982
If the output disk file name ends with the suffix '.gz', then CFITSIO
983
will compress the file using the gzip compression algorithm before
984
writing it to disk. This can reduce the amount of disk space used by
985
the file. Note that this feature requires that the uncompressed file
986
be constructed in memory before it is compressed and written to disk,
987
so it can fail if there is insufficient available memory.
988
989
An input FITS file may be compressed with the gzip or Unix compress
990
algorithms, in which case CFITSIO will uncompress the file on the fly
991
into a temporary file (in memory or on disk). Compressed files may
992
only be opened with read-only permission. When specifying the name of
993
a compressed FITS file it is not necessary to append the file suffix
994
(e.g., `.gz' or `.Z'). If CFITSIO cannot find the input file name
995
without the suffix, then it will automatically search for a compressed
996
file with the same root name. In the case of reading ftp and http type
997
files, CFITSIO generally looks for a compressed version of the file
998
first, before trying to open the uncompressed file. By default,
999
CFITSIO copies (and uncompressed if necessary) the ftp or http FITS
1000
file into memory on the local machine before opening it. This will
1001
fail if the local machine does not have enough memory to hold the whole
1002
FITS file, so in this case, the output filename specifier (see the next
1003
section) can be used to further control how CFITSIO reads ftp and http
1004
files.
1005
1006
If the input file is an IRAF image file (*.imh file) then CFITSIO will
1007
automatically convert it on the fly into a virtual FITS image before it
1008
is opened by the application program. IRAF images can only be opened
1009
with READONLY file access.
1010
1011
Similarly, if the input file is a raw binary data array, then CFITSIO
1012
will convert it on the fly into a virtual FITS image with the basic set
1013
of required header keywords before it is opened by the application
1014
program (with READONLY access). In this case the data type and
1015
dimensions of the image must be specified in square brackets following
1016
the filename (e.g. rawfile.dat[ib512,512]). The first character (case
1017
insensitive) defines the datatype of the array:
1018
-
1019
b 8-bit unsigned byte
1020
i 16-bit signed integer
1021
u 16-bit unsigned integer
1022
j 32-bit signed integer
1023
r or f 32-bit floating point
1024
d 64-bit floating point
1025
-
1026
An optional second character specifies the byte order of the array
1027
values: b or B indicates big endian (as in FITS files and the native
1028
format of SUN UNIX workstations and Mac PCs) and l or L indicates
1029
little endian (native format of DEC OSF workstations and IBM PCs). If
1030
this character is omitted then the array is assumed to have the native
1031
byte order of the local machine. These datatype characters are then
1032
followed by a series of one or more integer values separated by commas
1033
which define the size of each dimension of the raw array. Arrays with
1034
up to 5 dimensions are currently supported. Finally, a byte offset to
1035
the position of the first pixel in the data file may be specified by
1036
separating it with a ':' from the last dimension value. If omitted, it
1037
is assumed that the offset = 0. This parameter may be used to skip
1038
over any header information in the file that preceeds the binary data.
1039
Further examples:
1040
-
1041
raw.dat[b10000] 1-dimensional 10000 pixel byte array
1042
raw.dat[rb400,400,12] 3-dimensional floating point big-endian array
1043
img.fits[ib512,512:2880] reads the 512 x 512 short integer array in
1044
a FITS file, skipping over the 2880 byte header
1045
-
1046
1047
One special case of input file is where the filename = `-' (a dash or
1048
minus sign), which signifies that the input file is to be read from the
1049
stdin stream, or written to the stdout stream if a new output file is
1050
being created. In the case of reading from stdin, CFITSIO first copies
1051
the whole stream into a temporary FITS file (in memory or on disk), and
1052
subsequent reading of the FITS file occurs in this copy. When writing
1053
to stdout, CFITSIO first constructs the whole file in memory (since
1054
random access is required), then flushes it out to the stdout stream
1055
when the file is closed. This feature allows FITS files to be piped
1056
between tasks in memory rather than having to create temporary
1057
intermediate FITS files on disk. For example if task1 creates an
1058
output FITS file, and task2 reads an input FITS file, the FITS file may
1059
be piped between the 2 tasks by specifying
1060
-
1061
task1 - | task2 -
1062
-
1063
where the vertical bar is the Unix piping symbol. This assumes that the 2
1064
tasks read the name of the FITS file off of the command line.
1065
1066
**C. Output File Name when Opening an Existing File
1067
1068
An optional output filename may be specified in parentheses immediately
1069
following the base file name to be opened. This is mainly useful in
1070
those cases where CFITSIO creates a temporary copy of the input FITS
1071
file before it is opened and passed to the application program. This
1072
happens by default when opening a network FTP or HTTP-type file, when
1073
reading a compressed FITS file on a local disk, when reading from the
1074
stdin stream, or when a column filter, row filter, or binning specifier
1075
is included as part of the input file specification. By default this
1076
temporary file is created in memory. If there is not enough memory to
1077
create the file copy, then CFITSIO will exit with an error. In these
1078
cases one can force a permanent file to be created on disk, instead of
1079
a temporary file in memory, by supplying the name in parentheses
1080
immediately following the base file name. The output filename can
1081
include the '!' clobber flag.
1082
1083
Thus, if the input filename to CFITSIO is:
1084
\verb+file1.fits.gz(file2.fits)+
1085
then CFITSIO will uncompress `file1.fits.gz' into the local disk file
1086
`file2.fits' before opening it. CFITSIO does not automatically delete
1087
the output file, so it will still exist after the application program
1088
exits.
1089
1090
In some cases, several different temporary FITS files will be created
1091
in sequence, for instance, if one opens a remote file using FTP, then
1092
filters rows in a binary table extension, then create an image by
1093
binning a pair of columns. In this case, the remote file will be
1094
copied to a temporary local file, then a second temporary file will be
1095
created containing the filtered rows of the table, and finally a third
1096
temporary file containing the binned image will be created. In cases
1097
like this where multiple files are created, the outfile specifier will
1098
be interpreted the name of the final file as described below, in descending
1099
priority:
1100
1101
\begin{itemize}
1102
\item
1103
as the name of the final image file if an image within a single binary
1104
table cell is opened or if an image is created by binning a table column.
1105
\item
1106
as the name of the file containing the filtered table if a column filter
1107
and/or a row filter are specified.
1108
\item
1109
as the name of the local copy of the remote FTP or HTTP file.
1110
\item
1111
as the name of the uncompressed version of the FITS file, if a
1112
compressed FITS file on local disk has been opened.
1113
\item
1114
otherwise, the output filename is ignored.
1115
\end{itemize}
1116
1117
1118
The output file specifier is useful when reading FTP or HTTP-type
1119
FITS files since it can be used to create a local disk copy of the file
1120
that can be reused in the future. If the output file name = `*' then a
1121
local file with the same name as the network file will be created.
1122
Note that CFITSIO will behave differently depending on whether the
1123
remote file is compressed or not as shown by the following examples:
1124
\begin{itemize}
1125
\item
1126
`ftp://remote.machine/tmp/myfile.fits.gz(*)' - the remote compressed
1127
file is copied to the local compressed file `myfile.fits.gz', which
1128
is then uncompressed in local memory before being opened and passed
1129
to the application program.
1130
1131
\item
1132
`ftp://remote.machine/tmp/myfile.fits.gz(myfile.fits)' - the remote
1133
compressed file is copied and uncompressed into the local file
1134
`myfile.fits'. This example requires less local memory than the
1135
previous example since the file is uncompressed on disk instead of
1136
in memory.
1137
1138
\item
1139
`ftp://remote.machine/tmp/myfile.fits(myfile.fits.gz)' - this will
1140
usually produce an error since CFITSIO itself cannot compress files.
1141
\end{itemize}
1142
1143
The exact behavior of CFITSIO in the latter case depends on the type of
1144
ftp server running on the remote machine and how it is configured. In
1145
some cases, if the file `myfile.fits.gz' exists on the remote machine,
1146
then the server will copy it to the local machine. In other cases the
1147
ftp server will automatically create and transmit a compressed version
1148
of the file if only the uncompressed version exists. This can get
1149
rather confusing, so users should use a certain amount of caution when
1150
using the output file specifier with FTP or HTTP file types, to make
1151
sure they get the behavior that they expect.
1152
1153
**D. Template File Name when Creating a New File
1154
1155
When a new FITS file is created with a call to fits\_create\_file, the
1156
name of a template file may be supplied in parentheses immediately
1157
following the name of the new file to be created. This template is
1158
used to define the structure of one or more HDUs in the new file. The
1159
template file may be another FITS file, in which case the newly created
1160
file will have exactly the same keywords in each HDU as in the template
1161
FITS file, but all the data units will be filled with zeros. The
1162
template file may also be an ASCII text file, where each line (in
1163
general) describes one FITS keyword record. The format of the ASCII
1164
template file is described below.
1165
1166
**E. HDU Location Specification
1167
1168
The optional HDU location specifier defines which HDU (Header-Data
1169
Unit, also known as an `extension') within the FITS file to initially
1170
open. It must immediately follow the base file name (or the output
1171
file name if present). If it is not specified then the first HDU (the
1172
primary array) is opened. The HDU location specifier is required if
1173
the colFilter, rowFilter, or binSpec specifiers are present, because
1174
the primary array is not a valid HDU for these operations. The HDU may
1175
be specified either by absolute position number, starting with 0 for
1176
the primary array, or by reference to the HDU name, and optionally, the
1177
version number and the HDU type of the desired extension. The location
1178
of an image within a single cell of a binary table may also be
1179
specified, as described below.
1180
1181
The absolute position of the extension is specified either by enclosed
1182
the number in square brackets (e.g., `[1]' = the first extension
1183
following the primary array) or by preceded the number with a plus sign
1184
(`+1'). To specify the HDU by name, give the name of the desired HDU
1185
(the value of the EXTNAME or HDUNAME keyword) and optionally the
1186
extension version number (value of the EXTVER keyword) and the
1187
extension type (value of the XTENSION keyword: IMAGE, ASCII or TABLE,
1188
or BINTABLE), separated by commas and all enclosed in square brackets.
1189
If the value of EXTVER and XTENSION are not specified, then the first
1190
extension with the correct value of EXTNAME is opened. The extension
1191
name and type are not case sensitive, and the extension type may be
1192
abbreviated to a single letter (e.g., I = IMAGE extension or primary
1193
array, A or T = ASCII table extension, and B = binary table BINTABLE
1194
extension). If the HDU location specifier is equal to `[PRIMARY]' or
1195
`[P]', then the primary array (the first HDU) will be opened.
1196
1197
FITS images are most commonly stored in the primary array or an image
1198
extension, but images can also be stored as a vector in a single cell
1199
of a binary table (i.e. each row of the vector column contains a
1200
different image). Such an image can be opened with CFITSIO by
1201
specifying the desired column name and the row number after the binary
1202
table HDU specifier as shown in the following examples. The column name
1203
is separated from the HDU specifier by a semicolon and the row number
1204
is enclosed in parentheses. In this case CFITSIO copies the image from
1205
the table cell into a temporary primary array before it is opened. The
1206
application program then just sees the image in the primary array,
1207
without any extensions. The particular row to be opened may be
1208
specified either by giving an absolute integer row number (starting
1209
with 1 for the first row), or by specifying a boolean expression that
1210
evaluates to TRUE for the desired row. The first row that satisfies
1211
the expression will be used. The row selection expression has the same
1212
syntax as described in the Row Filter Specifier section, below.
1213
1214
Examples:
1215
-
1216
myfile.fits[3] - open the 3rd HDU following the primary array
1217
myfile.fits+3 - same as above, but using the FTOOLS-style notation
1218
myfile.fits[EVENTS] - open the extension that has EXTNAME = 'EVENTS'
1219
myfile.fits[EVENTS, 2] - same as above, but also requires EXTVER = 2
1220
myfile.fits[events,2,b] - same, but also requires XTENSION = 'BINTABLE'
1221
myfile.fits[3; images(17)] - opens the image in row 17 of the 'images'
1222
column in the 3rd extension of the file.
1223
myfile.fits[3; images(exposure > 100)] - as above, but opens the image
1224
in the first row that has an 'exposure' column value
1225
greater than 100.
1226
-
1227
1228
**F. Image Section
1229
1230
A virtual file containing a rectangular subsection of an image can be
1231
extracted and opened by specifying the range of pixels (start:end)
1232
along each axis to be extracted from the original image. One can also
1233
specify an optional pixel increment (start:end:step) for each axis of
1234
the input image. A pixel step = 1 will be assumed if it is not
1235
specified. If the start pixel is larger then the end pixel, then the
1236
image will be flipped (producing a mirror image) along that dimension.
1237
An asterisk, '*', may be used to specify the entire range of an axis,
1238
and '-*' will flip the entire axis. The input image can be in the
1239
primary array, in an image extension, or contained in a vector cell of
1240
a binary table. In the later 2 cases the extension name or number must
1241
be specified before the image section specifier.
1242
1243
Examples:
1244
-
1245
myfile.fits[1:512:2, 2:512:2] - open a 256x256 pixel image
1246
consisting of the odd numbered columns (1st axis) and
1247
the even numbered rows (2nd axis) of the image in the
1248
primary array of the file.
1249
1250
myfile.fits[*, 512:256] - open an image consisting of all the columns
1251
in the input image, but only rows 256 through 512.
1252
The image will be flipped along the 2nd axis since
1253
the starting pixel is greater than the ending pixel.
1254
1255
myfile.fits[*:2, 512:256:2] - same as above but keeping only
1256
every other row and column in the input image.
1257
1258
myfile.fits[-*, *] - copy the entire image, flipping it along
1259
the first axis.
1260
1261
myfile.fits[3][1:256,1:256] - opens a subsection of the image that
1262
is in the 3rd extension of the file.
1263
1264
myfile.fits[4; images(12)][1:10,1:10] - open an image consisting
1265
of the first 10 pixels in both dimensions. The original
1266
image resides in the 12th row of the 'images' vector
1267
column in the table in the 4th extension of the file.
1268
-
1269
1270
When CFITSIO opens an image section it first creates a temporary file
1271
containing the image section plus a copy of any other HDUs in the
1272
file. This temporary file is then opened by the application program,
1273
so it is not possible to write to or modify the input file when
1274
specifying an image section. Note that CFITSIO automatically updates
1275
the world coordinate system keywords in the header of the image
1276
section, if they exist, so that the coordinate associated with each
1277
pixel in the image section will be computed correctly.
1278
1279
**G. Column and Keyword Filtering Specification
1280
1281
The optional column/keyword filtering specifier is used to modify the
1282
column structure and/or the header keywords in the HDU that was
1283
selected with the previous HDU location specifier. This filtering
1284
specifier must be enclosed in square brackets and can be distinguished
1285
from a general row filter specifier (described below) by the fact that
1286
it begins with the string 'col ' and is not immediately followed by an
1287
equals sign. The original file is not changed by this filtering
1288
operation, and instead the modifications are made on a copy of the
1289
input FITS file (usually in memory), which also contains a copy of all
1290
the other HDUs in the file. This temporary file is passed to the
1291
application program and will persist only until the file is closed or
1292
until the program exits, unless the outfile specifier (see above) is
1293
also supplied.
1294
1295
The column/keyword filter can be used to perform the following
1296
operations. More than one operation may be specified by separating
1297
them with semi-colons.
1298
1299
\begin{itemize}
1300
1301
\item
1302
Copy only a specified list of columns columns to the filtered input file.
1303
The list of column name should be separated by semi-colons.
1304
1305
\item
1306
Delete a column or keyword by listing the name preceeded by a minus
1307
sign or an exclamation mark (!), e.g., '-TIME' will delete the TIME
1308
column if it exists, otherwise the TIME keyword. An error is returned
1309
if neither a column nor keyword with this name exists. Note that the
1310
exclamation point, '!', is a special UNIX character, so if it is used
1311
on the command line rather than entered at a task prompt, it must be
1312
preceded by a backslash to force the UNIX shell to ignore it.
1313
1314
\item
1315
Rename an existing column or keyword with the syntax 'NewName ==
1316
OldName'. An error is returned if neither a column nor keyword with
1317
this name exists.
1318
1319
\item
1320
Append a new column or keyword to the table. To create a column,
1321
give the new name, optionally followed by the datatype in parentheses,
1322
followed by a single equals sign and an expression to be used to
1323
compute the value (e.g., 'newcol(1J) = 0' will create a new 32-bit
1324
integer column called 'newcol' filled with zeros). The datatype is
1325
specified using the same syntax that is allowed for the value of the
1326
FITS TFORMn keyword (e.g., 'I', 'J', 'E', 'D', etc. for binary tables,
1327
and 'I8', F12.3', 'E20.12', etc. for ASCII tables). If the datatype is
1328
not specified then an appropriate datatype will be chosen depending on
1329
the form of the expression (may be a character string, logical, bit, long
1330
integer, or double column). An appropriate vector count (in the case
1331
of binary tables) will also be added if not explicitly specified.
1332
1333
When creating a new keyword, the keyword name must be preceeded by a
1334
pound sign '\#', and the expression must evaluate to a scalar
1335
(i.e., cannot have a column name in the expression). The comment
1336
string for the keyword may be specified in parentheses immediately
1337
following the keyword name (instead of supplying a datatype as in
1338
the case of creating a new column).
1339
1340
\item
1341
Recompute (overwrite) the values in an existing column or keyword by
1342
giving the name followed by an equals sign and an arithmetic
1343
expression.
1344
\end{itemize}
1345
1346
The expression that is used when appending or recomuting columns or
1347
keywords can be arbitrarily complex and may be a function of other
1348
header keyword values and other columns (in the same row). The full
1349
syntax and available functions for the expression are described below
1350
in the row filter specification section.
1351
1352
If the expression contains both a list of columns to be included and
1353
columns to be deleted, then all the columns in the original table
1354
except the explicitly deleted columns will appear in the filtered
1355
table.
1356
1357
For complex or commonly used operations, one can also place the
1358
operations into an external text file and import it into the column
1359
filter using the syntax '[col @filename.txt]'. The operations can
1360
extend over multiple lines of the file, but multiple operations must
1361
still be separated by semicolons. Any lines in the external text file
1362
that begin with 2 slash characters ('//') will be ignored and may be
1363
used to add comments into the file.
1364
1365
Examples:
1366
-
1367
[col Time;rate] - only the Time and rate columns will
1368
appear in the filtered input file.
1369
1370
[col -TIME; Good == STATUS] - deletes the TIME column and
1371
renames the status column to 'Good'
1372
1373
[col PI=PHA * 1.1 + 0.2] - creates new PI column from PHA values
1374
1375
[col rate = rate/exposure] - recomputes the rate column by dividing
1376
it by the EXPOSURE keyword value.
1377
-
1378
1379
**H. Row Filtering Specification
1380
1381
When entering the name of a FITS table that is to be opened by a
1382
program, an optional row filter may be specified to select a subset
1383
of the rows in the table. A temporary new FITS file is created on
1384
the fly which contains only those rows for which the row filter
1385
expression evaluates to true. (The primary array and any other
1386
extensions in the input file are also copied to the temporary
1387
file). The original FITS file is closed and the new virtual file
1388
is opened by the application program. The row filter expression is
1389
enclosed in square brackets following the file name and extension
1390
name (e.g., 'file.fits[events][GRADE==50]' selects only those rows
1391
where the GRADE column value equals 50). When dealing with tables
1392
where each row has an associated time and/or 2D spatial position,
1393
the row filter expression can also be used to select rows based on
1394
the times in a Good Time Intervals (GTI) extension, or on spatial
1395
position as given in a SAO-style region file.
1396
1397
***1. General Syntax
1398
1399
The row filtering expression can be an arbitrarily complex series
1400
of operations performed on constants, keyword values, and column
1401
data taken from the specified FITS TABLE extension. The expression
1402
must evaluate to a boolean value for each row of the table, where
1403
a value of FALSE means that the row will be excluded.
1404
1405
For complex or commonly used filters, one can place the expression
1406
into a text file and import it into the row filter using the syntax
1407
'[@filename.txt]'. The expression can be arbitrarily complex and
1408
extend over multiple lines of the file. Any lines in the external
1409
text file that begin with 2 slash characters ('//') will be ignored
1410
and may be used to add comments into the file.
1411
1412
Keyword and column data are referenced by name. Any string of
1413
characters not surrounded by quotes (ie, a constant string) or
1414
followed by an open parentheses (ie, a function name) will be
1415
initially interpreted as a column name and its contents for the
1416
current row inserted into the expression. If no such column exists,
1417
a keyword of that name will be searched for and its value used, if
1418
found. To force the name to be interpreted as a keyword (in case
1419
there is both a column and keyword with the same name), precede the
1420
keyword name with a single pound sign, '\#', as in '\#NAXIS2'. Due to
1421
the generalities of FITS column and keyword names, if the column or
1422
keyword name contains a space or a character which might appear as
1423
an arithmetic term then inclose the name in '\$' characters as in
1424
\$MAX PHA\$ or \#\$MAX-PHA\$. Names are case insensitive.
1425
1426
To access a table entry in a row other than the current one, follow
1427
the column's name with a row offset within curly braces. For
1428
example, 'PHA\{-3\}' will evaluate to the value of column PHA, 3 rows
1429
above the row currently being processed. One cannot specify an
1430
absolute row number, only a relative offset. Rows that fall outside
1431
the table will be treated as undefined, or NULLs.
1432
1433
Boolean operators can be used in the expression in either their
1434
Fortran or C forms. The following boolean operators are available:
1435
-
1436
"equal" .eq. .EQ. == "not equal" .ne. .NE. !=
1437
"less than" .lt. .LT. < "less than/equal" .le. .LE. <= =<
1438
"greater than" .gt. .GT. > "greater than/equal" .ge. .GE. >= =>
1439
"or" .or. .OR. || "and" .and. .AND. &&
1440
"negation" .not. .NOT. ! "approx. equal(1e-7)" ~
1441
-
1442
1443
Note that the exclamation
1444
point, '!', is a special UNIX character, so if it is used on the
1445
command line rather than entered at a task prompt, it must be preceded
1446
by a backslash to force the UNIX shell to ignore it.
1447
1448
The expression may also include arithmetic operators and functions.
1449
Trigonometric functions use radians, not degrees. The following
1450
arithmetic operators and functions can be used in the expression
1451
(function names are case insensitive):
1452
1453
-
1454
"addition" + "subtraction" -
1455
"multiplication" * "division" /
1456
"negation" - "exponentiation" ** ^
1457
"absolute value" abs(x) "cosine" cos(x)
1458
"sine" sin(x) "tangent" tan(x)
1459
"arc cosine" arccos(x) "arc sine" arcsin(x)
1460
"arc tangent" arctan(x) "arc tangent" arctan2(x,y)
1461
"exponential" exp(x) "square root" sqrt(x)
1462
"natural log" log(x) "common log" log10(x)
1463
"modulus" i % j "random # [0.0,1.0)" random()
1464
"minimum" min(x,y) "maximum" max(x,y)
1465
"if-then-else" b?x:y
1466
-
1467
1468
An alternate syntax for the min and max functions has only a single
1469
argument which should be a vector value (see below). The result
1470
will be the minimum/maximum element contained within the vector.
1471
1472
There are three functions that are primarily for use with SAO region
1473
files and the FSAOI task, but they can be used directly. They
1474
return a boolean true or false depending on whether a two
1475
dimensional point is in the region or not:
1476
-
1477
"point in a circular region"
1478
circle(xcntr,ycntr,radius,Xcolumn,Ycolumn)
1479
1480
"point in an elliptical region"
1481
ellipse(xcntr,ycntr,xhlf_wdth,yhlf_wdth,rotation,Xcolumn,Ycolumn)
1482
1483
"point in a rectangular region"
1484
box(xcntr,ycntr,xfll_wdth,yfll_wdth,rotation,Xcolumn,Ycolumn)
1485
1486
where
1487
(xcntr,ycntr) are the (x,y) position of the center of the region
1488
(xhlf_wdth,yhlf_wdth) are the (x,y) half widths of the region
1489
(xfll_wdth,yfll_wdth) are the (x,y) full widths of the region
1490
(radius) is half the diameter of the circle
1491
(rotation) is the angle(degrees) that the region is rotated with
1492
respect to (xcntr,ycntr)
1493
(Xcoord,Ycoord) are the (x,y) coordinates to test, usually column
1494
names
1495
NOTE: each parameter can itself be an expression, not merely a
1496
column name or constant.
1497
-
1498
1499
There is also a function for testing if two values are close to
1500
each other, i.e., if they are "near" each other to within a user
1501
specified tolerance. The arguments, value\_1 and value\_2 can be
1502
integer or real and represent the two values who's proximity is
1503
being tested to be within the specified tolerance, also an integer
1504
or real:
1505
-
1506
near(value_1, value_2, tolerance)
1507
-
1508
When a NULL, or undefined, value is encountered in the FITS table,
1509
the expression will evaluate to NULL unless the undefined value is
1510
not actually required for evaluation, e.g. "TRUE .or. NULL"
1511
evaluates to TRUE. The following two functions allow some NULL
1512
detection and handling: ISNULL(x) and DEFNULL(x,y). The former
1513
returns a boolean value of TRUE if the argument x is NULL. The
1514
later "defines" a value to be substituted for NULL values; it
1515
returns the value of x if x is not NULL, otherwise it returns the
1516
value of y.
1517
1518
The following type casting operators are available, where the
1519
inclosing parentheses are required and taken from the C language
1520
usage. Also, the integer to real casts values to double precision:
1521
-
1522
"real to integer" (int) x (INT) x
1523
"integer to real" (float) i (FLOAT) i
1524
-
1525
1526
Bit masks can be used to select out rows from bit columns (TFORMn =
1527
\#X) in FITS files. To represent the mask, binary, octal, and hex
1528
formats are allowed:
1529
1530
-
1531
binary: b0110xx1010000101xxxx0001
1532
octal: o720x1 -> (b111010000xxx001)
1533
hex: h0FxD -> (b00001111xxxx1101)
1534
-
1535
1536
In all the representations, an x or X is allowed in the mask as a
1537
wild card. Note that the x represents a different number of wild
1538
card bits in each representation. All representations are case
1539
insensitive.
1540
1541
To construct the boolean expression using the mask as the boolean
1542
equal operator described above on a bit table column. For example,
1543
if you had a 7 bit column named flags in a FITS table and wanted
1544
all rows having the bit pattern 0010011, the selection expression
1545
would be:
1546
1547
-
1548
flags == b0010011
1549
or
1550
flags .eq. b10011
1551
-
1552
1553
It is also possible to test if a range of bits is less than, less
1554
than equal, greater than and greater than equal to a particular
1555
boolean value:
1556
1557
-
1558
flags <= bxxx010xx
1559
flags .gt. bxxx100xx
1560
flags .le. b1xxxxxxx
1561
-
1562
1563
Notice the use of the x bit value to limit the range of bits being
1564
compared.
1565
1566
It is not necessary to specify the leading (most significant) zero
1567
(0) bits in the mask, as shown in the second expression above.
1568
1569
Bit wise AND, OR and NOT operations are also possible on two or
1570
more bit fields using the '\&'(AND), '$|$'(OR), and the '!'(NOT)
1571
operators. All of these operators result in a bit field which can
1572
then be used with the equal operator. For example:
1573
1574
-
1575
(!flags) == b1101100
1576
(flags & b1000001) == bx000001
1577
-
1578
1579
Bit fields can be appended as well using the '+' operator. Strings
1580
can be concatenated this way, too.
1581
1582
In addition, several constants are built in for use in numerical
1583
expressions:
1584
1585
-
1586
#pi 3.1415... #e 2.7182...
1587
#deg #pi/180 #row current row number
1588
#null undefined value #snull undefined string
1589
-
1590
1591
A string constant must be enclosed in quotes as in 'Crab'. The
1592
"null" constants are useful for conditionally setting table values
1593
to a NULL, or undefined, value (eg., "col1==-99 ? \#NULL : col1").
1594
1595
***2. Vector Columns
1596
1597
Vector columns can also be used in building the expression. No
1598
special syntax is required if one wants to operate on all elements
1599
of the vector. Simply use the column name as for a scalar column.
1600
Vector columns can be freely intermixed with scalar columns or
1601
constants in virtually all expressions. The result will be of the
1602
same dimension as the vector. Two vectors in an expression, though,
1603
need to have the same number of elements and have the same
1604
dimensions. The only places a vector column cannot be used (for
1605
now, anyway) are the SAO region functions and the NEAR boolean
1606
function.
1607
1608
Arithmetic and logical operations are all performed on an element by
1609
element basis. Comparing two vector columns, eg "COL1 == COL2",
1610
thus results in another vector of boolean values indicating which
1611
elements of the two vectors are equal. Two functions are available
1612
which operate on vectors: SUM(x) and NELEM(x). The former
1613
literally sums all the elements in x, returning a scalar value. If
1614
x is a boolean vector, SUM returns the number of TRUE elements.
1615
The latter, NELEM, returns the number of elements in vector x.
1616
(NELEM also operates on bit and string columns, returning their
1617
column widths.) As an example, to test whether all elements of two
1618
vectors satisfy a given logical comparison, one can use the
1619
expression
1620
1621
-
1622
SUM( COL1 > COL2 ) == NELEM( COL1 )
1623
-
1624
1625
which will return TRUE if all elements of COL1 are greater than
1626
their corresponding elements in COL2.
1627
1628
To specify a single element of a vector, give the column name
1629
followed by a comma-separated list of coordinates enclosed in
1630
square brackets. For example, if a vector column named PHAS exists
1631
in the table as a one dimensional, 256 component list of numbers
1632
from which you wanted to select the 57th component for use in the
1633
expression, then PHAS[57] would do the trick. Higher dimensional
1634
arrays of data may appear in a column. But in order to interpret
1635
them, the TDIMn keyword must appear in the header. Assuming that a
1636
(4,4,4,4) array is packed into each row of a column named ARRAY4D,
1637
the (1,2,3,4) component element of each row is accessed by
1638
ARRAY4D[1,2,3,4]. Arrays up to dimension 5 are currently
1639
supported. Each vector index can itself be an expression, although
1640
it must evaluate to an integer value within the bounds of the
1641
vector. Vector columns which contain spaces or arithmetic operators
1642
must have their names enclosed in "\$" characters as with
1643
\$ARRAY-4D\$[1,2,3,4].
1644
1645
A more C-like syntax for specifying vector indices is also
1646
available. The element used in the preceding example alternatively
1647
could be specified with the syntax ARRAY4D[4][3][2][1]. Note the
1648
reverse order of indices (as in C), as well as the fact that the
1649
values are still ones-based (as in Fortran -- adopted to avoid
1650
ambiguity for 1D vectors). With this syntax, one does not need to
1651
specify all of the indices. To extract a 3D slice of this 4D
1652
array, use ARRAY4D[4].
1653
1654
Variable-length vector columns are not supported.
1655
1656
Vectors can be manually constructed within the expression using a
1657
comma-separated list of elements surrounded by curly braces ('\{\}').
1658
For example, '\{1,3,6,1\}' is a 4-element vector containing the values
1659
1, 3, 6, and 1. The vector can contain only boolean, integer, and
1660
real values (or expressions). The elements will be promoted to the
1661
highest datatype present. Any elements which are themselves
1662
vectors, will be expanded out with each of its elements becoming an
1663
element in the constructed vector.
1664
1665
***3. Good Time Interval Filtering
1666
1667
A common filtering method involves selecting rows which have a time
1668
value which lies within what is called a Good Time Interval or GTI.
1669
The time intervals are defined in a separate FITS table extension
1670
which contains 2 columns giving the start and stop time of each
1671
good interval. The filtering operation accepts only those rows of
1672
the input table which have an associated time which falls within
1673
one of the time intervals defined in the GTI extension. A high
1674
level function, gtifilter(a,b,c,d), is available which evaluates
1675
each row of the input table and returns TRUE or FALSE depending
1676
whether the row is inside or outside the good time interval. The
1677
syntax is
1678
-
1679
gtifilter( [ "gtifile" [, expr [, "STARTCOL", "STOPCOL" ] ] ] )
1680
-
1681
where each "[]" demarks optional parameters. Note that the quotes
1682
around the gtifile and START/STOP column are required. The gtifile,
1683
if specified, can be blank ("") which will mean to use the first
1684
extension with the name "*GTI*" in the current file, a plain
1685
extension specifier (eg, "+2", "[2]", or "[STDGTI]") which will be
1686
used to select an extension in the current file, or a regular
1687
filename with or without an extension specifier which in the latter
1688
case will mean to use the first extension with an extension name
1689
"*GTI*". Expr can be any arithmetic expression, including simply
1690
the time column name. A vector time expression will produce a
1691
vector boolean result. STARTCOL and STOPCOL are the names of the
1692
START/STOP columns in the GTI extension. If one of them is
1693
specified, they both must be.
1694
1695
In its simplest form, no parameters need to be provided -- default
1696
values will be used. The expression "gtifilter()" is equivalent to
1697
-
1698
gtifilter( "", TIME, "*START*", "*STOP*" )
1699
-
1700
This will search the current file for a GTI extension, filter the
1701
TIME column in the current table, using START/STOP times taken from
1702
columns in the GTI extension with names containing the strings
1703
"START" and "STOP". The wildcards ('*') allow slight variations in
1704
naming conventions such as "TSTART" or "STARTTIME". The same
1705
default values apply for unspecified parameters when the first one
1706
or two parameters are specified. The function automatically
1707
searches for TIMEZERO/I/F keywords in the current and GTI
1708
extensions, applying a relative time offset, if necessary.
1709
1710
***4. Spatial Region Filtering
1711
1712
Another common filtering method selects rows based on whether the
1713
spatial position associated with each row is located within a given
1714
2-dimensional region. The syntax for this high-level filter is
1715
-
1716
regfilter( "regfilename" [ , Xexpr, Yexpr [ , "wcs cols" ] ] )
1717
-
1718
where each "[]" demarks optional parameters. The region file name
1719
is required and must be enclosed in quotes. The remaining
1720
parameters are optional. The region file is an ASCII text file
1721
which contains a list of one or more geometric shapes (circle,
1722
ellipse, box, etc.) which defines a region on the celestial sphere
1723
or an area within a particular 2D image. The region file is
1724
typically generated using an image display program such as fv/POW
1725
(distribute by the HEASARC), or ds9 (distributed by the Smithsonian
1726
Astrophysical Observatory). Users should refer to the documentation
1727
provided with these programs for more details on the syntax used in
1728
the region files.
1729
1730
In its simpliest form, (e.g., regfilter("region.reg") ) the
1731
coordinates in the default 'X' and 'Y' columns will be used to
1732
determine if each row is inside or outside the area specified in
1733
the region file. Alternate position column names, or expressions,
1734
may be entered if needed, as in
1735
-
1736
regfilter("region.reg", XPOS, YPOS)
1737
-
1738
Region filtering can be applied most unambiguously if the positions
1739
in the region file and in the table to be filtered are both give in
1740
terms of absolute celestial coordinate units. In this case the
1741
locations and sizes of the geometric shapes in the region file are
1742
specified in angular units on the sky (e.g., positions given in
1743
R.A. and Dec. and sizes in arcseconds or arcminutes). Similarly,
1744
each row of the filtered table will have a celestial coordinate
1745
associated with it. This association is usually implemented using
1746
a set of so-called 'World Coordinate System' (or WCS) FITS keywords
1747
that define the coordinate transformation that must be applied to
1748
the values in the 'X' and 'Y' columns to calculate the coordinate.
1749
1750
Alternatively, one can perform spatial filtering using unitless
1751
'pixel' coordinates for the regions and row positions. In this
1752
case the user must be careful to ensure that the positions in the 2
1753
files are self-consistent. A typical problem is that the region
1754
file may be generated using a binned image, but the unbinned
1755
coordinates are given in the event table. The ROSAT events files,
1756
for example, have X and Y pixel coordinates that range from 1 -
1757
15360. These coordinates are typically binned by a factor of 32 to
1758
produce a 480x480 pixel image. If one then uses a region file
1759
generated from this image (in image pixel units) to filter the
1760
ROSAT events file, then the X and Y column values must be converted
1761
to corresponding pixel units as in:
1762
-
1763
regfilter("rosat.reg", X/32.+.5, Y/32.+.5)
1764
-
1765
Note that this binning conversion is not necessary if the region
1766
file is specified using celestial coordinate units instead of pixel
1767
units because CFITSIO is then able to directly compare the
1768
celestial coordinate of each row in the table with the celestial
1769
coordinates in the region file without having to know anything
1770
about how the image may have been binned.
1771
1772
The last "wcs cols" parameter should rarely be needed. If supplied,
1773
this string contains the names of the 2 columns (space or comma
1774
separated) which have the associated WCS keywords. If not supplied,
1775
the filter will scan the X and Y expressions for column names.
1776
If only one is found in each expression, those columns will be
1777
used, otherwise an error will be returned.
1778
1779
These region shapes are supported (names are case insensitive):
1780
-
1781
Point ( X1, Y1 ) <- One pixel square region
1782
Line ( X1, Y1, X2, Y2 ) <- One pixel wide region
1783
Polygon ( X1, Y1, X2, Y2, ... ) <- Rest are interiors with
1784
Rectangle ( X1, Y1, X2, Y2, A ) | boundaries considered
1785
Box ( Xc, Yc, Wdth, Hght, A ) V within the region
1786
Diamond ( Xc, Yc, Wdth, Hght, A )
1787
Circle ( Xc, Yc, R )
1788
Annulus ( Xc, Yc, Rin, Rout )
1789
Ellipse ( Xc, Yc, Rx, Ry, A )
1790
Elliptannulus ( Xc, Yc, Rinx, Riny, Routx, Routy, Ain, Aout )
1791
Sector ( Xc, Yc, Amin, Amax )
1792
-
1793
where (Xc,Yc) is the coordinate of the shape's center; (X\#,Y\#) are
1794
the coordinates of the shape's edges; Rxxx are the shapes' various
1795
Radii or semimajor/minor axes; and Axxx are the angles of rotation
1796
(or bounding angles for Sector) in degrees. For rotated shapes, the
1797
rotation angle can be left off, indicating no rotation. Common
1798
alternate names for the regions can also be used: rotbox = box;
1799
rotrectangle = rectangle; (rot)rhombus = (rot)diamond; and pie
1800
= sector. When a shape's name is preceded by a minus sign, '-',
1801
the defined region is instead the area *outside* its boundary (ie,
1802
the region is inverted). All the shapes within a single region
1803
file are OR'd together to create the region, and the order is
1804
significant. The overall way of looking at region files is that if
1805
the first region is an excluded region then a dummy included region
1806
of the whole detector is inserted in the front. Then each region
1807
specification as it is processed overrides any selections inside of
1808
that region specified by previous regions. Another way of thinking
1809
about this is that if a previous excluded region is completely
1810
inside of a subsequent included region the excluded region is
1811
ignored.
1812
1813
The positional coordinates may be given either in pixel units,
1814
decimal degrees or hh:mm:ss.s, dd:mm:ss.s units. The shape sizes
1815
may be given in pixels, degrees, arcminutes, or arcseconds. Look
1816
at examples of region file produced by fv/POW or ds9 for further
1817
details of the region file format.
1818
1819
1820
***5. Example Row Filters
1821
-
1822
[ binary && mag <= 5.0] - Extract all binary stars brighter
1823
than fifth magnitude (note that
1824
the initial space is necessary to
1825
prevent it from being treated as a
1826
binning specification)
1827
1828
[#row >= 125 && #row <= 175] - Extract row numbers 125 through 175
1829
1830
[IMAGE[4,5] .gt. 100] - Extract all rows that have the
1831
(4,5) component of the IMAGE column
1832
greater than 100
1833
1834
[abs(sin(theta * #deg)) < 0.5] - Extract all rows having the
1835
absolute value of the sine of theta
1836
less than a half where the angles
1837
are tabulated in degrees
1838
1839
[SUM( SPEC > 3*BACKGRND )>=1] - Extract all rows containing a
1840
spectrum, held in vector column
1841
SPEC, with at least one value 3
1842
times greater than the background
1843
level held in a keyword, BACKGRND
1844
1845
[VCOL=={1,4,2}] - Extract all rows whose vector column
1846
VCOL contains the 3-elements 1, 4, and
1847
2.
1848
1849
[@rowFilter.txt] - Extract rows using the expression
1850
contained within the text file
1851
rowFilter.txt
1852
1853
[gtifilter()] - Search the current file for a GTI
1854
extension, filter the TIME
1855
column in the current table, using
1856
START/STOP times taken from
1857
columns in the GTI extension
1858
1859
[regfilter("pow.reg")] - Extract rows which have a coordinate
1860
(as given in the X and Y columns)
1861
within the spatial region specified
1862
in the pow.reg region file.
1863
1864
[regfilter("pow.reg", Xs, Ys)] - Same as above, except that the
1865
Xs and Ys columns will be used to
1866
determine the coordinate of each
1867
row in the table.
1868
-
1869
1870
**I. Binning or Histogramming Specification
1871
1872
The optional binning specifier is enclosed in square brackets and can
1873
be distinguished from a general row filter specification by the fact
1874
that it begins with the keyword 'bin' not immediately followed by an
1875
equals sign. When binning is specfied, a temporary N-dimensional FITS
1876
primary array is created by computing the histogram of the values in
1877
the specified columns of a FITS table extension. After the histogram
1878
is computed the input FITS file containing the table is then closed and
1879
the temporary FITS primary array is opened and passed to the
1880
application program. Thus, the application program never sees the
1881
original FITS table and only sees the image in the new temporary file
1882
(which has no additional extensions). Obviously, the application
1883
program must be expecting to open a FITS image and not a FITS table in
1884
this case.
1885
1886
The data type of the FITS histogram image may be specified by appending
1887
'b' (for 8-bit byte), 'i' (for 16-bit integers), 'j' (for 32-bit
1888
integer), 'r' (for 32-bit floating points), or 'd' (for 64-bit double
1889
precision floating point) to the 'bin' keyword (e.g. '[binr X]'
1890
creates a real floating point image). If the datatype is not
1891
explicitly specified then a 32-bit integer image will be created by
1892
default, unless the weighting option is also specified in which case
1893
the image will have a 32-bit floating point data type by default.
1894
1895
The histogram image may have from 1 to 4 dimensions (axes), depending
1896
on the number of columns that are specified. The general form of the
1897
binning specification is:
1898
-
1899
[bin{bijrd} Xcol=min:max:binsize, Ycol= ..., Zcol=..., Tcol=...; weight]
1900
-
1901
in which up to 4 columns, each corresponding to an axis of the image,
1902
are listed. The column names are case insensitive, and the column
1903
number may be given instead of the name, preceded by a pound sign
1904
(e.g., [bin \#4=1:512]). If the column name is not specified, then
1905
CFITSIO will first try to use the 'preferred column' as specified by
1906
the CPREF keyword if it exists (e.g., 'CPREF = 'DETX,DETY'), otherwise
1907
column names 'X', 'Y', 'Z', and 'T' will be assumed for each of the 4
1908
axes, respectively.
1909
1910
Each column name may be followed by an equals sign and then the lower
1911
and upper range of the histogram, and the size of the histogram bins,
1912
separated by colons. Spaces are allowed before and after the equals
1913
sign but not within the 'min:max:binsize' string. The min, max and
1914
binsize values may be integer or floating point numbers, or they may be
1915
the names of keywords in the header of the table. If the latter, then
1916
the value of that keyword is substituted into the expression.
1917
1918
Default values for the min, max and binsize quantities will be
1919
used if not explicitly given in the binning expression as shown
1920
in these examples:
1921
-
1922
[bin x = :512:2] - use default minimum value
1923
[bin x = 1::2] - use default maximum value
1924
[bin x = 1:512] - use default bin size
1925
[bin x = 1:] - use default maximum value and bin size
1926
[bin x = :512] - use default minimum value and bin size
1927
[bin x = 2] - use default minimum and maximum values
1928
[bin x] - use default minimum, maximum and bin size
1929
[bin 4] - default 2-D image, bin size = 4 in both axes
1930
[bin] - default 2-D image
1931
-
1932
CFITSIO will use the value of the TLMINn, TLMAXn, and TDBINn keywords,
1933
if they exist, for the default min, max, and binsize, respectively. If
1934
they do not exist then CFITSIO will use the actual minimum and maximum
1935
values in the column for the histogram min and max values. The default
1936
binsize will be set to 1, or (max - min) / 10., whichever is smaller,
1937
so that the histogram will have at least 10 bins along each axis.
1938
1939
A shortcut notation is allowed if all the columns/axes have the same
1940
binning specification. In this case all the column names may be listed
1941
within parentheses, followed by the (single) binning specification, as
1942
in:
1943
-
1944
[bin (X,Y)=1:512:2]
1945
[bin (X,Y) = 5]
1946
-
1947
1948
The optional weighting factor is the last item in the binning specifier
1949
and, if present, is separated from the list of columns by a
1950
semi-colon. As the histogram is accumulated, this weight is used to
1951
incremented the value of the appropriated bin in the histogram. If the
1952
weighting factor is not specified, then the default weight = 1 is
1953
assumed. The weighting factor may be a constant integer or floating
1954
point number, or the name of a keyword containing the weighting value.
1955
Or the weighting factor may be the name of a table column in which case
1956
the value in that column, on a row by row basis, will be used.
1957
1958
In some cases, the column or keyword may give the reciprocal of the
1959
actual weight value that is needed. In this case, precede the weight
1960
keyword or column name by a slash '/' to tell CFITSIO to use the
1961
reciprocal of the value when constructing the histogram.
1962
1963
For complex or commonly used histograms, one can also place its
1964
description into a text file and import it into the binning
1965
specification using the syntax '[bin @filename.txt]'. The file's
1966
contents can extend over multiple lines, although it must still
1967
conform to the no-spaces rule for the min:max:binsize syntax and each
1968
axis specification must still be comma-separated. Any lines in the
1969
external text file that begin with 2 slash characters ('//') will be
1970
ignored and may be used to add comments into the file.
1971
1972
Examples:
1973
1974
-
1975
[bini detx, dety] - 2-D, 16-bit integer histogram
1976
of DETX and DETY columns, using
1977
default values for the histogram
1978
range and binsize
1979
1980
[bin (detx, dety)=16; /exposure] - 2-D, 32-bit real histogram of DETX
1981
and DETY columns with a bin size = 16
1982
in both axes. The histogram values
1983
are divided by the EXPOSURE keyword
1984
value.
1985
1986
[bin time=TSTART:TSTOP:0.1] - 1-D lightcurve, range determined by
1987
the TSTART and TSTOP keywords,
1988
with 0.1 unit size bins.
1989
1990
[bin pha, time=8000.:8100.:0.1] - 2-D image using default binning
1991
of the PHA column for the X axis,
1992
and 1000 bins in the range
1993
8000. to 8100. for the Y axis.
1994
1995
[bin @binFilter.txt] - Use the contents of the text file
1996
binFilter.txt for the binning
1997
specifications.
1998
1999
-
2000
2001
2002
*V. Template Files
2003
2004
When a new FITS file is created with a call to fits\_create\_file, the
2005
name of a template file may be supplied in parentheses immediately
2006
following the name of the new file to be created. This template is
2007
used to define the structure of one or more HDUs in the new file. The
2008
template file may be another FITS file, in which case the newly created
2009
file will have exactly the same keywords in each HDU as in the template
2010
FITS file, but all the data units will be filled with zeros. The
2011
template file may also be an ASCII text file, where each line (in
2012
general) describes one FITS keyword record. The format of the ASCII
2013
template file is described in the following sections.
2014
2015
**A Detailed Template Line Format
2016
2017
The format of each ASCII template line closely follows the format of a
2018
FITS keyword record:
2019
-
2020
KEYWORD = KEYVALUE / COMMENT
2021
-
2022
except that free format may be used (e.g., the equals sign may appear
2023
at any position in the line) and TAB characters are allowed and are
2024
treated the same as space characters. The KEYVALUE and COMMENT fields
2025
are optional. The equals sign character is also optional, but it is
2026
recommended that it be included for clarity. Any template line that
2027
begins with the pound '\#' character is ignored by the template parser
2028
and may be use to insert comments into the template file itself.
2029
2030
The KEYWORD name field is limited to 8 characters in length and only
2031
the letters A-Z, digits 0-9, and the hyphen and underscore characters
2032
may be used, without any embedded spaces. Lowercase letters in the
2033
template keyword name will be converted to uppercase. Leading spaces
2034
in the template line preceding the keyword name are generally ignored,
2035
except if the first 8 characters of a template line are all blank, then
2036
the entire line is treated as a FITS comment keyword (with a blank
2037
keyword name) and is copied verbatim into the FITS header.
2038
2039
The KEYVALUE field may have any allowed FITS data type: character
2040
string, logical, integer, real, complex integer, or complex real. The
2041
character string values need not be enclosed in single quote characters
2042
unless they are necessary to distinguish the string from a different
2043
data type (e.g. 2.0 is a real but '2.0' is a string). The keyword has
2044
an undefined (null) value if the template record only contains blanks
2045
following the "=" or between the "=" and the "/" comment field
2046
delimiter.
2047
2048
String keyword values longer than 68 characters (the maximum length
2049
that will fit in a single FITS keyword record) are permitted using the
2050
CFITSIO long string convention. They can either be specified as a
2051
single long line in the template, or by using multiple lines where the
2052
continuing lines contain the 'CONTINUE' keyword, as in this example:
2053
-
2054
LONGKEY = 'This is a long string value that is contin&'
2055
CONTINUE 'ued over 2 records' / comment field goes here
2056
-
2057
The format of template lines with CONTINUE keyword is very strict: 3
2058
spaces must follow CONTINUE and the rest of the line is copied verbatim
2059
to the FITS file.
2060
2061
The start of the optional COMMENT field must be preceded by "/", which
2062
is used to separate it from the keyword value field. Exceptions are if
2063
the KEYWORD name field contains COMMENT, HISTORY, CONTINUE, or if the
2064
first 8 characters of the template line are blanks.
2065
2066
More than one Header-Data Unit (HDU) may be defined in the template
2067
file. The start of an HDU definition is denoted with a SIMPLE or
2068
XTENSION template line:
2069
2070
1) SIMPLE begins a Primary HDU definition. SIMPLE may only appear as
2071
the first keyword in the template file. If the template file begins
2072
with XTENSION instead of SIMPLE, then a default empty Primary HDU is
2073
created, and the template is then assumed to define the keywords
2074
starting with the first extension following the Primary HDU.
2075
2076
2) XTENSION marks the beginning of a new extension HDU definition. The
2077
previous HDU will be closed at this point and processing of the next
2078
extension begins.
2079
2080
**B Auto-indexing of Keywords
2081
2082
If a template keyword name ends with a "\#" character, it is said to be
2083
'auto-indexed'. Each "\#" character will be replaced by the current
2084
integer index value, which gets reset = 1 at the start of each new HDU
2085
in the file (or 7 in the special case of a GROUP definition). The
2086
FIRST indexed keyword in each template HDU definition is used as the
2087
'incrementor'; each subsequent occurrence of this SAME keyword will
2088
cause the index value to be incremented. This behavior can be rather
2089
subtle, as illustrated in the following examples in which the TTYPE
2090
keyword is the incrementor in both cases:
2091
-
2092
TTYPE# = TIME
2093
TFORM# = 1D
2094
TTYPE# = RATE
2095
TFORM# = 1E
2096
-
2097
will create TTYPE1, TFORM1, TTYPE2, and TFORM2 keywords. But if the
2098
template looks like,
2099
-
2100
TTYPE# = TIME
2101
TTYPE# = RATE
2102
TFORM# = 1D
2103
TFORM# = 1E
2104
-
2105
this results in a FITS files with TTYPE1, TTYPE2, TFORM2, and TFORM2,
2106
which is probably not what was intended!
2107
2108
**C Template Parser Directives
2109
2110
In addition to the template lines which define individual keywords, the
2111
template parser recognizes 3 special directives which are each preceded
2112
by the backslash character: \verb+ \include, \group+, and \verb+ \end+.
2113
2114
The 'include' directive must be followed by a filename. It forces the
2115
parser to temporarily stop reading the current template file and begin
2116
reading the include file. Once the parser reaches the end of the
2117
include file it continues parsing the current template file. Include
2118
files can be nested, and HDU definitions can span multiple template
2119
files.
2120
2121
The start of a GROUP definition is denoted with the 'group' directive,
2122
and the end of a GROUP definition is denoted with the 'end' directive.
2123
Each GROUP contains 0 or more member blocks (HDUs or GROUPs). Member
2124
blocks of type GROUP can contain their own member blocks. The GROUP
2125
definition itself occupies one FITS file HDU of special type (GROUP
2126
HDU), so if a template specifies 1 group with 1 member HDU like:
2127
-
2128
\group
2129
grpdescr = 'demo'
2130
xtension bintable
2131
# this bintable has 0 cols, 0 rows
2132
\end
2133
-
2134
then the parser creates a FITS file with 3 HDUs :
2135
-
2136
1) dummy PHDU
2137
2) GROUP HDU (has 1 member, which is bintable in HDU number 3)
2138
3) bintable (member of GROUP in HDU number 2)
2139
-
2140
Technically speaking, the GROUP HDU is a BINTABLE with 6 columns. Applications
2141
can define additional columns in a GROUP HDU using TFORMn and TTYPEn
2142
(where n is 7, 8, ....) keywords or their auto-indexing equivalents.
2143
2144
For a more complicated example of a template file using the group directives,
2145
look at the sample.tpl file that is included in the CFITSIO distribution.
2146
2147
**D Formal Template Syntax
2148
2149
The template syntax can formally be defined as follows:
2150
-
2151
TEMPLATE = BLOCK [ BLOCK ... ]
2152
2153
BLOCK = { HDU | GROUP }
2154
2155
GROUP = \GROUP [ BLOCK ... ] \END
2156
2157
HDU = XTENSION [ LINE ... ] { XTENSION | \GROUP | \END | EOF }
2158
2159
LINE = [ KEYWORD [ = ] ] [ VALUE ] [ / COMMENT ]
2160
2161
X ... - X can be present 1 or more times
2162
{ X | Y } - X or Y
2163
[ X ] - X is optional
2164
-
2165
2166
At the topmost level, the template defines 1 or more template blocks. Blocks
2167
can be either HDU (Header Data Unit) or a GROUP. For each block the parser
2168
creates 1 (or more for GROUPs) FITS file HDUs.
2169
2170
2171
**E Errors
2172
2173
In general the fits\_execute\_template() function tries to be as atomic
2174
as possible, so either everything is done or nothing is done. If an
2175
error occurs during parsing of the template, fits\_execute\_template()
2176
will (try to) delete the top level BLOCK (with all its children if any)
2177
in which the error occurred, then it will stop reading the template file
2178
and it will return with an error.
2179
2180
**F Examples
2181
2182
1. This template file will create a 200 x 300 pixel image, with 4-byte
2183
integer pixel values, in the primary HDU:
2184
-
2185
SIMPLE = T
2186
BITPIX = 32
2187
NAXIS = 2 / number of dimensions
2188
NAXIS1 = 100 / length of first axis
2189
NAXIS2 = 200 / length of second axis
2190
OBJECT = NGC 253 / name of observed object
2191
-
2192
The allowed values of BITPIX are 8, 16, 32, -32, or -64,
2193
representing, respectively, 8-bit integer, 16-bit integer, 32-bit
2194
integer, 32-bit floating point, or 64 bit floating point pixels.
2195
2196
2. To create a FITS table, the template first needs to include
2197
XTENSION = TABLE or BINTABLE to define whether it is an ASCII or binary
2198
table, and NAXIS2 to define the number of rows in the table. Two
2199
template lines are then needed to define the name (TTYPEn) and FITS data
2200
format (TFORMn) of the columns, as in this example:
2201
-
2202
xtension = bintable
2203
naxis2 = 40
2204
ttype# = Name
2205
tform# = 10a
2206
ttype# = Npoints
2207
tform# = j
2208
ttype# = Rate
2209
tunit# = counts/s
2210
tform# = e
2211
-
2212
The above example defines a null primary array followed by a 40-row
2213
binary table extension with 3 columns called 'Name', 'Npoints', and
2214
'Rate', with data formats of '10A' (ASCII character string), '1J'
2215
(integer) and '1E' (floating point), respectively. Note that the other
2216
required FITS keywords (BITPIX, NAXIS, NAXIS1, PCOUNT, GCOUNT, TFIELDS,
2217
and END) do not need to be explicitly defined in the template because
2218
their values can be inferred from the other keywords in the template.
2219
This example also illustrates that the templates are generally
2220
case-insensitive (the keyword names and TFORMn values are converted to
2221
upper-case in the FITS file) and that string keyword values generally
2222
do not need to be enclosed in quotes.
2223
2224
*V. FITSIO Conventions and Guidelines
2225
2226
**A. CFITSIO Size Limitations
2227
2228
CFITSIO places few restrictions on the size of FITS files that it
2229
reads or writes. There are a few limits, however, which may affect
2230
some extreme cases:
2231
2232
1. The maximum number of files that may be simultaneously opened is
2233
limited to the number of internal IO buffers allocated in CFITSIO
2234
(currently 25, as defined by NIOBUF in the file fitsio2.h), or by the
2235
limit of the underlying C compiler or machine operating system, which
2236
ever is smaller. The C symbolic constant FOPEN\_MAX usually defines
2237
the total number of files that may open at once (this includes any
2238
other text or binary files which may be open, not just FITS files).
2239
2240
2. The maximum number of extensions (HDUs) that can be read or written
2241
in a single FITS file is currently set to 1000 as defined by MAXHDU in
2242
the fitsio.h file. This value may be increased if necessary, but the
2243
access times to the later extensions in such files may become excessively
2244
long.
2245
2246
3. By default, CFITSIO can handle FITS files up to 2.1 GB in size
2247
(2**31 bytes). This file size limit is often imposed by 32-bit
2248
operating systems. More recently, as 64-bit operating systems become
2249
more common, an industry-wide standard (at least on Unix systems) has
2250
been developed to support larger sized files (see
2251
http://ftp.sas.com/standards/large.file/). Starting with version 2.1
2252
of CFITSIO, larger FITS files up to 6 terabytes in size may be read and
2253
written on certain supported platforms. In order to support these
2254
larger files, CFITSIO must be compiled with the
2255
`-D\_FILE\_OFFSET\_BITS=64' compiler flag. All programs which link to
2256
the CFITSIO library must also be compiled with this flag or must
2257
include this preprocessor definition at the start of the source code
2258
file. This causes the compiler to allocate 8-bytes instead of 4-bytes
2259
for the `off\_t' datatype which is used to store file offset
2260
positions.
2261
2262
If CFITSIO is compiled with the -D\_FILE\_OFFSET\_BITS=64 flag on a
2263
platform that supports large files, then it can read and write FITS
2264
files that contain up to 2**31 2880-byte FITS records, or approximately
2265
6 terabytes in size. It is still required that the value of the NAXISn
2266
and PCOUNT keywords in each extension be within the range of a signed
2267
4-byte integer (max value = 2,147,483,648). Thus, each dimension of an
2268
image (given by the NAXISn keywords), the total width of a table
2269
(NAXIS1 keyword), the number of rows in a table (NAXIS2 keyword), and
2270
the total size of the variable-length array heap in binary tables
2271
(PCOUNT keyword) must be less than this limit.
2272
2273
Currently, support for large files within CFITSIO has only been tested
2274
on the Solaris 2.6 operating system using the Sun cc compiler or gcc
2275
2.95.2.
2276
2277
**B. Multiple Access to the Same FITS File
2278
2279
CFITSIO supports simultaneous read and write access to multiple HDUs in
2280
the same FITS file. Thus, one can open the same FITS file twice within
2281
a single program and move to 2 different HDUs in the file, and then
2282
read and write data or keywords to the 2 extensions just as if one were
2283
accessing 2 completely separate FITS files. Since in general it is
2284
not possible to physically open the same file twice and then expect to
2285
be able to simultaneously (or in alternating succession) write to 2
2286
different locations in the file, CFITSIO recognizes when the file to be
2287
opened (in the call to fits\_open\_file) has already been opened and
2288
instead of actually opening the file again, just logically links the
2289
new file to the old file. (This only applies if the file is opened
2290
more than once within the same program, and does not prevent the same
2291
file from being simultaneously opened by more than one program). Then
2292
before CFITSIO reads or writes to either (logical) file, it makes sure
2293
that any modifications made to the other file have been completely
2294
flushed from the internal buffers to the file. Thus, in principle, one
2295
could open a file twice, in one case pointing to the first extension
2296
and in the other pointing to the 2nd extension and then write data to
2297
both extensions, in any order, without danger of corrupting the file,
2298
There may be some efficiency penalties in doing this however, since
2299
CFITSIO has to flush all the internal buffers related to one file
2300
before switching to the other, so it would still be prudent to
2301
minimize the number of times one switches back and forth between doing
2302
I/O to different HDUs in the same file.
2303
2304
**C. Current Header Data Unit (CHDU)
2305
2306
In general, a FITS file can contain multiple Header Data Units, also
2307
called extensions. CFITSIO only operates within one HDU at any given
2308
time, and the currently selected HDU is called the Current Header Data
2309
Unit (CHDU). When a FITS file is first created or opened the CHDU is
2310
automatically defined to be the first HDU (i.e., the primary array).
2311
CFITSIO routines are provided to move to and open any other existing
2312
HDU within the FITS file or to append or insert a new HDU in the FITS
2313
file which then becomes the CHDU.
2314
2315
**D. Subroutine Names
2316
2317
All FITSIO subroutine names begin with the letters 'ft' to distinguish
2318
them from other subroutines and are 5 or 6 characters long. Users should
2319
not name their own subroutines beginning with 'ft' to avoid conflicts.
2320
(The SPP interface routines all begin with 'fs'). Subroutines which read
2321
or get information from the FITS file have names beginning with
2322
'ftg...'. Subroutines which write or put information into the FITS file
2323
have names beginning with 'ftp...'.
2324
2325
**E. Subroutine Families and Datatypes
2326
2327
Many of the subroutines come in families which differ only in the
2328
datatype of the associated parameter(s) . The datatype of these
2329
subroutines is indicated by the last letter of the subroutine name
2330
(e.g., 'j' in 'ftpkyj') as follows:
2331
-
2332
x - bit
2333
b - character*1 (unsigned byte)
2334
i - short integer (I*2)
2335
j - integer (I*4)
2336
e - real exponential floating point (R*4)
2337
f - real fixed-format floating point (R*4)
2338
d - double precision real floating-point (R*8)
2339
g - double precision fixed-format floating point (R*8)
2340
c - complex reals (pairs of R*4 values)
2341
m - double precision complex (pairs of R*8 values)
2342
l - logical (L*4)
2343
s - character string
2344
-
2345
2346
When dealing with the FITS byte datatype, it is important to remember
2347
that the raw values (before any scaling by the BSCALE and BZERO, or
2348
TSCALn and TZEROn keyword values) in byte arrays (BITPIX = 8) or byte
2349
columns (TFORMn = 'B') are interpreted as unsigned bytes with values
2350
ranging from 0 to 255. Some Fortran compilers support a non-standard
2351
byte datatype such as INTEGER*1, LOGICAL*1, or BYTE, which can sometimes
2352
be used instead of CHARACTER*1 variables. Many machines permit passing a
2353
numeric datatype (such as INTEGER*1) to the FITSIO subroutines which are
2354
expecting a CHARACTER*1 datatype, but this technically violates the
2355
Fortran-77 standard and is not supported on all machines (e.g., on a VAX/VMS
2356
machine one must use the VAX-specific \%DESCR function).
2357
2358
One feature of the CFITSIO routines is that they can operate on a `X'
2359
(bit) column in a binary table as though it were a `B' (byte) column.
2360
For example a `11X' datatype column can be interpreted the same as a
2361
`2B' column (i.e., 2 unsigned 8-bit bytes). In some instances, it can
2362
be more efficient to read and write whole bytes at a time, rather than
2363
reading or writing each individual bit.
2364
2365
The double precision complex datatype is not a standard Fortran-77
2366
datatype. If a particular Fortran compiler does not directly support
2367
this datatype, then one may instead pass an array of pairs of double
2368
precision values to these subroutines. The first value in each pair
2369
is the real part, and the second is the imaginary part.
2370
2371
**F. Implicit Data Type Conversion
2372
2373
The FITSIO routines that read and write numerical data can perform
2374
implicit data type conversion. This means that the data type of the
2375
variable or array in the program does not need to be the same as the
2376
data type of the value in the FITS file. Data type conversion is
2377
supported for numerical and string data types (if the string contains a
2378
valid number enclosed in quotes) when reading a FITS header keyword
2379
value and for numeric values when reading or writing values in the
2380
primary array or a table column. CFITSIO returns status =
2381
NUM\_OVERFLOW if the converted data value exceeds the range of the
2382
output data type. Implicit data type conversion is not supported
2383
within binary tables for string, logical, complex, or double complex
2384
data types.
2385
2386
In addition, any table column may be read as if it contained string values.
2387
In the case of numeric columns the returned string will be formated
2388
using the TDISPn display format if it exists.
2389
2390
**G. Data Scaling
2391
2392
When reading numerical data values in the primary array or a
2393
table column, the values will be scaled automatically by the BSCALE and
2394
BZERO (or TSCALn and TZEROn) header keyword values if they are
2395
present in the header. The scaled data that is returned to the reading
2396
program will have
2397
-
2398
output value = (FITS value) * BSCALE + BZERO
2399
-
2400
(a corresponding formula using TSCALn and TZEROn is used when reading
2401
from table columns). In the case of integer output values the floating
2402
point scaled value is truncated to an integer (not rounded to the
2403
nearest integer). The ftpscl and fttscl subroutines may be used to
2404
override the scaling parameters defined in the header (e.g., to turn
2405
off the scaling so that the program can read the raw unscaled values
2406
from the FITS file).
2407
2408
When writing numerical data to the primary array or to a table
2409
column the data values will generally be automatically inversely scaled
2410
by the value of the BSCALE and BZERO (or TSCALn and TZEROn) header
2411
keyword values if they they exist in the header. These keywords must
2412
have been written to the header before any data is written for them to
2413
have any effect. Otherwise, one may use the ftpscl and fttscl
2414
subroutines to define or override the scaling keywords in the header
2415
(e.g., to turn off the scaling so that the program can write the raw
2416
unscaled values into the FITS file). If scaling is performed, the
2417
inverse scaled output value that is written into the FITS file will
2418
have
2419
-
2420
FITS value = ((input value) - BZERO) / BSCALE
2421
-
2422
(a corresponding formula using TSCALn and TZEROn is used when
2423
writing to table columns). Rounding to the nearest integer, rather
2424
than truncation, is performed when writing integer datatypes to the
2425
FITS file.
2426
2427
**H. Error Status Values and the Error Message Stack
2428
2429
The last parameter in nearly every FITSIO subroutine is the error
2430
status value which is both an input and an output parameter. A
2431
returned positive value for this parameter indicates an error was
2432
detected. A listing of all the FITSIO status code values is given at
2433
the end of this document.
2434
2435
The FITSIO library uses an `inherited status' convention for the status
2436
parameter which means that if a subroutine is called with a positive
2437
input value of the status parameter, then the subroutine will exit
2438
immediately without changing the value of the status parameter. Thus,
2439
if one passes the status value returned from each FITSIO routine as
2440
input to the next FITSIO subroutine, then whenever an error is detected
2441
all further FITSIO processing will cease. This convention can simplify
2442
the error checking in application programs because it is not necessary
2443
to check the value of the status parameter after every single FITSIO
2444
subroutine call. If a program contains a sequence of several FITSIO
2445
calls, one can just check the status value after the last call. Since
2446
the returned status values are generally distinctive, it should be
2447
possible to determine which subroutine originally returned the error
2448
status.
2449
2450
FITSIO also maintains an internal stack of error messages (80-character
2451
maximum length) which in many cases provide a more detailed explanation
2452
of the cause of the error than is provided by the error status number
2453
alone. It is recommended that the error message stack be printed out
2454
whenever a program detects a FITSIO error. To do this, call the FTGMSG
2455
routine repeatedly to get the successive messages on the stack. When the
2456
stack is empty FTGMSG will return a blank string. Note that this is a
2457
`First In -- First Out' stack, so the oldest error message is returned
2458
first by ftgmsg.
2459
2460
**I. Variable-Length Array Facility in Binary Tables
2461
2462
FITSIO provides easy-to-use support for reading and writing data in
2463
variable length fields of a binary table. The variable length columns
2464
have TFORMn keyword values of the form `1Pt(len)' where `t' is the
2465
datatype code (e.g., I, J, E, D, etc.) and `len' is an integer
2466
specifying the maximum length of the vector in the table. If the value
2467
of `len' is not specified when the table is created (e.g., if the TFORM
2468
keyword value is simply specified as '1PE' instead of '1PE(400) ), then
2469
FITSIO will automatically scan the table when it is closed to
2470
determine the maximum length of the vector and will append this value
2471
to the TFORMn value.
2472
2473
The same routines which read and write data in an ordinary fixed length
2474
binary table extension are also used for variable length fields,
2475
however, the subroutine parameters take on a slightly different
2476
interpretation as described below.
2477
2478
All the data in a variable length field is written into an area called
2479
the `heap' which follows the main fixed-length FITS binary table. The
2480
size of the heap, in bytes, is specified with the PCOUNT keyword in the
2481
FITS header. When creating a new binary table, the initial value of
2482
PCOUNT should usually be set to zero. FITSIO will recompute the size
2483
of the heap as the data is written and will automatically update the
2484
PCOUNT keyword value when the table is closed. When writing variable
2485
length data to a table, CFITSIO will automatically extend the size
2486
of the heap area if necessary, so that any following HDUs do not
2487
get overwritten.
2488
2489
By default the heap data area starts immediately after the last row of
2490
the fixed-length table. This default starting location may be
2491
overridden by the THEAP keyword, but this is not recommended.
2492
If addtional rows of data are added to the table, CFITSIO will
2493
automatically shift the the heap down to make room for the new
2494
rows, but it is obviously be more efficient to initially
2495
create the table with the necessary number of blank rows, so that
2496
the heap does not needed to be constantly moved.
2497
2498
When writing to a variable length field, the entire array of values for
2499
a given row of the table must be written with a single call to FTPCLx.
2500
The total length of the array is calculated from (NELEM+FELEM-1). One
2501
cannot append more elements to an existing field at a later time; any
2502
attempt to do so will simply overwrite all the data which was previously
2503
written. Note also that the new data will be written to a new area of
2504
the heap and the heap space used by the previous write cannot be
2505
reclaimed. For this reason it is advised that each row of a variable
2506
length field only be written once. An exception to this general rule
2507
occurs when setting elements of an array as undefined. One must first
2508
write a dummy value into the array with FTPCLx, and then call FTPCLU to
2509
flag the desired elements as undefined. (Do not use the FTPCNx family
2510
of routines with variable length fields). Note that the rows of a table,
2511
whether fixed or variable length, do not have to be written
2512
consecutively and may be written in any order.
2513
2514
When writing to a variable length ASCII character field (e.g., TFORM =
2515
'1PA') only a single character string written. FTPCLS writes the whole
2516
length of the input string (minus any trailing blank characters), thus
2517
the NELEM and FELEM parameters are ignored. If the input string is
2518
completely blank then FITSIO will write one blank character to the FITS
2519
file. Similarly, FTGCVS and FTGCFS read the entire string (truncated
2520
to the width of the character string argument in the subroutine call)
2521
and also ignore the NELEM and FELEM parameters.
2522
2523
The FTPDES subroutine is useful in situations where multiple rows of a
2524
variable length column have the identical array of values. One can
2525
simply write the array once for the first row, and then use FTPDES to
2526
write the same descriptor values into the other rows (use the FTGDES
2527
routine to read the first descriptor value); all the rows will then
2528
point to the same storage location thus saving disk space.
2529
2530
When reading from a variable length array field one can only read as
2531
many elements as actually exist in that row of the table; reading does
2532
not automatically continue with the next row of the table as occurs
2533
when reading an ordinary fixed length table field. Attempts to read
2534
more than this will cause an error status to be returned. One can
2535
determine the number of elements in each row of a variable column with
2536
the FTGDES subroutine.
2537
2538
**I. Support for IEEE Special Values
2539
2540
The ANSI/IEEE-754 floating-point number standard defines certain
2541
special values that are used to represent such quantities as
2542
Not-a-Number (NaN), denormalized, underflow, overflow, and infinity.
2543
(See the Appendix in the NOST FITS standard or the NOST FITS User's
2544
Guide for a list of these values). The FITSIO subroutines that read
2545
floating point data in FITS files recognize these IEEE special values
2546
and by default interpret the overflow and infinity values as being
2547
equivalent to a NaN, and convert the underflow and denormalized values
2548
into zeros. In some cases programmers may want access to the raw IEEE
2549
values, without any modification by FITSIO. This can be done by
2550
calling the FTGPVx or FTGCVx routines while specifying 0.0 as the value
2551
of the NULLVAL parameter. This will force FITSIO to simply pass the
2552
IEEE values through to the application program, without any
2553
modification. This does not work for double precision values on
2554
VAX/VMS machines, however, where there is no easy way to bypass the
2555
default interpretation of the IEEE special values.
2556
2557
**J. When the Final Size of the FITS HDU is Unknown
2558
2559
It is not required to know the total size of a FITS data array or table
2560
before beginning to write the data to the FITS file. In the case of
2561
the primary array or an image extension, one should initially create
2562
the array with the size of the highest dimension (largest NAXISn
2563
keyword) set to a dummy value, such as 1. Then after all the data have
2564
been written and the true dimensions are known, then the NAXISn value
2565
should be updated using the fits\_ update\_key routine before moving to
2566
another extension or closing the FITS file.
2567
2568
When writing to FITS tables, CFITSIO automatically keeps track of the
2569
highest row number that is written to, and will increase the size of
2570
the table if necessary. CFITSIO will also automatically insert space
2571
in the FITS file if necessary, to ensure that the data 'heap', if it
2572
exists, and/or any additional HDUs that follow the table do not get
2573
overwritten as new rows are written to the table.
2574
2575
As a general rule it is best to specify the initial number of rows = 0
2576
when the table is created, then let CFITSIO keep track of the number of
2577
rows that are actually written. The application program should not
2578
manually update the number of rows in the table (as given by the NAXIS2
2579
keyword) since CFITSIO does this automatically. If a table is
2580
initially created with more than zero rows, then this will ususally be
2581
considered as the minimum size of the table, even if fewer rows are
2582
actually written to the table. Thus, if a table is initially created
2583
with NAXIS2 = 20, and CFITSIO only writes 10 rows of data before
2584
closing the table, then NAXIS2 will remain equal to 20. If however, 30
2585
rows of data are written to this table, then NAXIS2 will be increased
2586
from 20 to 30. The one exception to this automatic updating of the
2587
NAXIS2 keyword is if the application program directly modifies the
2588
value of NAXIS2 (up or down) itself just before closing the table. In this
2589
case, CFITSIO does not update NAXIS2 again, since it assumes that the
2590
application program must have had a good reason for changing the value
2591
directly. This is not recommended, however, and is only provided for
2592
backward compatibility with software that initially creates a table
2593
with a large number of rows, than decreases the NAXIS2 value to the
2594
actual smaller value just before closing the table.
2595
2596
**K. Local FITS Conventions supported by FITSIO
2597
2598
CFITSIO supports several local FITS conventions which are not
2599
defined in the official NOST FITS standard and which are not
2600
necessarily recognized or supported by other FITS software packages.
2601
Programmers should be cautious about using these features, especially
2602
if the FITS files that are produced are expected to be processed by
2603
other software systems which do not use the CFITSIO interface.
2604
2605
***1. Support for Long String Keyword Values.
2606
2607
The length of a standard FITS string keyword is limited to 68
2608
characters because it must fit entirely within a single FITS header
2609
keyword record. In some instances it is necessary to encode strings
2610
longer than this limit, so FITSIO supports a local convention in which
2611
the string value is continued over multiple keywords. This
2612
continuation convention uses an ampersand character at the end of each
2613
substring to indicate that it is continued on the next keyword, and the
2614
continuation keywords all have the name CONTINUE without an equal sign
2615
in column 9. The string value may be continued in this way over as many
2616
additional CONTINUE keywords as is required. The following lines
2617
illustrate this continuation convention which is used in the value of
2618
the STRKEY keyword:
2619
-
2620
LONGSTRN= 'OGIP 1.0' / The OGIP Long String Convention may be used.
2621
STRKEY = 'This is a very long string keyword&' / Optional Comment
2622
CONTINUE ' value that is continued over 3 keywords in the & '
2623
CONTINUE 'FITS header.' / This is another optional comment.
2624
-
2625
It is recommended that the LONGSTRN keyword, as shown
2626
here, always be included in any HDU that uses this longstring
2627
convention. A subroutine called FTPLSW
2628
has been provided in CFITSIO to write this keyword if it does not
2629
already exist.
2630
2631
This long string convention is supported by the following FITSIO
2632
subroutines that deal with string-valued keywords:
2633
-
2634
ftgkys - read a string keyword
2635
ftpkls - write (append) a string keyword
2636
ftikls - insert a string keyword
2637
ftmkls - modify the value of an existing string keyword
2638
ftukls - update an existing keyword, or write a new keyword
2639
ftdkey - delete a keyword
2640
-
2641
These routines will transparently read, write, or delete a long string
2642
value in the FITS file, so programmers in general do not have to be
2643
concerned about the details of the convention that is used to encode
2644
the long string in the FITS header. When reading a long string, one
2645
must ensure that the character string parameter used in these
2646
subroutine calls has been declared long enough to hold the entire
2647
string, otherwise the returned string value will be truncated.
2648
2649
Note that the more commonly used FITSIO subroutine to write string
2650
valued keywords (FTPKYS) does NOT support this long string convention
2651
and only supports strings up to 68 characters in length. This has been
2652
done deliberately to prevent programs from inadvertently writing
2653
keywords using this non-standard convention without the explicit intent
2654
of the programmer or user. The FTPKLS subroutine must be called
2655
instead to write long strings. This routine can also be used to write
2656
ordinary string values less than 68 characters in length.
2657
2658
***2. Arrays of Fixed-Length Strings in Binary Tables
2659
2660
The definition of the FITS binary table extension format does not
2661
provide a simple way to specify that a character column contains an
2662
array of fixed-length strings. To support this feature, FITSIO uses a
2663
local convention for the format of the TFORMn keyword value of the form
2664
'rAw' where 'r' is an integer specifying the total width in characters
2665
of the column, and 'w' is an integer specifying the (fixed) length of
2666
an individual unit string within the vector. For example, TFORM1 =
2667
'120A10' would indicate that the binary table column is 120 characters
2668
wide and consists of 12 10-character length strings. This convention
2669
is recognized by the FITSIO subroutines that read or write strings in
2670
binary tables. The Binary Table definition document specifies that
2671
other optional characters may follow the datatype code in the TFORM
2672
keyword, so this local convention is in compliance with the
2673
FITS standard, although other FITS readers are not required to
2674
recognize this convention.
2675
2676
The Binary Table definition document that was approved by the IAU in
2677
1994 contains an appendix describing an alternate convention for
2678
specifying arrays of fixed or variable length strings in a binary table
2679
character column (with the form 'rA:SSTRw/nnn)'. This appendix was not
2680
officially voted on by the IAU and hence is still provisional. FITSIO
2681
does not currently support this proposal.
2682
2683
***3. Keyword Units Strings
2684
2685
One deficiency of the current FITS Standard is that it does not define
2686
a specific convention for recording the physical units of a keyword
2687
value. The TUNITn keyword can be used to specify the physical units of
2688
the values in a table column, but there is no analogous convention for
2689
keyword values. The comment field of the keyword is often used for
2690
this purpose, but the units are usually not specified in a well defined
2691
format that FITS readers can easily recognize and extract.
2692
2693
To solve this deficiency, FITSIO uses a local convention in which the
2694
keyword units are enclosed in square brackets as the first token in the
2695
keyword comment field; more specifically, the opening square bracket
2696
immediately follows the slash '/' comment field delimiter and a single
2697
space character. The following examples illustrate keywords that use
2698
this convention:
2699
2700
-
2701
EXPOSURE= 1800.0 / [s] elapsed exposure time
2702
V_HELIO = 16.23 / [km s**(-1)] heliocentric velocity
2703
LAMBDA = 5400. / [angstrom] central wavelength
2704
FLUX = 4.9033487787637465E-30 / [J/cm**2/s] average flux
2705
-
2706
2707
In general, the units named in the IAU(1988) Style Guide are
2708
recommended, with the main exception that the preferred unit for angle
2709
is 'deg' for degrees.
2710
2711
The FTPUNT and FTGUNT subroutines in FITSIO write and read,
2712
respectively, the keyword unit strings in an existing keyword.
2713
2714
***4. HIERARCH Convention for Extended Keyword Names
2715
2716
CFITSIO supports the HIERARCH keyword convention which allows keyword
2717
names that are longer then 8 characters and may contain the full range
2718
of printable ASCII text characters. This convention
2719
was developed at the European Southern Observatory (ESO) to support
2720
hierarchical FITS keyword such as:
2721
-
2722
HIERARCH ESO INS FOCU POS = -0.00002500 / Focus position
2723
-
2724
Basically, this convention uses the FITS keyword 'HIERARCH' to indicate
2725
that this convention is being used, then the actual keyword name
2726
({\tt'ESO INS FOCU POS'} in this example) begins in column 10 and can
2727
contain any printable ASCII text characters, including spaces. The
2728
equals sign marks the end of the keyword name and is followed by the
2729
usual value and comment fields just as in standard FITS keywords.
2730
Further details of this convention are described at
2731
http://arcdev.hq.eso.org/dicb/dicd/dic-1-1.4.html (search for
2732
HIERARCH).
2733
2734
This convention allows a much broader range of keyword names
2735
than is allowed by the FITS Standard. Here are more examples
2736
of such keywords:
2737
-
2738
HIERARCH LongKeyword = 47.5 / Keyword has > 8 characters, and mixed case
2739
HIERARCH XTE$TEMP = 98.6 / Keyword contains the '$' character
2740
HIERARCH Earth is a star = F / Keyword contains embedded spaces
2741
-
2742
CFITSIO will transparently read and write these keywords, so application
2743
programs do not in general need to know anything about the specific
2744
implementation details of the HIERARCH convention. In particular,
2745
application programs do not need to specify the `HIERARCH' part of the
2746
keyword name when reading or writing keywords (although it
2747
may be included if desired). When writing a keyword, CFITSIO first
2748
checks to see if the keyword name is legal as a standard FITS keyword
2749
(no more than 8 characters long and containing only letters, digits, or
2750
a minus sign or underscore). If so it writes it as a standard FITS
2751
keyword, otherwise it uses the hierarch convention to write the
2752
keyword. The maximum keyword name length is 67 characters, which
2753
leaves only 1 space for the value field. A more practical limit is
2754
about 40 characters, which leaves enough room for most keyword values.
2755
CFITSIO returns an error if there is not enough room for both the
2756
keyword name and the keyword value on the 80-character card, except for
2757
string-valued keywords which are simply truncated so that the closing
2758
quote character falls in column 80. In the current implementation,
2759
CFITSIO preserves the case of the letters when writing the keyword
2760
name, but it is case-insensitive when reading or searching for a
2761
keyword. The current implementation allows any ASCII text character
2762
(ASCII 32 to ASCII 126) in the keyword name except for the '='
2763
character. A space is also required on either side of the equal sign.
2764
2765
**L. Optimizing Code for Maximum Processing Speed
2766
2767
CFITSIO has been carefully designed to obtain the highest possible
2768
speed when reading and writing FITS files. In order to achieve the
2769
best performance, however, application programmers must be careful to
2770
call the CFITSIO routines appropriately and in an efficient sequence;
2771
inappropriate usage of CFITSIO routines can greatly slow down the
2772
execution speed of a program.
2773
2774
The maximum possible I/O speed of CFITSIO depends of course on the type
2775
of computer system that it is running on. As a rough guide, the
2776
current generation of workstations can achieve speeds of 2 -- 10 MB/s
2777
when reading or writing FITS images and similar, or slightly slower
2778
speeds with FITS binary tables. Reading of FITS files can occur at
2779
even higher rates (30MB/s or more) if the FITS file is still cached in
2780
system memory following a previous read or write operation on the same
2781
file. To more accurately predict the best performance that is possible
2782
on any particular system, a diagnostic program called ``speed.c'' is
2783
included with the CFITSIO distribution which can be run to
2784
approximately measure the maximum possible speed of writing and reading
2785
a test FITS file.
2786
2787
The following 2 sections provide some background on how CFITSIO
2788
internally manages the data I/O and describes some strategies that may
2789
be used to optimize the processing speed of software that uses
2790
CFITSIO.
2791
2792
***1. Background Information: How CFITSIO Manages Data I/O
2793
2794
Many CFITSIO operations involve transferring only a small number of
2795
bytes to or from the FITS file (e.g, reading a keyword, or writing a
2796
row in a table); it would be very inefficient to physically read or
2797
write such small blocks of data directly in the FITS file on disk,
2798
therefore CFITSIO maintains a set of internal Input--Output (IO)
2799
buffers in RAM memory that each contain one FITS block (2880 bytes) of
2800
data. Whenever CFITSIO needs to access data in the FITS file, it first
2801
transfers the FITS block containing those bytes into one of the IO
2802
buffers in memory. The next time CFITSIO needs to access bytes in the
2803
same block it can then go to the fast IO buffer rather than using a
2804
much slower system disk access routine. The number of available IO
2805
buffers is determined by the NIOBUF parameter (in fitsio2.h) and is
2806
currently set to 25.
2807
2808
Whenever CFITSIO reads or writes data it first checks to see if that
2809
block of the FITS file is already loaded into one of the IO buffers.
2810
If not, and if there is an empty IO buffer available, then it will load
2811
that block into the IO buffer (when reading a FITS file) or will
2812
initialize a new block (when writing to a FITS file). If all the IO
2813
buffers are already full, it must decide which one to reuse (generally
2814
the one that has been accessed least recently), and flush the contents
2815
back to disk if it has been modified before loading the new block.
2816
2817
The one major exception to the above process occurs whenever a large
2818
contiguous set of bytes are accessed, as might occur when reading or
2819
writing a FITS image. In this case CFITSIO bypasses the internal IO
2820
buffers and simply reads or writes the desired bytes directly in the
2821
disk file with a single call to a low-level file read or write
2822
routine. The minimum threshold for the number of bytes to read or
2823
write this way is set by the MINDIRECT parameter and is currently set
2824
to 3 FITS blocks = 8640 bytes. This is the most efficient way to read
2825
or write large chunks of data and can achieve IO transfer rates of
2826
5 -- 10MB/s or greater. Note that this fast direct IO process is not
2827
applicable when accessing columns of data in a FITS table because the
2828
bytes are generally not contiguous since they are interleaved by the
2829
other columns of data in the table. This explains why the speed for
2830
accessing FITS tables is generally slower than accessing
2831
FITS images.
2832
2833
Given this background information, the general strategy for efficiently
2834
accessing FITS files should now be apparent: when dealing with FITS
2835
images, read or write large chunks of data at a time so that the direct
2836
IO mechanism will be invoked; when accessing FITS headers or FITS
2837
tables, on the other hand, once a particular FITS block has been
2838
loading into one of the IO buffers, try to access all the needed
2839
information in that block before it gets flushed out of the IO buffer.
2840
It is important to avoid the situation where the same FITS block is
2841
being read then flushed from a IO buffer multiple times.
2842
2843
The following section gives more specific suggestions for optimizing
2844
the use of CFITSIO.
2845
2846
1. When dealing with a FITS primary array or IMAGE extension, it is
2847
more efficient to read or write large chunks of the image at a time
2848
(at least 3 FITS blocks = 8640 bytes) so that the direct IO mechanism
2849
will be used as described in the previous section. Smaller chunks of
2850
data are read or written via the IO buffers, which is somewhat less
2851
efficient because of the extra copy operation and additional
2852
bookkeeping steps that are required. In principle it is more efficient
2853
to read or write as big an array of image pixels at one time as
2854
possible, however, if the array becomes so large that the operating
2855
system cannot store it all in RAM, then the performance may be degraded
2856
because of the increased swapping of virtual memory to disk.
2857
2858
2. When dealing with FITS tables, the most important efficiency factor
2859
in the software design is to read or write the data in the FITS file in
2860
a single pass through the file. An example of poor program design
2861
would be to read a large, 3-column table by sequentially reading the
2862
entire first column, then going back to read the 2nd column, and
2863
finally the 3rd column; this obviously requires 3 passes through the
2864
file which could triple the execution time of an I/O limited program.
2865
For small tables this is not important, but when reading multi-megabyte
2866
sized tables these inefficiencies can become significant. The more
2867
efficient procedure in this case is to read or write only as many rows
2868
of the table as will fit into the available internal I/O buffers, then
2869
access all the necessary columns of data within that range of rows.
2870
Then after the program is completely finished with the data in those
2871
rows it can move on to the next range of rows that will fit in the
2872
buffers, continuing in this way until the entire file has been
2873
processed. By using this procedure of accessing all the columns of a
2874
table in parallel rather than sequentially, each block of the FITS file
2875
will only be read or written once.
2876
2877
The optimal number of rows to read or write at one time in a given
2878
table depends on the width of the table row, on the number of I/O
2879
buffers that have been allocated in FITSIO, and also on the number of
2880
other FITS files that are open at the same time (since one I/O buffer
2881
is always reserved for each open FITS file). Fortunately, a FITSIO
2882
routine is available that will return the optimal number of rows for a
2883
given table: call ftgrsz(unit, nrows, status). It is not critical to
2884
use exactly the value of nrows returned by this routine, as long as one
2885
does not exceed it. Using a very small value however can also lead to
2886
poor preformance because of the overhead from the larger number of
2887
subroutine calls.
2888
2889
The optimal number of rows returned by ftgrsz is valid only as long as
2890
the application program is only reading or writing data in the
2891
specified table. Any other calls to access data in the table header or
2892
in any other FITS file would cause additional blocks of data to be
2893
loaded into the I/O buffers displacing data from the original table,
2894
and should be avoided during the critical period while the table is
2895
being read or written.
2896
2897
Occasionally it is necessary to simultaneously access more than one
2898
FITS table, for example when transfering values from an input table to
2899
an output table. In cases like this, one should call ftgrsz to get the
2900
optimal number of rows for each table separately, than reduce the
2901
number of rows proportionally. For example, if the optimal number of
2902
rows in the input table is 3600 and is 1400 in the output table, then
2903
these values should be cut in half to 1800 and 700, respectively, if
2904
both tables are going to be accessed at the same time.
2905
2906
3. Use binary table extensions rather than ASCII table
2907
extensions for better efficiency when dealing with tabular data. The
2908
I/O to ASCII tables is slower because of the overhead in formatting or
2909
parsing the ASCII data fields, and because ASCII tables are about twice
2910
as large as binary tables with the same information content.
2911
2912
4. Design software so that it reads the FITS header keywords in the
2913
same order in which they occur in the file. When reading keywords,
2914
FITSIO searches forward starting from the position of the last keyword
2915
that was read. If it reaches the end of the header without finding the
2916
keyword, it then goes back to the start of the header and continues the
2917
search down to the position where it started. In practice, as long as
2918
the entire FITS header can fit at one time in the available internal I/O
2919
buffers, then the header keyword access will be very fast and it makes
2920
little difference which order they are accessed.
2921
2922
5. Avoid the use of scaling (by using the BSCALE and BZERO or TSCAL and
2923
TZERO keywords) in FITS files since the scaling operations add to the
2924
processing time needed to read or write the data. In some cases it may
2925
be more efficient to temporarily turn off the scaling (using ftpscl or
2926
fttscl) and then read or write the raw unscaled values in the FITS
2927
file.
2928
2929
6. Avoid using the 'implicit datatype conversion' capability in
2930
FITSIO. For instance, when reading a FITS image with BITPIX = -32
2931
(32-bit floating point pixels), read the data into a single precision
2932
floating point data array in the program. Forcing FITSIO to convert
2933
the data to a different datatype can significantly slow the program.
2934
2935
7. Where feasible, design FITS binary tables using vector column
2936
elements so that the data are written as a contiguous set of bytes,
2937
rather than as single elements in multiple rows. For example, it is
2938
faster to access the data in a table that contains a single row
2939
and 2 columns with TFORM keywords equal to '10000E' and '10000J', than
2940
it is to access the same amount of data in a table with 10000 rows
2941
which has columns with the TFORM keywords equal to '1E' and '1J'. In
2942
the former case the 10000 floating point values in the first column are
2943
all written in a contiguous block of the file which can be read or
2944
written quickly, whereas in the second case each floating point value
2945
in the first column is interleaved with the integer value in the second
2946
column of the same row so CFITSIO has to explicitly move to the
2947
position of each element to be read or written.
2948
2949
8. Avoid the use of variable length vector columns in binary tables,
2950
since any reading or writing of these data requires that CFITSIO first
2951
look up or compute the starting address of each row of data in the
2952
heap.
2953
2954
9. When copying data from one FITS table to another, it is faster to
2955
transfer the raw bytes instead of reading then writing each column of
2956
the table. The FITSIO subroutines FTGTBS and FTPTBS (for ASCII
2957
tables), and FTGTBB and FTPTBB (for binary tables) will perform
2958
low-level reads or writes of any contiguous range of bytes in a table
2959
extension. These routines can be used to read or write a whole row (or
2960
multiple rows) of a table with a single subroutine call. These
2961
routines are fast because they bypass all the usual data scaling, error
2962
checking and machine dependent data conversion that is normally done by
2963
FITSIO, and they allow the program to write the data to the output file
2964
in exactly the same byte order. For these same reasons, use of these
2965
routines can be somewhat risky because no validation or machine
2966
dependent conversion is performed by these routines. In general these
2967
routines are only recommended for optimizing critical pieces of code
2968
and should only be used by programmers who thoroughly understand the
2969
internal byte structure of the FITS tables they are reading or
2970
writing.
2971
2972
10. Another strategy for improving the speed of writing a FITS table,
2973
similar to the previous one, is to directly construct the entire byte
2974
stream for a whole table row (or multiple rows) within the application
2975
program and then write it to the FITS file with
2976
ftptbb. This avoids all the overhead normally present
2977
in the column-oriented CFITSIO write routines. This technique should
2978
only be used for critical applications, because it makes the code more
2979
difficult to understand and maintain, and it makes the code more system
2980
dependent (e.g., do the bytes need to be swapped before writing to the
2981
FITS file?).
2982
2983
11. Finally, external factors such as the type of magnetic disk
2984
controller (SCSI or IDE), the size of the disk cache, the average seek
2985
speed of the disk, the amount of disk fragmentation, and the amount of
2986
RAM available on the system can all have a significant impact on
2987
overall I/O efficiency. For critical applications, a system
2988
adminstrator should review the proposed system hardware to identify any
2989
potential I/O bottlenecks.
2990
2991
2992
*VI. The CFITSIO Iterator Function
2993
2994
The fits\_iterate\_data function in CFITSIO provides a unique method of
2995
executing an arbitrary user-supplied `work' function that operates on
2996
rows of data in FITS tables or on pixels in FITS images. Rather than
2997
explicitly reading and writing the FITS images or columns of data, one
2998
instead calls the CFITSIO iterator routine, passing to it the name of
2999
the user's work function that is to be executed along with a list of
3000
all the table columns or image arrays that are to be passed to the work
3001
function. The CFITSIO iterator function then does all the work of
3002
allocating memory for the arrays, reading the input data from the FITS
3003
file, passing them to the work function, and then writing any output
3004
data back to the FITS file after the work function exits. Because
3005
it is often more efficient to process only a subset of the total table
3006
rows at one time, the iterator function can determine the optimum
3007
amount of data to pass in each iteration and repeatly call the work
3008
function until the entire table been processed.
3009
3010
For many applications this single CFITSIO iterator function can
3011
effectively replace all the other CFITSIO routines for reading or
3012
writing data in FITS images or tables. Using the iterator has several
3013
important advantages over the traditional method of reading and writing
3014
FITS data files:
3015
3016
\begin{itemize}
3017
\item
3018
It cleanly separates the data I/O from the routine that operates on
3019
the data. This leads to a more modular and `object oriented'
3020
programming style.
3021
3022
\item
3023
It simplifies the application program by eliminating the need to allocate
3024
memory for the data arrays and eliminates most of the calls to the CFITSIO
3025
routines that explicitly read and write the data.
3026
3027
\item
3028
It ensures that the data are processed as efficiently as possible.
3029
This is especially important when processing tabular data since
3030
the iterator function will calculate the most efficient number
3031
of rows in the table to be passed at one time to the user's work
3032
function on each iteration.
3033
3034
\item
3035
Makes it possible for larger projects to develop a library of work
3036
functions that all have a uniform calling sequence and are all
3037
independent of the details of the FITS file format.
3038
3039
\end{itemize}
3040
3041
There are basically 2 steps in using the CFITSIO iterator function.
3042
The first step is to design the work function itself which must have a
3043
prescribed set of input parameters. One of these parameters is a
3044
structure containing pointers to the arrays of data; the work function
3045
can perform any desired operations on these arrays and does not need to
3046
worry about how the input data were read from the file or how the
3047
output data get written back to the file.
3048
3049
The second step is to design the driver routine that opens all the
3050
necessary FITS files and initializes the input parameters to the
3051
iterator function. The driver program calls the CFITSIO iterator
3052
function which then reads the data and passes it to the user's work
3053
function.
3054
3055
Further details on using the iterator function can be found in the
3056
companion CFITSIO User's Guide, and in the iter\_a.f, iter\_b.f and
3057
iter\_c.f example programs.
3058
3059
3060
3061
*VII. Basic Interface Routines
3062
3063
This section defines a basic set of subroutines that can be
3064
used to perform the most common types of read and write operations
3065
on FITS files. New users should start with these subroutines and
3066
then, as needed, explore the more advance routines described in
3067
the following chapter to perform more complex or specialized operations.
3068
3069
A right arrow symbol ($>$) is used to separate the input parameters from
3070
the output parameters in the definition of each routine. This symbol
3071
is not actually part of the calling sequence. Note that
3072
the status parameter is both an input and an output parameter
3073
and must be initialized = 0 prior to calling the FITSIO subroutines.
3074
3075
Refer to Chapter 9 for the definition of all the parameters
3076
used by these interface routines.
3077
3078
**A. FITSIO Error Status Routines \label{FTVERS}
3079
3080
>1 Return the current version number of the fitsio library.
3081
The version number will be incremented with each new
3082
> release of CFITSIO.
3083
-
3084
FTVERS( > version)
3085
-
3086
>2 Return the descriptive text string corresponding to a FITSIO error
3087
status code. The 30-character length string contains a brief
3088
> description of the cause of the error.
3089
-
3090
FTGERR(status, > errtext)
3091
-
3092
>3 Return the top (oldest) 80-character error message from the
3093
internal FITSIO stack of error messages and shift any remaining
3094
messages on the stack up one level. Any FITSIO error will
3095
generate one or more messages on the stack. Call this routine
3096
repeatedly to get each message in sequence. The error stack is empty
3097
> when a blank string is returned.
3098
-
3099
FTGMSG( > errmsg)
3100
-
3101
>4 Print out the error message corresponding to the input status
3102
value and all the error messages on the FITSIO stack to the specified
3103
file stream (stream can be either the string 'STDOUT' or 'STDERR').
3104
> If the input status value = 0 then this routine does nothing.
3105
-
3106
FTRPRT (stream, > status)
3107
-
3108
>5 Write an 80-character message to the FITSIO error stack. Application
3109
programs should not normally write to the stack, but there may be
3110
> some situations where this is desirable.
3111
-
3112
FTPMSG(errmsg)
3113
-
3114
>6 Clear the entire error message stack. This routine is useful
3115
to clear any error message that may have been generated by
3116
a non-fatal FITSIO error (such as failing to find an optional
3117
> header keyword). This routine is called without any arguments.
3118
-
3119
FTCMSG
3120
-
3121
3122
**B. File I/O Routines
3123
3124
>1 Open an existing FITS file with readonly or readwrite access.
3125
This routine always opens the primary array (the first HDU) of
3126
the file, and does not move to a following extension, if one was
3127
specified as part of the filename. Use the FTNOPN routine to
3128
automatically move to the extension. This routine will also
3129
open IRAF images (.imh format files) and raw binary data arrays
3130
with READONLY access by first converting them on the fly into
3131
virtual FITS images. See the `Extended File Name Syntax' chapter
3132
> for more details.
3133
-
3134
FTOPEN(unit,filename,rwmode, > blocksize,status)
3135
-
3136
>2 Open an existing FITS file with readonly or readwrite access
3137
and move to a following extension, if one was specified as
3138
part of the filename. (e.g., 'filename.fits+2' or
3139
'filename.fits[2]' will move to the 3rd HDU in the file).
3140
Note that this routine differs from FTOPEN in that it does not
3141
> have the redundant blocksize argument.
3142
-
3143
FTNOPN(unit,filename,rwmode, > status)
3144
-
3145
>3 Open and initialize a new empty FITS file. A template file may also be
3146
> specified to define the structure of the new file (see secion 4.2.4).
3147
-
3148
FTINIT(unit,filename,blocksize, > status)
3149
-
3150
>>4 Close a FITS file previously opened with ftopen or ftinit
3151
-
3152
FTCLOS(unit, > status)
3153
-
3154
>5 Move to a specified (absolute) HDU in the FITS file (nhdu = 1 for the
3155
> FITS primary array)
3156
-
3157
FTMAHD(unit,nhdu, > hdutype,status)
3158
-
3159
>6 Create a primary array (if none already exists), or insert a
3160
new IMAGE extension immediately following the CHDU, or
3161
insert a new Primary Array at the beginning of the file. Any
3162
following extensions in the file will be shifted down to make room
3163
for the new extension. If the CHDU is the last HDU in the file
3164
then the new image extension will simply be appended to the end of
3165
the file. One can force a new primary array to be inserted at the
3166
beginning of the FITS file by setting status = -9 prior
3167
to calling the routine. In this case the old primary array will be
3168
converted to an IMAGE extension. The new extension (or primary
3169
> array) will become the CHDU.
3170
-
3171
FTIIMG(unit,bitpix,naxis,naxes, > status)
3172
-
3173
>7 Insert a new ASCII TABLE extension immediately following the CHDU.
3174
Any following extensions will be shifted down to make room for
3175
the new extension. If there are no other following extensions
3176
then the new table extension will simply be appended to the
3177
> end of the file. The new extension will become the CHDU.
3178
-
3179
FTITAB(unit,rowlen,nrows,tfields,ttype,tbcol,tform,tunit,extname, >
3180
status)
3181
-
3182
>8 Insert a new binary table extension immediately following the CHDU.
3183
Any following extensions will be shifted down to make room for
3184
the new extension. If there are no other following extensions
3185
then the new bintable extension will simply be appended to the
3186
> end of the file. The new extension will become the CHDU.
3187
-
3188
FTIBIN(unit,nrows,tfields,ttype,tform,tunit,extname,varidat > status)
3189
-
3190
**C. Keyword I/O Routines
3191
3192
>>1 Put (append) an 80-character record into the CHU.
3193
-
3194
FTPREC(unit,card, > status)
3195
-
3196
>2 Put (append) a new keyword of the appropriate datatype into the CHU.
3197
The E and D versions of this routine have the added feature that
3198
if the 'decimals' parameter is negative, then the 'G' display
3199
format rather then the 'E' format will be used when constructing
3200
the keyword value, taking the absolute value of 'decimals' for the
3201
precision. This will suppress trailing zeros, and will use a
3202
fixed format rather than an exponential format,
3203
> depending on the magnitude of the value.
3204
-
3205
FTPKY[JLS](unit,keyword,keyval,comment, > status)
3206
FTPKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
3207
-
3208
>3 Get the nth 80-character header record from the CHU. The first keyword
3209
in the header is at key\_no = 1; if key\_no = 0 then this subroutine
3210
simple moves the internal pointer to the beginning of the header
3211
so that subsequent keyword operations will start at the top of
3212
> the header; it also returns a blank card value in this case.
3213
-
3214
FTGREC(unit,key_no, > card,status)
3215
-
3216
>4 Get a keyword value (with the appropriate datatype) and comment from
3217
> the CHU
3218
-
3219
FTGKY[EDJLS](unit,keyword, > keyval,comment,status)
3220
-
3221
>>5 Delete an existing keyword record.
3222
-
3223
FTDKEY(unit,keyword, > status)
3224
-
3225
3226
**D. Data I/O Routines
3227
3228
The following routines read or write data values in the current HDU of
3229
the FITS file. Automatic datatype conversion
3230
will be attempted for numerical datatypes if the specified datatype is
3231
different from the actual datatype of the FITS array or table column.
3232
3233
>>1 Write elements into the primary data array or image extension.
3234
-
3235
FTPPR[BIJED](unit,group,fpixel,nelements,values, > status)
3236
-
3237
>2 Read elements from the primary data array or image extension.
3238
Undefined array elements will be
3239
returned with a value = nullval, unless nullval = 0 in which case no
3240
checks for undefined pixels will be performed. The anyf parameter is
3241
set to true (= .true.) if any of the returned
3242
> elements were undefined.
3243
-
3244
FTGPV[BIJED](unit,group,fpixel,nelements,nullval, > values,anyf,status)
3245
-
3246
>3 Write elements into an ASCII or binary table column. The `felem'
3247
parameter applies only to vector columns in binary tables and is
3248
> ignored when writing to ASCII tables.
3249
-
3250
FTPCL[SLBIJEDCM](unit,colnum,frow,felem,nelements,values, > status)
3251
-
3252
>4 Read elements from an ASCII or binary table column. Undefined
3253
array elements will be returned with a value = nullval, unless nullval = 0
3254
(or = ' ' for ftgcvs) in which case no checking for undefined values will
3255
be performed. The ANYF parameter is set to true if any of the returned
3256
elements are undefined.
3257
3258
Any column, regardless of it's intrinsic datatype, may be read as a
3259
string. It should be noted however that reading a numeric column
3260
as a string is 10 - 100 times slower than reading the same column
3261
as a number due to the large overhead in constructing the formatted
3262
strings. The display format of the returned strings will be
3263
determined by the TDISPn keyword, if it exists, otherwise by the
3264
datatype of the column. The length of the returned strings can be
3265
determined with the ftgcdw routine. The following TDISPn display
3266
formats are currently supported:
3267
-
3268
Iw.m Integer
3269
Ow.m Octal integer
3270
Zw.m Hexadecimal integer
3271
Fw.d Fixed floating point
3272
Ew.d Exponential floating point
3273
Dw.d Exponential floating point
3274
Gw.d General; uses Fw.d if significance not lost, else Ew.d
3275
-
3276
where w is the width in characters of the displayed values, m is the minimum
3277
number of digits displayed, and d is the number of digits to the right of the
3278
> decimal. The .m field is optional.
3279
3280
-
3281
FTGCV[SBIJEDCM](unit,colnum,frow,felem,nelements,nullval, >
3282
values,anyf,status)
3283
-
3284
>5 Get the table column number and full name of the column whose name
3285
matches the input template string. See the `Advanced Interface Routines'
3286
> chapter for a full description of this routine.
3287
-
3288
FTGCNN(unit,casesen,coltemplate, > colname,colnum,status)
3289
-
3290
3291
3292
*VIII Advanced Interface Subroutines
3293
3294
This chapter defines all the available subroutines in the FITSIO user
3295
interface. For completeness, the basic subroutines described in the
3296
previous chapter are also repeated here. A right arrow symbol is used
3297
here to separate the input parameters from the output parameters in the
3298
definition of each subroutine. This symbol is not actually part of the
3299
calling sequence. An alphabetical list and definition of all the
3300
parameters is given at the end of this section. The SPP interface
3301
subroutines have the same arguments but have names that begin with 'fs'
3302
rather than 'ft'.
3303
3304
**A. FITS File Open and Close Subroutines: \label{FTOPEN}
3305
3306
>>1 Open an existing FITS file with readonly or readwrite access
3307
-
3308
FTOPEN(unit,filename,rwmode, > blocksize,status)
3309
-
3310
>2 Open an existing FITS file with readonly or readwrite access
3311
and move to a following extension, if one was specified as
3312
part of the filename. (e.g., 'filename.fits+2' or
3313
'filename.fits[2]' will move to the 3rd HDU in the file).
3314
Note that this routine differs from FTOPEN in that it does not
3315
> have the redundant blocksize argument.
3316
-
3317
FTNOPN(unit,filename,rwmode, > status)
3318
-
3319
>3 Reopen a FITS file that was previously opened with
3320
FTOPEN, FTNOPN, or FTINIT. The newunit number
3321
may then be treated as a separate file, and one may
3322
simultaneously read or write to 2 (or more) different extensions in
3323
the same file. The FTOPEN and FTNOPN routines (above) automatically
3324
detects cases where a previously opened file is being opened again,
3325
and then internally call FTREOPEN, so programs should rarely
3326
> need to explicitly call this routine.
3327
-
3328
FTREOPEN(unit, > newunit, status)
3329
-
3330
>>4 Open and initialize a new empty FITS file
3331
-
3332
FTINIT(unit,filename,blocksize, > status)
3333
-
3334
>5 Create a new FITS file, using a template file to define its
3335
initial size and structure. The template may be another FITS HDU
3336
or an ASCII template file. If the input template file name
3337
is blank, then this routine behaves the same as FTINIT.
3338
The currently supported format of the ASCII template file is described
3339
under the fits\_parse\_template routine (in the general Utilities
3340
section), but this may change slightly later releases of
3341
> CFITSIO.
3342
-
3343
FTTPLT(unit, filename, tplfilename, > status)
3344
-
3345
>6 Flush internal buffers of data to the output FITS file
3346
previously opened with ftopen or ftinit. The routine usually
3347
never needs to be called, but doing so will ensure that
3348
if the program subsequently aborts, then the FITS file will
3349
> have at least been closed properly.
3350
-
3351
FTFLUS(unit, > status)
3352
-
3353
>>7 Close a FITS file previously opened with ftopen or ftinit
3354
-
3355
FTCLOS(unit, > status)
3356
-
3357
>8 Close and DELETE a FITS file previously opened with ftopen or ftinit.
3358
This routine may be useful in cases where a FITS file is created, but
3359
> an error occurs which prevents the complete file from being written.
3360
-
3361
FTDELT(unit, > status)
3362
-
3363
>9 Get the value of an unused I/O unit number which may then be used
3364
as input to FTOPEN or FTINIT. This routine searches for the first
3365
unused unit number in the range from with 99 down to 50. This
3366
routine just keeps an internal list of the allocated unit numbers
3367
and does not physically check that the Fortran unit is available (to be
3368
compatible with the SPP version of FITSIO). Thus users must not
3369
independently allocate any unit numbers in the range 50 - 99
3370
if this routine is also to be used in the same program. This
3371
routine is provided for convenience only, and it is not required
3372
> that the unit numbers used by FITSIO be allocated by this routine.
3373
-
3374
FTGIOU( > iounit, status)
3375
-
3376
>10 Free (deallocate) an I/O unit number which was previously allocated
3377
with FTGIOU. All previously allocated unit numbers may be
3378
> deallocated at once by calling FTFIOU with iounit = -1.
3379
-
3380
FTFIOU(iounit, > status)
3381
-
3382
>11 Parse the input filename and return the HDU number that would be
3383
moved to if the file were opened with FTNOPN. The returned HDU
3384
number begins with 1 for the primary array, so for example, if the
3385
input filename = `myfile.fits[2]' then hdunum = 3 will be returned.
3386
FITSIO does not open the file to check if the extension actually exists
3387
if an extension number is specified. If an extension *name* is included
3388
in the file name specification (e.g. `myfile.fits[EVENTS]' then this
3389
routine will have to open the FITS file and look for the position of
3390
the named extension, then close file again. This is not possible if
3391
the file is being read from the stdin stream, and an error will be
3392
returned in this case. If the filename does not specify an explicit
3393
extension (e.g. 'myfile.fits') then hdunum = -99 will be returned,
3394
which is functionally equivalent to hdunum = 1. This routine is mainly
3395
used for backward compatibility in the ftools software package and is
3396
not recommended for general use. It is generally better and more
3397
efficient to first open the FITS file with FTNOPN, then use FTGHDN to
3398
determine which HDU in the file has been opened, rather than calling
3399
> FTEXTN followed by a call to FTNOPN.
3400
-
3401
FTEXTN(filename, > nhdu, status)
3402
-
3403
>>12 Return the name of the opened FITS file.
3404
-
3405
FTFLNM(unit, > filename, status)
3406
-
3407
>>13 Return the I/O mode of the open FITS file (READONLY = 0, READWRITE = 1).
3408
-
3409
FTFLMD(unit, > iomode, status)
3410
-
3411
>14 Return the file type of the opened FITS file (e.g. 'file://', 'ftp://',
3412
> etc.).
3413
-
3414
FTURLT(unit, > urltype, status)
3415
-
3416
>15 Parse the input filename or URL into its component parts: the file
3417
type (file://, ftp://, http://, etc), the base input file name, the
3418
name of the output file that the input file is to be copied to prior
3419
to opening, the HDU or extension specification, the filtering
3420
specifier, the binning specifier, and the column specifier. Blank
3421
strings will be returned for any components that are not present
3422
>in the input file name.
3423
-
3424
FTIURL(filename, > filetype, infile, outfile, extspec, filter,
3425
binspec, colspec, status)
3426
-
3427
>16 Parse the input file name and return the root file name. The root
3428
name includes the file type if specified, (e.g. 'ftp://' or 'http://')
3429
and the full path name, to the extent that it is specified in the input
3430
filename. It does not enclude the HDU name or number, or any filtering
3431
>specifications.
3432
-
3433
FTRTNM(filename, > rootname, status)
3434
-
3435
3436
**B. HDU-Level Operations \label{FTMAHD}
3437
3438
When a FITS file is first opened or created, the internal buffers in
3439
FITSIO automatically point to the first HDU in the file. The following
3440
routines may be used to move to another HDU in the file. Note that
3441
the HDU numbering convention used in FITSIO denotes the primary array
3442
as the first HDU, the first extension in a FITS file is the second HDU,
3443
and so on.
3444
3445
>1 Move to a specified (absolute) HDU in the FITS file (nhdu = 1 for the
3446
> FITS primary array)
3447
-
3448
FTMAHD(unit,nhdu, > hdutype,status)
3449
-
3450
>>2 Move to a new (existing) HDU forward or backwards relative to the CHDU
3451
-
3452
FTMRHD(unit,nmove, > hdutype,status)
3453
-
3454
>3 Move to the (first) HDU which has the specified extension type and
3455
EXTNAME (or HDUNAME) and EXTVER keyword values. The hdutype parameter
3456
may have
3457
a value of IMAGE\_HDU, ASCII\_TBL, BINARY\_TBL, or ANY\_HDU where
3458
ANY\_HDU means that only the extname and extver values will be
3459
used to locate the correct extension. If the input value of
3460
extver is 0 then the EXTVER keyword is ignored and the first HDU
3461
with a matching EXTNAME (or HDUNAME) keyword will be found. If no
3462
matching HDU is found in the file then the current HDU will remain
3463
unchanged
3464
> and a status = BAD\_HDU\_NUM (301) will be returned.
3465
-
3466
FTMNHD(unit, hdutype, extname, extver, > status)
3467
-
3468
>>4 Get the number of the current HDU in the FITS file (primary array = 1)
3469
-
3470
FTGHDN(unit, > nhdu)
3471
-
3472
>5 Return the type of the current HDU in the FITS file. The possible
3473
> values for hdutype are IMAGE\_HDU (0), ASCII\_TBL (1), or BINARY\_TBL (2).
3474
-
3475
FTGHDT(unit, > hdutype, status)
3476
-
3477
>6 Return the total number of HDUs in the FITS file.
3478
> The CHDU remains unchanged.
3479
-
3480
FTTHDU(unit, > hdunum, status)
3481
-
3482
>7 Create (append) a new empty HDU following the last extension that
3483
has been previously accessed by the program. This will overwrite
3484
any extensions in an existing FITS file if the program has not already
3485
moved to that (or a later) extension using the FTMAHD or FTMRHD routines.
3486
For example, if an existing FITS file contains a primary array and 5
3487
extensions and a program (1) opens the FITS file, (2) moves to
3488
extension 4, (3) moves back to the primary array, and (4) then calls
3489
FTCRHD, then the new extension will be written following the 4th
3490
> extension, overwriting the existing 5th extension.
3491
-
3492
FTCRHD(unit, > status)
3493
-
3494
>8 Insert a new IMAGE extension immediately following the CHDU.
3495
Any following extensions will be shifted down to make room for
3496
the new extension. If there are no other following extensions
3497
then the new image extension will simply be appended to the
3498
> end of the file. The new extension will become the CHDU.
3499
-
3500
FTIIMG(unit,bitpix,naxis,naxes, > status)
3501
-
3502
>9 Insert a new ASCII TABLE extension immediately following the CHDU.
3503
Any following extensions will be shifted down to make room for
3504
the new extension. If there are no other following extensions
3505
then the new table extension will simply be appended to the
3506
> end of the file. The new extension will become the CHDU.
3507
-
3508
FTITAB(unit,rowlen,nrows,tfields,ttype,tbcol,tform,tunit,extname, >
3509
status)
3510
-
3511
>10 Insert a new binary table extension immediately following the CHDU.
3512
Any following extensions will be shifted down to make room for
3513
the new extension. If there are no other following extensions
3514
then the new bintable extension will simply be appended to the
3515
> end of the file. The new extension will become the CHDU.
3516
-
3517
FTIBIN(unit,nrows,tfields,ttype,tform,tunit,extname,varidat > status)
3518
-
3519
>11 Resize an image by modifing the size, dimensions, and/or datatype of the
3520
current primary array or image extension. If the new image, as specified
3521
by the input arguments, is larger than the current existing image
3522
in the FITS file then zero fill data will be inserted at the end
3523
of the current image and any following extensions will be moved
3524
further back in the file. Similarly, if the new image is
3525
smaller than the current image then any following extensions
3526
will be shifted up towards the beginning of the FITS file
3527
and the image data will be truncated to the new size.
3528
This routine rewrites the BITPIX, NAXIS, and NAXISn keywords
3529
> with the appropriate values for new image.
3530
-
3531
FTRSIM(unit,bitpix,naxis,naxes,status)
3532
-
3533
>12 Delete the CHDU in the FITS file. Any following HDUs will be shifted
3534
forward in the file, to fill in the gap created by the deleted
3535
HDU. In the case of deleting the primary array (the first HDU in
3536
the file) then the current primary array will be replace by a null
3537
primary array containing the minimum set of required keywords and
3538
no data. If there are more extensions in the file following the
3539
one that is deleted, then the the CHDU will be redefined to point
3540
to the following extension. If there are no following extensions
3541
then the CHDU will be redefined to point to the previous HDU. The
3542
output HDUTYPE parameter indicates the type of the new CHDU after
3543
> the previous CHDU has been deleted.
3544
-
3545
FTDHDU(unit, > hdutype,status)
3546
-
3547
>13 Copy the entire CHDU from the FITS file associated with IUNIT to the CHDU
3548
of the FITS file associated with OUNIT. The output HDU must be empty and
3549
not already contain any keywords. Space will be reserved for MOREKEYS
3550
additional keywords in the output header if there is not already enough
3551
> space.
3552
-
3553
FTCOPY(iunit,ounit,morekeys, > status)
3554
-
3555
>14 Copy the header (and not the data) from the CHDU associated with inunit
3556
to the CHDU associated with outunit. If the current output HDU
3557
is not completely empty, then the CHDU will be closed and a new
3558
HDU will be appended to the output file. This routine will automatically
3559
transform the necessary keywords when copying a primary array to
3560
and image extension, or an image extension to a primary array.
3561
> An empty output data unit will be created (all values = 0).
3562
-
3563
FTCPHD(inunit, outunit, > status)
3564
-
3565
>15 Copy just the data from the CHDU associated with IUNIT
3566
to the CHDU associated with OUNIT. This will overwrite
3567
any data previously in the OUNIT CHDU. This low level routine is used
3568
by FTCOPY, but it may also be useful in certain application programs
3569
which want to copy the data from one FITS file to another but also
3570
want to modify the header keywords in the process. all the required
3571
header keywords must be written to the OUNIT CHDU before calling
3572
> this routine
3573
-
3574
FTCPDT(iunit,ounit, > status)
3575
-
3576
3577
**C. Define or Redefine the structure of the CHDU \label{FTRDEF}
3578
3579
It should rarely be necessary to call the subroutines in this section.
3580
FITSIO internally calls these routines whenever necessary, so any calls
3581
to these routines by application programs will likely be redundant.
3582
3583
>1 This routine forces FITSIO to scan the current header keywords that
3584
define the structure of the HDU (such as the NAXISn, PCOUNT and GCOUNT
3585
keywords) so that it can initialize the internal buffers that describe
3586
the HDU structure. This routine may be used instead of the more
3587
complicated calls to ftpdef, ftadef or ftbdef. This routine is
3588
also very useful for reinitializing the structure of an HDU,
3589
if the number of rows in a table, as specified by the NAXIS2 keyword,
3590
> has been modified from its initial value.
3591
-
3592
FTRDEF(unit, > status) (DEPRECATED)
3593
-
3594
>2 Define the structure of the primary array or IMAGE extension. When
3595
writing GROUPed FITS files that by convention set the NAXIS1 keyword
3596
equal to 0, ftpdef must be called with naxes(1) = 1, NOT 0, otherwise
3597
FITSIO will report an error status=308 when trying to write data
3598
to a group. Note: it is usually simpler to call FTRDEF rather
3599
> than this routine.
3600
-
3601
FTPDEF(unit,bitpix,naxis,naxes,pcount,gcount, > status) (DEPRECATED)
3602
-
3603
>3 Define the structure of an ASCII table (TABLE) extension. Note: it
3604
> is usually simpler to call FTRDEF rather than this routine.
3605
-
3606
FTADEF(unit,rowlen,tfields,tbcol,tform,nrows > status) (DEPRECATED)
3607
-
3608
>4 Define the structure of a binary table (BINTABLE) extension. Note: it
3609
> is usually simpler to call FTRDEF rather than this routine.
3610
-
3611
FTBDEF(unit,tfields,tform,varidat,nrows > status) (DEPRECATED)
3612
-
3613
>5 Define the size of the Current Data Unit, overriding the length
3614
of the data unit as previously defined by ftpdef, ftadef, or ftbdef.
3615
This is useful if one does not know the total size of the data unit until
3616
after the data have been written. The size (in bytes) of an ASCII or
3617
Binary table is given by NAXIS1 * NAXIS2. (Note that to determine the
3618
value of NAXIS1 it is often more convenient to read the value of the
3619
NAXIS1 keyword from the output file, rather than computing the row
3620
length directly from all the TFORM keyword values). Note: it
3621
> is usually simpler to call FTRDEF rather than this routine.
3622
-
3623
FTDDEF(unit,bytlen, > status) (DEPRECATED)
3624
-
3625
>6 Define the zero indexed byte offset of the 'heap' measured from
3626
the start of the binary table data. By default the heap is assumed
3627
to start immediately following the regular table data, i.e., at
3628
location NAXIS1 x NAXIS2. This routine is only relevant for
3629
binary tables which contain variable length array columns (with
3630
TFORMn = 'Pt'). This subroutine also automatically writes
3631
the value of theap to a keyword in the extension header. This
3632
subroutine must be called after the required keywords have been
3633
written (with ftphbn) and after the table structure has been defined
3634
> (with ftbdef) but before any data is written to the table.
3635
-
3636
FTPTHP(unit,theap, > status)
3637
-
3638
3639
**D. FITS Header I/O Subroutines
3640
3641
***1. Header Space and Position Routines \label{FTHDEF}
3642
3643
>1 Reserve space in the CHU for MOREKEYS more header keywords.
3644
This subroutine may be called to reserve space for keywords which are
3645
to be written at a later time, after the data unit or subsequent
3646
extensions have been written to the FITS file. If this subroutine is
3647
not explicitly called, then the initial size of the FITS header will be
3648
limited to the space available at the time that the first data is written
3649
to the associated data unit. FITSIO has the ability to dynamically
3650
add more space to the header if needed, however it is more efficient
3651
> to preallocate the required space if the size is known in advance.
3652
-
3653
FTHDEF(unit,morekeys, > status)
3654
-
3655
>2 Return the number of existing keywords in the CHU (NOT including the
3656
END keyword which is not considered a real keyword) and the remaining
3657
space available to write additional keywords in the CHU. (returns
3658
KEYSADD = -1 if the header has not yet been closed).
3659
Note that FITSIO will attempt to dynamically add space for more
3660
> keywords if required when appending new keywords to a header.
3661
-
3662
FTGHSP(iunit, > keysexist,keysadd,status)
3663
-
3664
>3 Return the number of keywords in the header and the current position
3665
in the header. This returns the number of the keyword record that
3666
will be read next (or one greater than the position of the last keyword
3667
that was read or written). A value of 1 is returned if the pointer is
3668
> positioned at the beginning of the header.
3669
-
3670
FTGHPS(iunit, > keysexist,key_no,status)
3671
-
3672
***2. Read or Write Standard Header Routines \label{FTPHPR}
3673
3674
These subroutines provide a simple method of reading or writing most of
3675
the keyword values that are normally required in a FITS files. These
3676
subroutines are provided for convenience only and are not required to
3677
be used. If preferred, users may call the lower-level subroutines
3678
described in the previous section to individually read or write the
3679
required keywords. Note that in most cases, the required keywords such
3680
as NAXIS, TFIELD, TTYPEn, etc, which define the structure of the HDU
3681
must be written to the header before any data can be written to the
3682
image or table.
3683
3684
>1 Put the primary header or IMAGE extension keywords into the CHU.
3685
There are 2 available routines: The simpler FTPHPS routine is
3686
equivalent to calling ftphpr with the default values of SIMPLE = true,
3687
pcount = 0, gcount = 1, and EXTEND = true. PCOUNT, GCOUNT and EXTEND
3688
keywords are not required in the primary header and are only written if
3689
pcount is not equal to zero, gcount is not equal to zero or one, and if
3690
extend is TRUE, respectively. When writing to an IMAGE extension, the
3691
>SIMPLE and EXTEND parameters are ignored.
3692
-
3693
FTPHPS(unit,bitpix,naxis,naxes, > status)
3694
3695
FTPHPR(unit,simple,bitpix,naxis,naxes,pcount,gcount,extend, > status)
3696
-
3697
>2 Get primary header or IMAGE extension keywords from the CHU. When
3698
reading from an IMAGE extension the SIMPLE and EXTEND parameters are
3699
> ignored.
3700
-
3701
FTGHPR(unit,maxdim, > simple,bitpix,naxis,naxes,pcount,gcount,extend,
3702
status)
3703
-
3704
>3 Put the ASCII table header keywords into the CHU. The optional
3705
TUNITn and EXTNAME keywords are written only if the input string
3706
>values are not blank.
3707
-
3708
FTPHTB(unit,rowlen,nrows,tfields,ttype,tbcol,tform,tunit,extname, >
3709
status)
3710
-
3711
>>4 Get the ASCII table header keywords from the CHU
3712
-
3713
FTGHTB(unit,maxdim, > rowlen,nrows,tfields,ttype,tbcol,tform,tunit,
3714
extname,status)
3715
-
3716
>5 Put the binary table header keywords into the CHU. The optional
3717
TUNITn and EXTNAME keywords are written only if the input string
3718
values are not blank. The pcount parameter, which specifies the
3719
size of the variable length array heap, should initially = 0;
3720
FITSIO will automatically update the PCOUNT keyword value if any
3721
variable length array data is written to the heap. The TFORM keyword
3722
value for variable length vector columns should have the form 'Pt(len)'
3723
or '1Pt(len)' where `t' is the data type code letter (A,I,J,E,D, etc.)
3724
and `len' is an integer specifying the maximum length of the vectors
3725
in that column (len must be greater than or equal to the longest
3726
vector in the column). If `len' is not specified when the table is
3727
created (e.g., the input TFORMn value is just '1Pt') then FITSIO will
3728
scan the column when the table is first closed and will append the
3729
maximum length to the TFORM keyword value. Note that if the table
3730
is subsequently modified to increase the maximum length of the vectors
3731
then the modifying program is responsible for also updating the TFORM
3732
> keyword value.
3733
3734
-
3735
FTPHBN(unit,nrows,tfields,ttype,tform,tunit,extname,varidat, > status)
3736
-
3737
>>6 Get the binary table header keywords from the CHU
3738
-
3739
FTGHBN(unit,maxdim, > nrows,tfields,ttype,tform,tunit,extname,varidat,
3740
status)
3741
-
3742
***3. Write Keyword Subroutines \label{FTPREC}
3743
3744
>>1 Put (append) an 80-character record into the CHU.
3745
-
3746
FTPREC(unit,card, > status)
3747
-
3748
>2 Put (append) a COMMENT keyword into the CHU. Multiple COMMENT keywords
3749
> will be written if the input comment string is longer than 72 characters.
3750
-
3751
FTPCOM(unit,comment, > status)
3752
-
3753
>3 Put (append) a HISTORY keyword into the CHU. Multiple HISTORY keywords
3754
> will be written if the input history string is longer than 72 characters.
3755
-
3756
FTPHIS(unit,history, > status)
3757
-
3758
>4 Put (append) the DATE keyword into the CHU. The keyword value will contain
3759
the current system date as a character string in 'dd/mm/yy' format. If
3760
a DATE keyword already exists in the header, then this subroutine will
3761
> simply update the keyword value in-place with the current date.
3762
-
3763
FTPDAT(unit, > status)
3764
-
3765
>5 Put (append) a new keyword of the appropriate datatype into the CHU.
3766
Note that FTPKYS will only write string values up to 68 characters in
3767
length; longer strings will be truncated. The FTPKLS routine can be
3768
used to write longer strings, using a non-standard FITS convention.
3769
The E and D versions of this routine have the added feature that
3770
if the 'decimals' parameter is negative, then the 'G' display
3771
format rather then the 'E' format will be used when constructing
3772
the keyword value, taking the absolute value of 'decimals' for the
3773
precision. This will suppress trailing zeros, and will use a
3774
fixed format rather than an exponential format,
3775
> depending on the magnitude of the value.
3776
-
3777
FTPKY[JLS](unit,keyword,keyval,comment, > status)
3778
FTPKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
3779
-
3780
>6 Put (append) a string valued keyword into the CHU which may be longer
3781
than 68 characters in length. This uses the Long String Keyword
3782
convention that is described in the "Usage Guidelines and Suggestions"
3783
section of this document. Since this uses a non-standard FITS
3784
convention to encode the long keyword string, programs which use
3785
this routine should also call the FTPLSW routine to add some COMMENT
3786
keywords to warn users of the FITS file that this convention is
3787
being used. FTPLSW also writes a keyword called LONGSTRN to record
3788
the version of the longstring convention that has been used, in case
3789
a new convention is adopted at some point in the future. If the
3790
LONGSTRN keyword is already present in the header, then FTPLSW will
3791
> simply return and will not write duplicate keywords.
3792
-
3793
FTPKLS(unit,keyword,keyval,comment, > status)
3794
FTPLSW(unit, > status)
3795
-
3796
>7 Put (append) a new keyword with an undefined, or null, value into the CHU.
3797
> The value string of the keyword is left blank in this case.
3798
-
3799
FTPKYU(unit,keyword,comment, > status)
3800
-
3801
>8 Put (append) a numbered sequence of keywords into the CHU. One may
3802
append the same comment to every keyword (and eliminate the need
3803
to have an array of identical comment strings, one for each keyword) by
3804
including the ampersand character as the last non-blank character in the
3805
(first) COMMENTS string parameter. This same string
3806
will then be used for the comment field in all the keywords. (Note
3807
that the SPP version of these routines only supports a single comment
3808
> string).
3809
-
3810
FTPKN[JLS](unit,keyroot,startno,no_keys,keyvals,comments, > status)
3811
FTPKN[EDFG](unit,keyroot,startno,no_keys,keyvals,decimals,comments, >
3812
status)
3813
-
3814
>9 Copy an indexed keyword from one HDU to another, modifying
3815
the index number of the keyword name in the process. For example,
3816
this routine could read the TLMIN3 keyword from the input HDU
3817
(by giving keyroot = "TLMIN" and innum = 3) and write it to the
3818
output HDU with the keyword name TLMIN4 (by setting outnum = 4).
3819
If the input keyword does not exist, then this routine simply
3820
> returns without indicating an error.
3821
-
3822
FTCPKYinunit, outunit, innum, outnum, keyroot, > status)
3823
-
3824
>10 Put (append) a 'triple precision' keyword into the CHU in F28.16 format.
3825
The floating point keyword value is constructed by concatenating the
3826
input integer value with the input double precision fraction value
3827
(which must have a value between 0.0 and 1.0). The FTGKYT routine should
3828
be used to read this keyword value, because the other keyword reading
3829
> subroutines will not preserve the full precision of the value.
3830
-
3831
FTPKYT(unit,keyword,intval,dblval,comment, > status)
3832
-
3833
>11 Write keywords to the CHDU that are defined in an ASCII template file.
3834
The format of the template file is described under the ftgthd
3835
> routine below.
3836
-
3837
FTPKTP(unit, filename, > status)
3838
-
3839
>12 Append the physical units string to an existing keyword. This
3840
routine uses a local convention, shown in the following example,
3841
in which the keyword units are enclosed in square brackets in the
3842
> beginning of the keyword comment field.
3843
3844
-
3845
VELOCITY= 12.3 / [km/s] orbital speed
3846
3847
FTPUNT(unit,keyword,units, > status)
3848
-
3849
***4. Insert Keyword Subroutines \label{FTIREC}
3850
3851
>1 Insert a new keyword record into the CHU at the specified position
3852
(i.e., immediately preceding the (keyno)th keyword in the header.)
3853
This 'insert record' subroutine is somewhat less efficient
3854
then the 'append record' subroutine (FTPREC) described above because
3855
> the remaining keywords in the header have to be shifted down one slot.
3856
-
3857
FTIREC(unit,key_no,card, > status)
3858
-
3859
>2 Insert a new keyword into the CHU. The new keyword is inserted
3860
immediately following the last keyword that has been read from the header.
3861
The FTIKLS subroutine works the same as the FTIKYS subroutine, except
3862
it also supports long string values greater than 68 characters in length.
3863
These 'insert keyword' subroutines are somewhat less efficient then
3864
the 'append keyword' subroutines described above because the remaining
3865
> keywords in the header have to be shifted down one slot.
3866
-
3867
FTIKY[JLS](unit,keyword,keyval,comment, > status)
3868
FTIKLS(unit,keyword,keyval,comment, > status)
3869
FTIKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
3870
-
3871
>3 Insert a new keyword with an undefined, or null, value into the CHU.
3872
> The value string of the keyword is left blank in this case.
3873
-
3874
FTIKYU(unit,keyword,comment, > status)
3875
-
3876
***5. Read Keyword Subroutines \label{FTGREC}
3877
3878
These routines return the value of the specified keyword(s). Wild card
3879
characters (*, ?, or \#) may be used when specifying the name of the keyword
3880
to be read: a '?' will match any single character at that position in the
3881
keyword name and a '*' will match any length (including zero) string of
3882
characters. The '\#' character will match any consecutive string of
3883
decimal digits (0 - 9). Note that when a wild card is used in the input
3884
keyword name, the routine will only search for a match from the current
3885
header position to the end of the header. It will not resume the search
3886
from the top of the header back to the original header position as is done
3887
when no wildcards are included in the keyword name. If the desired
3888
keyword string is 8-characters long (the maximum length of a keyword
3889
name) then a '*' may be appended as the ninth character of the input
3890
name to force the keyword search to stop at the end of the header
3891
(e.g., 'COMMENT *' will search for the next COMMENT keyword). The
3892
ffgrec routine may be used to set the starting position when doing
3893
wild card searches.
3894
3895
>1 Get the nth 80-character header record from the CHU. The first keyword
3896
in the header is at key\_no = 1; if key\_no = 0 then this subroutine
3897
simple moves the internal pointer to the beginning of the header
3898
so that subsequent keyword operations will start at the top of
3899
> the header; it also returns a blank card value in this case.
3900
-
3901
FTGREC(unit,key_no, > card,status)
3902
-
3903
>2 Get the name, value (as a string), and comment of the nth keyword in CHU.
3904
This routine also checks that the returned keyword name (KEYWORD) contains
3905
only legal ASCII characters. Call FTGREC and FTPSVC to bypass this error
3906
> check.
3907
-
3908
FTGKYN(unit,key_no, > keyword,value,comment,status)
3909
-
3910
>>3 Get the 80-character header record for the named keyword
3911
-
3912
FTGCRD(unit,keyword, > card,status)
3913
-
3914
>4 Get the next keyword whose name matches one of the strings in
3915
'inclist' but does not match any of the strings in 'exclist'.
3916
The strings in inclist and exclist may contain wild card characters
3917
(*, ?, and \#) as described at the beginning of this section.
3918
This routine searches from the current header position to the
3919
end of the header, only, and does not continue the search from
3920
the top of the header back to the original position. The current
3921
header position may be reset with the ftgrec routine. Note
3922
that nexc may be set = 0 if there are no keywords to be excluded.
3923
This routine returns status = 202 if a matching
3924
> keyword is not found.
3925
-
3926
FTGNXK(unit,inclist,ninc,exclist,nexc, > card,status)
3927
-
3928
>5 Get the literal keyword value as a character string. Regardless
3929
of the datatype of the keyword, this routine simply returns the
3930
string of characters in the value field of the keyword along with
3931
> the comment field.
3932
-
3933
FTGKEY(unit,keyword, > value,comment,status)
3934
-
3935
>6 Get a keyword value (with the appropriate datatype) and comment from
3936
> the CHU
3937
-
3938
FTGKY[EDJLS](unit,keyword, > keyval,comment,status)
3939
-
3940
>7 Get a sequence of numbered keyword values. These
3941
> routines do not support wild card characters in the root name.
3942
-
3943
FTGKN[EDJLS](unit,keyroot,startno,max_keys, > keyvals,nfound,status)
3944
-
3945
>8 Get the value of a floating point keyword, returning the integer and
3946
fractional parts of the value in separate subroutine arguments.
3947
This subroutine may be used to read any keyword but is especially
3948
> useful for reading the 'triple precision' keywords written by FTPKYT.
3949
-
3950
FTGKYT(unit,keyword, > intval,dblval,comment,status)
3951
-
3952
>9 Get the physical units string in an existing keyword. This
3953
routine uses a local convention, shown in the following example,
3954
in which the keyword units are
3955
enclosed in square brackets in the beginning of the keyword comment
3956
field. A blank string is returned if no units are defined
3957
> for the keyword.
3958
-
3959
VELOCITY= 12.3 / [km/s] orbital speed
3960
3961
FTGUNT(unit,keyword, > units,status)
3962
-
3963
***6. Modify Keyword Subroutines \label{FTMREC}
3964
3965
Wild card characters, as described in the Read Keyword section, above,
3966
may be used when specifying the name of the keyword to be modified.
3967
3968
>>1 Modify (overwrite) the nth 80-character header record in the CHU
3969
-
3970
FTMREC(unit,key_no,card, > status)
3971
-
3972
>2 Modify (overwrite) the 80-character header record for the named keyword
3973
in the CHU. This can be used to overwrite the name of the keyword as
3974
> well as its value and comment fields.
3975
-
3976
FTMCRD(unit,keyword,card, > status)
3977
-
3978
>3 Modify (overwrite) the name of an existing keyword in the CHU
3979
> preserving the current value and comment fields.
3980
-
3981
FTMNAM(unit,oldkey,keyword, > status)
3982
-
3983
>>4 Modify (overwrite) the comment field of an existing keyword in the CHU
3984
-
3985
FTMCOM(unit,keyword,comment, > status)
3986
-
3987
>5 Modify the value and comment fields of an existing keyword in the CHU.
3988
The FTMKLS subroutine works the same as the FTMKYS subroutine, except
3989
it also supports long string values greater than 68 characters in length.
3990
Optionally, one may modify only the value field and leave the comment
3991
field unchanged by setting the input COMMENT parameter equal to
3992
the ampersand character (\&).
3993
The E and D versions of this routine have the added feature that
3994
if the 'decimals' parameter is negative, then the 'G' display
3995
format rather then the 'E' format will be used when constructing
3996
the keyword value, taking the absolute value of 'decimals' for the
3997
precision. This will suppress trailing zeros, and will use a
3998
fixed format rather than an exponential format,
3999
> depending on the magnitude of the value.
4000
-
4001
FTMKY[JLS](unit,keyword,keyval,comment, > status)
4002
FTMKLS(unit,keyword,keyval,comment, > status)
4003
FTMKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
4004
-
4005
>6 Modify the value of an existing keyword to be undefined, or null.
4006
The value string of the keyword is set to blank.
4007
Optionally, one may leave the comment field unchanged by setting the
4008
> input COMMENT parameter equal to the ampersand character (\&).
4009
-
4010
FTMKYU(unit,keyword,comment, > status)
4011
-
4012
***7. Update Keyword Subroutines \label{FTUCRD}
4013
4014
>1 Update an 80-character record in the CHU. If the specified keyword
4015
already exists then that header record will be replaced with
4016
the input CARD string. If it does not exist then the new record will
4017
be added to the header.
4018
The FTUKLS subroutine works the same as the FTUKYS subroutine, except
4019
> it also supports long string values greater than 68 characters in length.
4020
-
4021
FTUCRD(unit,keyword,card, > status)
4022
-
4023
>2 Update the value and comment fields of a keyword in the CHU.
4024
The specified keyword is modified if it already exists (by calling
4025
FTMKYx) otherwise a new keyword is created by calling FTPKYx.
4026
The E and D versions of this routine have the added feature that
4027
if the 'decimals' parameter is negative, then the 'G' display
4028
format rather then the 'E' format will be used when constructing
4029
the keyword value, taking the absolute value of 'decimals' for the
4030
precision. This will suppress trailing zeros, and will use a
4031
fixed format rather than an exponential format,
4032
> depending on the magnitude of the value.
4033
-
4034
FTUKY[JLS](unit,keyword,keyval,comment, > status)
4035
FTUKLS(unit,keyword,keyval,comment, > status)
4036
FTUKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
4037
-
4038
>3 Update the value of an existing keyword to be undefined, or null,
4039
or insert a new undefined-value keyword if it doesn't already exist.
4040
> The value string of the keyword is left blank in this case.
4041
-
4042
FTUKYU(unit,keyword,comment, > status)
4043
-
4044
***8. Delete Keyword Subroutines \label{FTDREC}
4045
4046
>1 Delete an existing keyword record. The space previously occupied by
4047
the keyword is reclaimed by moving all the following header records up
4048
one row in the header. The first routine deletes a keyword at a
4049
specified position in the header (the first keyword is at position 1),
4050
whereas the second routine deletes a specifically named keyword.
4051
Wild card characters, as described in the Read Keyword section, above,
4052
may be used when specifying the name of the keyword to be deleted
4053
> (be careful!).
4054
-
4055
FTDREC(unit,key_no, > status)
4056
FTDKEY(unit,keyword, > status)
4057
-
4058
4059
**F. Data Scaling and Undefined Pixel Parameters \label{FTPSCL}
4060
4061
These subroutines define or modify the internal parameters used by
4062
FITSIO to either scale the data or to represent undefined pixels.
4063
Generally FITSIO will scale the data according to the values of the BSCALE
4064
and BZERO (or TSCALn and TZEROn) keywords, however these subroutines
4065
may be used to override the keyword values. This may be useful when
4066
one wants to read or write the raw unscaled values in the FITS file.
4067
Similarly, FITSIO generally uses the value of the BLANK or TNULLn
4068
keyword to signify an undefined pixel, but these routines may be used
4069
to override this value. These subroutines do not create or modify the
4070
corresponding header keyword values.
4071
4072
>1 Reset the scaling factors in the primary array or image extension; does
4073
not change the BSCALE and BZERO keyword values and only affects the
4074
automatic scaling performed when the data elements are written/read
4075
to/from the FITS file. When reading from a FITS file the returned
4076
data value = (the value given in the FITS array) * BSCALE + BZERO.
4077
The inverse formula is used when writing data values to the FITS
4078
file. (NOTE: BSCALE and BZERO must be declared as Double Precision
4079
> variables).
4080
-
4081
FTPSCL(unit,bscale,bzero, > status)
4082
-
4083
>2 Reset the scaling parameters for a table column; does not change
4084
the TSCALn or TZEROn keyword values and only affects the automatic
4085
scaling performed when the data elements are written/read to/from
4086
the FITS file. When reading from a FITS file the returned data
4087
value = (the value given in the FITS array) * TSCAL + TZERO. The
4088
inverse formula is used when writing data values to the FITS file.
4089
(NOTE: TSCAL and TZERO must be declared as Double Precision
4090
> variables).
4091
-
4092
FTTSCL(unit,colnum,tscal,tzero, > status)
4093
-
4094
>3 Define the integer value to be used to signify undefined pixels in the
4095
primary array or image extension. This is only used if BITPIX = 8, 16,
4096
or 32. This does not create or change the value of the BLANK keyword in
4097
> the header.
4098
-
4099
FTPNUL(unit,blank, > status)
4100
-
4101
>4 Define the string to be used to signify undefined pixels in
4102
a column in an ASCII table. This does not create or change the value
4103
> of the TNULLn keyword.
4104
-
4105
FTSNUL(unit,colnum,snull > status)
4106
-
4107
>5 Define the value to be used to signify undefined pixels in
4108
an integer column in a binary table (where TFORMn = 'B', 'I', or 'J').
4109
> This does not create or change the value of the TNULLn keyword.
4110
-
4111
FTTNUL(unit,colnum,tnull > status)
4112
-
4113
4114
**G. FITS Primary Array or IMAGE Extension I/O Subroutines \label{FTPPR}
4115
4116
These subroutines put or get data values in the primary data array
4117
(i.e., the first HDU in the FITS file) or an IMAGE extension. The
4118
data array is represented as a single one-dimensional array of
4119
pixels regardless of the actual dimensionality of the array, and the
4120
FPIXEL parameter gives the position within this 1-D array of the first
4121
pixel to read or write. Automatic data type conversion is performed
4122
for numeric data (except for complex data types) if the data type of
4123
the primary array (defined by the BITPIX keyword) differs from the data
4124
type of the array in the calling subroutine. The data values are also
4125
scaled by the BSCALE and BZERO header values as they are being written
4126
or read from the FITS array. The ftpscl subroutine MUST be
4127
called to define the scaling parameters when writing data to the FITS
4128
array or to override the default scaling value given in the header when
4129
reading the FITS array.
4130
4131
Two sets of subroutines are provided to read the data array which
4132
differ in the way undefined pixels are handled. The first set of
4133
routines (FTGPVx) simply return an array of data elements in which
4134
undefined pixels are set equal to a value specified by the user in the
4135
'nullval' parameter. An additional feature of these subroutines is
4136
that if the user sets nullval = 0, then no checks for undefined pixels
4137
will be performed, thus increasing the speed of the program. The
4138
second set of routines (FTGPFx) returns the data element array and, in
4139
addition, a logical array which defines whether the corresponding data
4140
pixel is undefined. The latter set of subroutines may be more
4141
convenient to use in some circumstances, however, it requires an
4142
additional array of logical values which can be unwieldy when working
4143
with large data arrays. Also for programmer convenience, sets of
4144
subroutines to directly read or write 2 and 3 dimensional arrays have
4145
been provided, as well as a set of subroutines to read or write any
4146
contiguous rectangular subset of pixels within the n-dimensional array.
4147
4148
>1 Get the data type of the image (= BITPIX value). Possible returned
4149
> values are: 8, 16, 32, -32, or -64.
4150
-
4151
FTGIDT(unit, > bitpix,status)
4152
-
4153
>>2 Get the dimension (number of axes = NAXIS) of the image
4154
-
4155
FTGIDM(unit, > naxis,status)
4156
-
4157
>>3 Get the size of all the dimensions of the image
4158
-
4159
FTGISZ(unit, maxdim, > naxes,status)
4160
-
4161
>4 Get the parameters that define the type and size of the image. This
4162
> routine simply combines calls to the above 3 routines.
4163
-
4164
FTGIPR(unit, maxdim, > bitpix, naxis, naxes, int *status)
4165
-
4166
>>5 Put elements into the data array
4167
-
4168
FTPPR[BIJED](unit,group,fpixel,nelements,values, > status)
4169
-
4170
>6 Put elements into the data array, substituting the appropriate FITS null
4171
value for all elements which are equal to the value of NULLVAL. For
4172
integer FITS arrays, the null value defined by the previous call to FTPNUL
4173
will be substituted; for floating point FITS arrays (BITPIX = -32
4174
or -64) then the special IEEE NaN (Not-a-Number) value will be
4175
> substituted.
4176
-
4177
FTPPN[BIJED](unit,group,fpixel,nelements,values,nullval > status)
4178
-
4179
>>7 Set data array elements as undefined
4180
-
4181
FTPPRU(unit,group,fpixel,nelements, > status)
4182
-
4183
>8 Get elements from the data array. Undefined array elements will be
4184
returned with a value = nullval, unless nullval = 0 in which case no
4185
> checks for undefined pixels will be performed.
4186
-
4187
FTGPV[BIJED](unit,group,fpixel,nelements,nullval, > values,anyf,status)
4188
-
4189
>9 Get elements and nullflags from data array.
4190
Any undefined array elements will have the corresponding flagvals element
4191
> set equal to .TRUE.
4192
-
4193
FTGPF[BIJED](unit,group,fpixel,nelements, > values,flagvals,anyf,status)
4194
-
4195
>>10 Put values into group parameters
4196
-
4197
FTPGP[BIJED](unit,group,fparm,nparm,values, > status)
4198
-
4199
>>11 Get values from group parameters
4200
-
4201
FTGGP[BIJED](unit,group,fparm,nparm, > values,status)
4202
-
4203
The following 4 subroutines transfer FITS images with 2 or 3 dimensions
4204
to or from a data array which has been declared in the calling program.
4205
The dimensionality of the FITS image is passed by the naxis1, naxis2,
4206
and naxis3 parameters and the declared dimensions of the program array
4207
are passed in the dim1 and dim2 parameters. Note that the program array
4208
does not have to have the same dimensions as the FITS array, but must
4209
be at least as big. For example if a FITS image with NAXIS1 = NAXIS2 = 400
4210
is read into a program array which is dimensioned as 512 x 512 pixels,
4211
then the image will just fill the lower left corner of the array
4212
with pixels in the range 1 - 400 in the X an Y directions. This has
4213
the effect of taking a contiguous set of pixel value in the FITS array
4214
and writing them to a non-contiguous array in program memory
4215
(i.e., there are now some blank pixels around the edge of the image
4216
in the program array).
4217
4218
>>11 Put 2-D image into the data array
4219
-
4220
FTP2D[BIJED](unit,group,dim1,naxis1,naxis2,image, > status)
4221
-
4222
>>12 Put 3-D cube into the data array
4223
-
4224
FTP3D[BIJED](unit,group,dim1,dim2,naxis1,naxis2,naxis3,cube, > status)
4225
-
4226
>13 Get 2-D image from the data array. Undefined
4227
pixels in the array will be set equal to the value of 'nullval',
4228
unless nullval=0 in which case no testing for undefined pixels will
4229
> be performed.
4230
-
4231
FTG2D[BIJED](unit,group,nullval,dim1,naxis1,naxis2, > image,anyf,status)
4232
-
4233
>14 Get 3-D cube from the data array. Undefined
4234
pixels in the array will be set equal to the value of 'nullval',
4235
unless nullval=0 in which case no testing for undefined pixels will
4236
> be performed.
4237
-
4238
FTG3D[BIJED](unit,group,nullval,dim1,dim2,naxis1,naxis2,naxis3, >
4239
cube,anyf,status)
4240
-
4241
4242
The following subroutines transfer a rectangular subset of the pixels
4243
in a FITS N-dimensional image to or from an array which has been
4244
declared in the calling program. The fpixels and lpixels parameters
4245
are integer arrays which specify the starting and ending pixels in each
4246
dimension of the FITS image that are to be read or written. (Note that
4247
these are the starting and ending pixels in the FITS image, not in the
4248
declared array). The array parameter is treated simply as a large
4249
one-dimensional array of the appropriate datatype containing the pixel
4250
values; The pixel values in the FITS array are read/written from/to
4251
this program array in strict sequence without any gaps; it is up to
4252
the calling routine to correctly interpret the dimensionality of this
4253
array. The two families of FITS reading routines (FTGSVx and FTGSFx
4254
subroutines) also have an 'incs' parameter which defines the
4255
data sampling interval in each dimension of the FITS array. For
4256
example, if incs(1)=2 and incs(2)=3 when reading a 2-dimensional
4257
FITS image, then only every other pixel in the first dimension
4258
and every 3rd pixel in the second dimension will be returned in
4259
the 'array' parameter. [Note: the FTGSSx family of routines which
4260
were present in previous versions of FITSIO have been superseded
4261
by the more general FTGSVx family of routines.]
4262
4263
>>15 Put an arbitrary data subsection into the data array.
4264
-
4265
FTPSS[BIJED](unit,group,naxis,naxes,fpixels,lpixels,array, > status)
4266
-
4267
>16 Get an arbitrary data subsection from the data array. Undefined
4268
pixels in the array will be set equal to the value of 'nullval',
4269
unless nullval=0 in which case no testing for undefined pixels will
4270
> be performed.
4271
-
4272
FTGSV[BIJED](unit,group,naxis,naxes,fpixels,lpixels,incs,nullval, >
4273
array,anyf,status)
4274
-
4275
>17 Get an arbitrary data subsection from the data array. Any Undefined
4276
pixels in the array will have the corresponding 'flagvals'
4277
> element set equal to .TRUE.
4278
-
4279
FTGSF[BIJED](unit,group,naxis,naxes,fpixels,lpixels,incs, >
4280
array,flagvals,anyf,status)
4281
-
4282
4283
**H. FITS ASCII and Binary Table Data I/O Subroutines
4284
4285
***1. Column Information Subroutines \label{FTGCNO}
4286
4287
>1 Get the number of rows or columns in the current FITS table.
4288
The number of rows is given by the NAXIS2 keyword and the
4289
number of columns is given by the TFIELDS keyword in the header
4290
> of the table.
4291
-
4292
FTGNRW(unit, > nrows, status)
4293
FTGNCL(unit, > ncols, status)
4294
-
4295
>2 Get the table column number (and name) of the column whose name
4296
matches an input template name. The table column names are defined by
4297
the TTYPEn keywords in the FITS header. If a column does not have a
4298
TTYPEn keyword, then these routines assume that the name consists of
4299
all blank characters. These 2 subroutines perform the same function
4300
except that FTGCNO only returns the number of the matching column whereas
4301
FTGCNN also returns the name of the column. If CASESEN = .true. then
4302
the column name match will be case-sensitive.
4303
4304
The input column name template (COLTEMPLATE) is (1) either the exact
4305
name of the column to be searched for, or (2) it may contain wild cards
4306
characters (*, ?, or \#), or (3) it may contain the number of the desired
4307
column (where the number is expressed as ASCII digits). The first 2 wild
4308
cards behave similarly to UNIX filename matching: the '*' character matches
4309
any sequence of characters (including zero characters) and the '?'
4310
character matches any single character. The \# wildcard will match
4311
any consecutive string of decimal digits (0-9). As an example, the template
4312
strings 'AB?DE', 'AB*E', and 'AB*CDE' will all match the string
4313
'ABCDE'. If more than one column name in the table matches the
4314
template string, then the first match is returned and the status value
4315
will be set to 237 as a warning that a unique match was not found. To
4316
find the other cases that match the template, simply call the
4317
subroutine again leaving the input status value equal to 237 and the
4318
next matching name will then be returned. Repeat this process until a
4319
status = 219 (column name not found) is returned. If these subroutines
4320
fail to match the template to any of the columns in the table, they
4321
lastly check if the template can be interpreted as a simple positive
4322
integer (e.g., '7', or '512') and if so, they return that column
4323
number. If no matches are found then a status = 219 error is
4324
returned.
4325
4326
Note that the FITS Standard recommends that only letters, digits, and
4327
the underscore character be used in column names (with no embedded
4328
spaces in the name). Trailing blank characters are not significant.
4329
It is recommended that the column names in a given table be unique
4330
>within the first 8 characters.
4331
-
4332
FTGCNO(unit,casesen,coltemplate, > colnum,status)
4333
FTGCNN(unit,casesen,coltemplate, > colname,colnum,status)
4334
-
4335
>3 Get the datatype of a column in an ASCII or binary table. This
4336
routine returns an integer code value corresponding to the datatype
4337
of the column. (See the FTBNFM and FTASFM subroutines in the Utilities
4338
section of this document for a list of the code values). The vector
4339
repeat count (which is alway 1 for ASCII table columns) is also returned.
4340
If the specified column has an ASCII character datatype (code = 16) then
4341
the width of a unit string in the column is also returned. Note that
4342
this routine supports the local convention for specifying arrays of
4343
strings within a binary table character column, using the syntax
4344
TFORM = 'rAw' where 'r' is the total number of characters (= the width
4345
of the column) and 'w' is the width of a unit string within the column.
4346
Thus if the column has TFORM = '60A12' then this routine will return
4347
> datacode = 16, repeat = 60, and width = 12.
4348
-
4349
FTGTCL(unit,colnum, > datacode,repeat,width,status)
4350
-
4351
>4 Return the display width of a column. This is the length
4352
of the string that will be returned
4353
when reading the column as a formatted string. The display width is
4354
determined by the TDISPn keyword, if present, otherwise by the data
4355
> type of the column.
4356
-
4357
FTGCDW(unit, colnum, > dispwidth, status)
4358
-
4359
>5 Get information about an existing ASCII table column. (NOTE: TSCAL and
4360
TZERO must be declared as Double Precision variables). All the
4361
> returned parameters are scalar quantities.
4362
-
4363
FTGACL(unit,colnum, >
4364
ttype,tbcol,tunit,tform,tscal,tzero,snull,tdisp,status)
4365
-
4366
>6 Get information about an existing binary table column. (NOTE: TSCAL and
4367
TZERO must be declared as Double Precision variables). DATATYPE is a
4368
character string which returns the datatype of the column as defined
4369
by the TFORMn keyword (e.g., 'I', 'J','E', 'D', etc.). In the case
4370
of an ASCII character column, DATATYPE will have a value of the
4371
form 'An' where 'n' is an integer expressing the width of the field
4372
in characters. For example, if TFORM = '160A8' then FTGBCL will return
4373
DATATYPE='A8' and REPEAT=20. All the returned parameters are scalar
4374
> quantities.
4375
-
4376
FTGBCL(unit,colnum, >
4377
ttype,tunit,datatype,repeat,tscal,tzero,tnull,tdisp,status)
4378
-
4379
>7 Put (append) a TDIMn keyword whose value has the form '(l,m,n...)'
4380
where l, m, n... are the dimensions of a multidimension array
4381
> column in a binary table.
4382
-
4383
FTPTDM(unit,colnum,naxis,naxes, > status)
4384
-
4385
>8 Return the number of and size of the dimensions of a table column.
4386
Normally this information is given by the TDIMn keyword, but if
4387
this keyword is not present then this routine returns NAXIS = 1
4388
> and NAXES(1) equal to the repeat count in the TFORM keyword.
4389
-
4390
FTGTDM(unit,colnum,maxdim, > naxis,naxes,status)
4391
-
4392
>9 Decode the input TDIMn keyword string (e.g. '(100,200)') and return the
4393
number of and size of the dimensions of a binary table column. If the input
4394
tdimstr character string is null, then this routine returns naxis = 1
4395
and naxes[0] equal to the repeat count in the TFORM keyword. This routine
4396
> is called by FTGTDM.
4397
-
4398
FTDTDM(unit,tdimstr,colnum,maxdim, > naxis,naxes, status)
4399
-
4400
>10 Return the optimal number of rows to read or write at one time for
4401
maximum I/O efficiency. Refer to the ``Optimizing Code'' section
4402
> in Chapter 5 for more discussion on how to use this routine.
4403
4404
-
4405
FFGRSZ(unit, > nrows,status)
4406
-
4407
4408
***2. Low-Level Table Access Subroutines \label{FTGTBS}
4409
4410
The following subroutines provide low-level access to the data in ASCII
4411
or binary tables and are mainly useful as an efficient way to copy all
4412
or part of a table from one location to another. These routines simply
4413
read or write the specified number of consecutive bytes in an ASCII or
4414
binary table, without regard for column boundaries or the row length in
4415
the table. The first two subroutines read or write consecutive bytes
4416
in a table to or from a character string variable, while the last two
4417
subroutines read or write consecutive bytes to or from a variable
4418
declared as a numeric data type (e.g., INTEGER, INTEGER*2, REAL, DOUBLE
4419
PRECISION). These routines do not perform any machine dependent data
4420
conversion or byte swapping, except that conversion to/from ASCII
4421
format is performed by the FTGTBS and FTPTBS routines on machines which
4422
do not use ASCII character codes in the internal data representations
4423
(e.g., on IBM mainframe computers).
4424
4425
>1 Read a consecutive string of characters from an ASCII table
4426
into a character variable (spanning columns and multiple rows if necessary)
4427
This routine should not be used with binary tables because of
4428
> complications related to passing string variables between C and Fortran.
4429
-
4430
FTGTBS(unit,frow,startchar,nchars, > string,status)
4431
-
4432
>2 Write a consecutive string of characters to an ASCII table
4433
from a character variable (spanning columns and multiple rows if necessary)
4434
This routine should not be used with binary tables because of
4435
> complications related to passing string variables between C and Fortran.
4436
-
4437
FTPTBS(unit,frow,startchar,nchars,string, > status)
4438
-
4439
>3 Read a consecutive array of bytes from an ASCII or binary table
4440
into a numeric variable (spanning columns and multiple rows if necessary).
4441
The array parameter may be declared as any numerical datatype as long
4442
as the array is at least 'nchars' bytes long, e.g., if nchars = 17,
4443
> then declare the array as INTEGER*4 ARRAY(5).
4444
-
4445
FTGTBB(unit,frow,startchar,nchars, > array,status)
4446
-
4447
>4 Write a consecutive array of bytes to an ASCII or binary table
4448
from a numeric variable (spanning columns and multiple rows if necessary)
4449
The array parameter may be declared as any numerical datatype as long
4450
as the array is at least 'nchars' bytes long, e.g., if nchars = 17,
4451
> then declare the array as INTEGER*4 ARRAY(5).
4452
-
4453
FTPTBB(unit,frow,startchar,nchars,array, > status)
4454
-
4455
4456
***3. Edit Rows or Columns \label{FTIROW}
4457
4458
>1 Insert blank rows into an existing ASCII or binary table (in the CDU).
4459
All the rows FOLLOWING row FROW are shifted down by NROWS rows. If
4460
FROW = 0 then the blank rows are inserted at the beginning of the
4461
table. This routine modifies the NAXIS2 keyword to reflect the new
4462
> number of rows in the table.
4463
-
4464
FTIROW(unit,frow,nrows, > status)
4465
-
4466
>2 Delete rows from an existing ASCII or binary table (in the CDU).
4467
The NROWS number of rows are deleted, starting with row FROW, and
4468
any remaining rows in the table are shifted up to fill in the space.
4469
This routine modifies the NAXIS2 keyword to reflect the new number
4470
> of rows in the table.
4471
-
4472
FTDROW(unit,frow,nrows, > status)
4473
-
4474
>3 Delete a list of rows from an ASCII or binary table (in the CDU).
4475
rowlist is an array of row numbers to be deleted from the table.
4476
(The first row in the table is 1 not 0). The list of
4477
row numbers must be sorted in ascending order. nrows is the
4478
> number of row numbers in the list.
4479
-
4480
FTDRWS(unit,rowlist,nrows, > status)
4481
-
4482
>4 Insert a blank column (or columns) into an existing ASCII or binary
4483
table (in the CDU). COLNUM specifies the column number that the (first)
4484
new column should occupy in the table. NCOLS specifies how many
4485
columns are to be inserted. Any existing columns from this position and
4486
higher are moved over to allow room for the new column(s).
4487
The index number on all the following keywords will be incremented
4488
if necessary to reflect the new position of the column(s) in the table:
4489
TBCOLn, TFORMn, TTYPEn, TUNITn, TNULLn, TSCALn, TZEROn, TDISPn, TDIMn,
4490
TLMINn, TLMAXn, TDMINn, TDMAXn, TCTYPn, TCRPXn, TCRVLn, TCDLTn, TCROTn,
4491
> and TCUNIn.
4492
-
4493
FTICOL(unit,colnum,ttype,tform, > status)
4494
FTICLS(unit,colnum,ncols,ttype,tform, > status)
4495
-
4496
>5 Modify the vector length of a binary table column (e.g.,
4497
change a column from TFORMn = '1E' to '20E'). The vector
4498
> length may be increased or decreased from the current value.
4499
-
4500
FTMVEC(unit,colnum,newveclen, > status)
4501
-
4502
>6 Delete a column from an existing ASCII or binary table (in the CDU).
4503
The index number of all the keywords listed above (for FTICOL) will be
4504
decremented if necessary to reflect the new position of the column(s) in
4505
the table. Those index keywords that refer to the deleted column will
4506
also be deleted. Note that the physical size of the FITS file will
4507
not be reduced by this operation, and the empty FITS blocks if any
4508
> at the end of the file will be padded with zeros.
4509
-
4510
FTDCOL(unit,colnum, > status)
4511
-
4512
>7 Copy a column from one HDU to another (or to the same HDU). If
4513
createcol = TRUE, then a new column will be inserted in the output
4514
table, at position `outcolumn', otherwise the existing output column will
4515
be overwritten (in which case it must have a compatible datatype).
4516
> Note that the first column in a table is at colnum = 1.
4517
-
4518
FTCPCL(inunit,outunit,incolnum,outcolnum,createcol, > status);
4519
-
4520
***4. Read and Write Column Data Routines \label{FTPCLS}
4521
4522
These subroutines put or get data values in the current ASCII or Binary table
4523
extension. Automatic data type conversion is performed for numerical data
4524
types (B,I,J,E,D) if the data type of the column (defined by the TFORM keyword)
4525
differs from the data type of the calling subroutine. The data values are also
4526
scaled by the TSCALn and TZEROn header values as they are being written to
4527
or read from the FITS array. The fttscl subroutine MUST be used to define the
4528
scaling parameters when writing data to the table or to override the default
4529
scaling values given in the header
4530
when reading from the table.
4531
4532
In the case of binary tables with vector elements, the 'felem'
4533
parameter defines the starting pixel within the element vector. This
4534
parameter is ignored with ASCII tables. Similarly, in the case of
4535
binary tables the 'nelements' parameter specifies the total number of
4536
vector values read or written (continuing on subsequent rows if
4537
required) and not the number of table elements. Two sets of
4538
subroutines are provided to get the column data which differ in the way
4539
undefined pixels are handled. The first set of routines (FTGCV)
4540
simply return an array of data elements in which undefined pixels are
4541
set equal to a value specified by the user in the 'nullval' parameter.
4542
An additional feature of these subroutines is that if the user sets
4543
nullval = 0, then no checks for undefined pixels will be performed,
4544
thus increasing the speed of the program. The second set of routines
4545
(FTGCF) returns the data element array and in addition a logical array
4546
of flags which defines whether the corresponding data pixel is undefined.
4547
4548
Any column, regardless of it's intrinsic datatype, may be read as a
4549
string. It should be noted however that reading a numeric column
4550
as a string is 10 - 100 times slower than reading the same column as
4551
a number due to the large overhead in constructing the formatted
4552
strings. The display format of the returned strings will be
4553
determined by the TDISPn keyword, if it exists, otherwise by the
4554
datatype of the column. The length of the returned strings can be
4555
determined with the ftgcdw routine. The following TDISPn display
4556
formats are currently supported:
4557
-
4558
Iw.m Integer
4559
Ow.m Octal integer
4560
Zw.m Hexadecimal integer
4561
Fw.d Fixed floating point
4562
Ew.d Exponential floating point
4563
Dw.d Exponential floating point
4564
Gw.d General; uses Fw.d if significance not lost, else Ew.d
4565
-
4566
where w is the width in characters of the displayed values, m is the minimum
4567
number of digits displayed, and d is the number of digits to the right of the
4568
decimal. The .m field is optional.
4569
4570
>1 Put elements into an ASCII or binary table column (in the CDU).
4571
(The SPP FSPCLS routine has an additional integer argument after
4572
the VALUES character string which specifies the size of the 1st
4573
> dimension of this 2-D CHAR array).
4574
-
4575
FTPCL[SLBIJEDCM](unit,colnum,frow,felem,nelements,values, > status)
4576
-
4577
>2 Put elements into an ASCII or binary table column (in the CDU)
4578
substituting the appropriate FITS null value for any elements that
4579
are equal to NULLVAL. This family of routines must NOT be used to
4580
write to variable length array columns. For ASCII TABLE extensions, the
4581
null value defined by the previous call to FTSNUL will be substituted;
4582
For integer FITS columns, in a binary table the null value
4583
defined by the previous call to FTTNUL will be substituted;
4584
For floating point FITS columns a special IEEE NaN (Not-a-Number)
4585
> value will be substituted.
4586
-
4587
FTPCN[BIJED](unit,colnum,frow,felem,nelements,values,nullval > status)
4588
-
4589
>3 Put bit values into a binary byte ('B') or bit ('X') table column (in the
4590
CDU). LRAY is an array of logical values corresponding to the sequence of
4591
bits to be written. If LRAY is true then the corresponding bit is
4592
set to 1, otherwise the bit is set to 0. Note that in the case of
4593
'X' columns, FITSIO will write to all 8 bits of each byte whether
4594
they are formally valid or not. Thus if the column is defined as
4595
'4X', and one calls FTPCLX with fbit=1 and nbit=8, then all 8 bits
4596
will be written into the first byte (as opposed to writing the
4597
first 4 bits into the first row and then the next 4 bits into the
4598
next row), even though the last 4 bits of each byte are formally
4599
> not defined.
4600
-
4601
FTPCLX(unit,colnum,frow,fbit,nbit,lray, > status)
4602
-
4603
>>4 Set table elements in a column as undefined
4604
-
4605
FTPCLU(unit,colnum,frow,felem,nelements, > status)
4606
-
4607
>5 Get elements from an ASCII or binary table column (in the CDU). These
4608
routines return the values of the table column array elements. Undefined
4609
array elements will be returned with a value = nullval, unless nullval = 0
4610
(or = ' ' for ftgcvs) in which case no checking for undefined values will
4611
be performed. The ANYF parameter is set to true if any of the returned
4612
elements are undefined. (Note: the ftgcl routine simple gets an array
4613
of logical data values without any checks for undefined values; use
4614
the ftgcfl routine to check for undefined logical elements).
4615
(The SPP FSGCVS routine has an additional integer argument after
4616
the VALUES character string which specifies the size of the 1st
4617
> dimension of this 2-D CHAR array).
4618
-
4619
FTGCL(unit,colnum,frow,felem,nelements, > values,status)
4620
FTGCV[SBIJEDCM](unit,colnum,frow,felem,nelements,nullval, >
4621
values,anyf,status)
4622
-
4623
>6 Get elements and null flags from an ASCII or binary table column (in the
4624
CHDU). These routines return the values of the table column array elements.
4625
Any undefined array elements will have the corresponding flagvals element
4626
set equal to .TRUE. The ANYF parameter is set to true if any of the
4627
returned elements are undefined.
4628
(The SPP FSGCFS routine has an additional integer argument after
4629
the VALUES character string which specifies the size of the 1st
4630
> dimension of this 2-D CHAR array).
4631
-
4632
FTGCF[SLBIJEDCM](unit,colnum,frow,felem,nelements, >
4633
values,flagvals,anyf,status)
4634
-
4635
>7 Get an arbitrary data subsection from an N-dimensional array
4636
in a binary table vector column. Undefined pixels
4637
in the array will be set equal to the value of 'nullval',
4638
unless nullval=0 in which case no testing for undefined pixels will
4639
be performed. The first and last rows in the table to be read
4640
are specified by fpixels(naxis+1) and lpixels(naxis+1), and hence
4641
are treated as the next higher dimension of the FITS N-dimensional
4642
array. The INCS parameter specifies the sampling interval in
4643
> each dimension between the data elements that will be returned.
4644
-
4645
FTGSV[BIJED](unit,colnum,naxis,naxes,fpixels,lpixels,incs,nullval, >
4646
array,anyf,status)
4647
-
4648
>8 Get an arbitrary data subsection from an N-dimensional array
4649
in a binary table vector column. Any Undefined
4650
pixels in the array will have the corresponding 'flagvals'
4651
element set equal to .TRUE. The first and last rows in the table
4652
to be read are specified by fpixels(naxis+1) and lpixels(naxis+1),
4653
and hence are treated as the next higher dimension of the FITS
4654
N-dimensional array. The INCS parameter specifies the sampling
4655
interval in each dimension between the data elements that will be
4656
> returned.
4657
-
4658
FTGSF[BIJED](unit,colnum,naxis,naxes,fpixels,lpixels,incs, >
4659
array,flagvals,anyf,status)
4660
-
4661
>9 Get bit values from a byte ('B') or bit (`X`) table column (in the
4662
CDU). LRAY is an array of logical values corresponding to the
4663
sequence of bits to be read. If LRAY is true then the
4664
corresponding bit was set to 1, otherwise the bit was set to 0.
4665
Note that in the case of 'X' columns, FITSIO will read all 8 bits
4666
of each byte whether they are formally valid or not. Thus if the
4667
column is defined as '4X', and one calls FTGCX with fbit=1 and
4668
nbit=8, then all 8 bits will be read from the first byte (as
4669
opposed to reading the first 4 bits from the first row and then the
4670
first 4 bits from the next row), even though the last 4 bits of
4671
> each byte are formally not defined.
4672
-
4673
FTGCX(unit,colnum,frow,fbit,nbit, > lray,status)
4674
-
4675
>10 Read any consecutive set of bits from an 'X' or 'B' column and
4676
interpret them as an unsigned n-bit integer. NBIT must be less than
4677
or equal to 16 when calling FTGCXI, and less than or equal to 32 when
4678
calling FTGCXJ; there is no limit on the value of NBIT for FTGCXD, but
4679
the returned double precision value only has 48 bits of precision on
4680
most 32-bit word machines. The NBITS bits are interpreted as an
4681
unsigned integer unless NBITS = 16 (in FTGCXI) or 32 (in FTGCXJ) in which
4682
case the string of bits are interpreted as 16-bit or 32-bit 2's
4683
complement signed integers. If NROWS is greater than 1 then the
4684
same set of bits will be read from sequential rows in the table
4685
starting with row FROW. Note that the numbering convention
4686
used here for the FBIT parameter adopts 1 for the first element of the
4687
> vector of bits; this is the Most Significant Bit of the integer value.
4688
-
4689
FTGCX[IJD](unit,colnum,frow,nrows,fbit,nbit, > array,status)
4690
-
4691
>11 Get the descriptor for a variable length column in a binary table.
4692
The descriptor consists of 2 integer parameters: the number of elements
4693
in the array and the starting offset relative to the start of the heap.
4694
The first routine returns a single descriptor whereas the second routine
4695
> returns the descriptors for a range of rows in the table.
4696
-
4697
FTGDES(unit,colnum,rownum, > nelements,offset,status)
4698
FFGDESSunit,colnum,firstrow,nrows > nelements,offset, status)
4699
-
4700
>12 Put the descriptor for a variable length column in a binary table.
4701
This subroutine can be used in conjunction with FTGDES to enable
4702
2 or more arrays to point to the same storage location to save
4703
> storage space if the arrays are identical.
4704
-
4705
FTPDES(unit,colnum,rownum,nelements,offset, > status)
4706
-
4707
4708
**I. Row Selection and Calculator Routines \label{FTFROW}
4709
4710
These routines all parse and evaluate an input string containing a user
4711
defined arithmetic expression. The first 3 routines select rows in a
4712
FITS table, based on whether the expression evaluates to true (not
4713
equal to zero) or false (zero). The other routines evaluate the
4714
expression and calculate a value for each row of the table. The
4715
allowed expression syntax is described in the row filter section in the
4716
earlier `Extended File Name Syntax' chapter of this document.
4717
4718
>1 Evaluate a boolean expression over the indicated rows, returning an
4719
> array of flags indicating which rows evaluated to TRUE/FALSE
4720
-
4721
FTFROW(unit,expr,firstrow, nrows, > n_good_rows, row_status, status)
4722
-
4723
>>2 Find the first row which satisfies the input boolean expression
4724
-
4725
FTFFRW(unit, expr, > rownum, status)
4726
-
4727
>3 Evaluate an expression on all rows of a table. If the input and output
4728
files are not the same, copy the TRUE rows to the output file. If the
4729
>files are the same, delete the FALSE rows (preserve the TRUE rows).
4730
-
4731
FTSROW(inunit, outunit, expr, > status)
4732
-
4733
>4 Calculate an expression for the indicated rows of a table, returning
4734
the results, cast as datatype (TSHORT, TDOUBLE, etc), in array. If
4735
nulval==NULL, UNDEFs will be zeroed out. For vector results, the number
4736
of elements returned may be less than nelements if nelements is not an
4737
even multiple of the result dimension. Call FTTEXP to obtain
4738
>the dimensions of the results.
4739
-
4740
FTCROW(unit,datatype,expr,firstrow,nelements,nulval, >
4741
array,anynul,status)
4742
-
4743
>5 Evaluate an expression and write the result either to a column (if
4744
the expression is a function of other columns in the table) or to a
4745
keyword (if the expression evaluates to a constant and is not a
4746
function of other columns in the table). In the former case, the
4747
parName parameter is the name of the column (which may or may not already
4748
exist) into which to write the results, and parInfo contains an
4749
optional TFORM keyword value if a new column is being created. If a
4750
TFORM value is not specified then a default format will be used,
4751
depending on the expression. If the expression evalutes to a constant,
4752
then the result will be written to the keyword name given by the
4753
parName parameter, and the parInfo parameter may be used to supply an
4754
optional comment for the keyword. If the keyword does not already
4755
exist, then the name of the keyword must be preceeded with a '\#' character,
4756
>otherwise the result will be written to a column with that name.
4757
4758
-
4759
FTCALC(inunit, expr, outunit, parName, parInfo, > status)
4760
-
4761
>6 This calculator routine is similar to the previous routine, except
4762
that the expression is only evaluated over the specified
4763
row ranges. nranges specifies the number of row ranges, and firstrow
4764
>and lastrow give the starting and ending row number of each range.
4765
-
4766
FTCALC_RNG(inunit, expr, outunit, parName, parInfo,
4767
nranges, firstrow, lastrow, > status)
4768
-
4769
>>7 Evaluate the given expression and return information on the result.
4770
-
4771
FTTEXP(unit, expr, > datatype, nelem, naxis, naxes, status)
4772
-
4773
4774
4775
**J. Celestial Coordinate System Subroutines \label{FTGICS}
4776
4777
The following subroutines are provided to help calculate the
4778
transformation between pixel location in an image and the corresponding
4779
celestial coordinates on the sky. These support the following standard
4780
map projections: -SIN, -TAN, -ARC, -NCP, -GLS, -MER, and -AIT (these
4781
are the legal values for the coordtype parameter). These routines are
4782
based on similar functions in Classic AIPS. All the angular quantities
4783
are given in units of degrees.
4784
4785
>1 Get the values of all the standard FITS celestial coordinate system
4786
keywords from the header of a FITS image (i.e., the primary array or
4787
an image extension). These values may then be passed to the subroutines
4788
that perform the coordinate transformations. If any or all of the WCS
4789
keywords are not present, then default values will be returned. If
4790
the first coordinate axis is the declination-like coordinate, then
4791
this routine will swap them so that the longitudinal-like coordinate
4792
is returned as the first axis.
4793
4794
If the file uses the newer 'CDj\_i' WCS transformation matrix
4795
keywords instead of old style 'CDELTn' and 'CROTA2' keywords, then
4796
this routine will calculate and return the values of the equivalent
4797
old-style keywords. Note that the conversion from the new-style
4798
keywords to the old-style values is sometimes only an
4799
approximation, so if the approximation is larger than an internally
4800
defined threshold level, then CFITSIO will still return the
4801
approximate WCS keyword values, but will also return with status =
4802
506, to warn the calling program that approximations have been
4803
made. It is then up to the calling program to decide whether the
4804
approximations are sufficiently accurate for the particular
4805
application, or whether more precise WCS transformations must be
4806
> performed using new-style WCS keywords directly.
4807
-
4808
FTGICS(unit, > xrval,yrval,xrpix,yrpix,xinc,yinc,rot,coordtype,status)
4809
-
4810
>2 Get the values of all the standard FITS celestial coordinate system
4811
keywords from the header of a FITS table where the X and Y (or RA and
4812
DEC coordinates are stored in 2 separate columns of the table.
4813
These values may then be passed to the subroutines that perform the
4814
> coordinate transformations.
4815
-
4816
FTGTCS(unit,xcol,ycol, >
4817
xrval,yrval,xrpix,yrpix,xinc,yinc,rot,coordtype,status)
4818
-
4819
>3 Calculate the celestial coordinate corresponding to the input
4820
> X and Y pixel location in the image.
4821
-
4822
FTWLDP(xpix,ypix,xrval,yrval,xrpix,yrpix,xinc,yinc,rot,
4823
coordtype, > xpos,ypos,status)
4824
-
4825
>4 Calculate the X and Y pixel location corresponding to the input
4826
> celestial coordinate in the image.
4827
-
4828
FTXYPX(xpos,ypos,xrval,yrval,xrpix,yrpix,xinc,yinc,rot,
4829
coordtype, > xpix,ypix,status)
4830
-
4831
4832
**K. File Checksum Subroutines \label{FTPCKS}
4833
4834
The following routines either compute or validate the checksums for the
4835
CHDU. The DATASUM keyword is used to store the numerical value of the
4836
32-bit, 1's complement checksum for the data unit alone. If there is
4837
no data unit then the value is set to zero. The numerical value is
4838
stored as an ASCII string of digits, enclosed in quotes, because the
4839
value may be too large to represent as a 32-bit signed integer. The
4840
CHECKSUM keyword is used to store the ASCII encoded COMPLEMENT of the
4841
checksum for the entire HDU. Storing the complement, rather than the
4842
actual checksum, forces the checksum for the whole HDU to equal zero.
4843
If the file has been modified since the checksums were computed, then
4844
the HDU checksum will usually not equal zero. These checksum keyword
4845
conventions are based on a paper by Rob Seaman published in the
4846
proceedings of the ADASS IV conference in Baltimore in November 1994
4847
and a later revision in June 1995.
4848
4849
>1 Compute and write the DATASUM and CHECKSUM keyword values for the CHDU
4850
into the current header. The DATASUM value is the 32-bit checksum
4851
for the data unit, expressed as a decimal integer enclosed in single
4852
quotes. The CHECKSUM keyword value is a 16-character string which
4853
is the ASCII-encoded value for the complement of the checksum for
4854
the whole HDU. If these keywords already exist, their values
4855
will be updated only if necessary (i.e., if the file has been modified
4856
> since the original keyword values were computed).
4857
-
4858
FTPCKS(unit, > status)
4859
-
4860
>2 Update the CHECKSUM keyword value in the CHDU, assuming that the
4861
DATASUM keyword exists and already has the correct value. This routine
4862
calculates the new checksum for the current header unit, adds it to the
4863
data unit checksum, encodes the value into an ASCII string, and writes
4864
> the string to the CHECKSUM keyword.
4865
-
4866
FTUCKS(unit, > status)
4867
-
4868
>3 Verify the CHDU by computing the checksums and comparing
4869
them with the keywords. The data unit is verified correctly
4870
if the computed checksum equals the value of the DATASUM
4871
keyword. The checksum for the entire HDU (header plus data unit) is
4872
correct if it equals zero. The output DATAOK and HDUOK parameters
4873
in this subroutine are integers which will have a value = 1
4874
if the data or HDU is verified correctly, a value = 0
4875
if the DATASUM or CHECKSUM keyword is not present, or value = -1
4876
> if the computed checksum is not correct.
4877
-
4878
FTVCKS(unit, > dataok,hduok,status)
4879
-
4880
>4 Compute and return the checksum values for the CHDU (as
4881
double precision variables) without creating or modifying the
4882
CHECKSUM and DATASUM keywords. This routine is used internally by
4883
> FTVCKS, but may be useful in other situations as well.
4884
-
4885
FTGCKS(unit, > datasum,hdusum,status)
4886
-
4887
>5 Encode a checksum value (stored in a double precision variable)
4888
into a 16-character string. If COMPLEMENT = .true. then the 32-bit
4889
> sum value will be complemented before encoding.
4890
-
4891
FTESUM(sum,complement, > checksum)
4892
-
4893
>6 Decode a 16 character checksum string into a double precision value.
4894
If COMPLEMENT = .true. then the 32-bit sum value will be complemented
4895
> after decoding.
4896
-
4897
FTDSUM(checksum,complement, > sum)
4898
-
4899
4900
**L. Date and Time Utility Routines \label{FTGSDT}
4901
4902
The following routines help to construct or parse the FITS date/time
4903
strings. Starting in the year 2000, the FITS DATE keyword values (and
4904
the values of other `DATE-' keywords) must have the form 'YYYY-MM-DD'
4905
(date only) or 'YYYY-MM-DDThh:mm:ss.ddd...' (date and time) where the
4906
number of decimal places in the seconds value is optional. These times
4907
are in UTC. The older 'dd/mm/yy' date format may not be used for dates
4908
after 01 January 2000.
4909
4910
>1 Get the current system date. The returned year has 4 digits
4911
> (1999, 2000, etc.)
4912
-
4913
FTGSDT( > day, month, year, status )
4914
-
4915
4916
>2 Get the current system date and time string ('YYYY-MM-DDThh:mm:ss').
4917
The time will be in UTC/GMT if available, as indicated by a returned timeref
4918
value = 0. If the returned value of timeref = 1 then this indicates that
4919
it was not possible to convert the local time to UTC, and thus the local
4920
>time was returned.
4921
-
4922
FTGSTM(> datestr, timeref, status)
4923
-
4924
4925
>3 Construct a date string from the input date values. If the year
4926
is between 1900 and 1998, inclusive, then the returned date string will
4927
have the old FITS format ('dd/mm/yy'), otherwise the date string will
4928
have the new FITS format ('YYYY-MM-DD'). Use FTTM2S instead
4929
> to always return a date string using the new FITS format.
4930
-
4931
FTDT2S( year, month, day, > datestr, status)
4932
-
4933
4934
>4 Construct a new-format date + time string ('YYYY-MM-DDThh:mm:ss.ddd...').
4935
If the year, month, and day values all = 0 then only the time is encoded
4936
with format 'hh:mm:ss.ddd...'. The decimals parameter specifies how many
4937
decimal places of fractional seconds to include in the string. If `decimals'
4938
> is negative, then only the date will be return ('YYYY-MM-DD').
4939
-
4940
FTTM2S( year, month, day, hour, minute, second, decimals,
4941
> datestr, status)
4942
-
4943
4944
>5 Return the date as read from the input string, where the string may be
4945
in either the old ('dd/mm/yy') or new ('YYYY-MM-DDThh:mm:ss' or
4946
>'YYYY-MM-DD') FITS format.
4947
-
4948
FTS2DT(datestr, > year, month, day, status)
4949
-
4950
4951
>6 Return the date and time as read from the input string, where the
4952
string may be in either the old or new FITS format. The returned hours,
4953
minutes, and seconds values will be set to zero if the input string
4954
does not include the time ('dd/mm/yy' or 'YYYY-MM-DD') . Similarly,
4955
the returned year, month, and date values will be set to zero if the
4956
>date is not included in the input string ('hh:mm:ss.ddd...').
4957
-
4958
FTS2TM(datestr, > year, month, day, hour, minute, second, status)
4959
-
4960
4961
**M. General Utility Subroutines \label{FTGHAD}
4962
4963
The following utility subroutines may be useful for certain applications:
4964
4965
>>1 Return the starting byte address of the CHDU and the next HDU.
4966
-
4967
FTGHAD(iunit, > curaddr,nextaddr)
4968
-
4969
>>2 Convert a character string to uppercase (operates in place).
4970
-
4971
FTUPCH(string)
4972
-
4973
>3 Compare the input template string against the reference string
4974
to see if they match. The template string may contain wildcard
4975
characters: '*' will match any sequence of characters (including
4976
zero characters) and '%' will match any single character in the
4977
reference string. If CASESN = .true. then the match will be
4978
case sensitive. The returned MATCH parameter will be .true. if
4979
the 2 strings match, and EXACT will be .true. if the match is
4980
exact (i.e., if no wildcard characters were used in the match).
4981
> Both strings must be 68 characters or less in length.
4982
-
4983
FTCMPS(str_template,string,casesen, > match,exact)
4984
-
4985
4986
>4 Test that the keyword name contains only legal characters: A-Z,0-9,
4987
> hyphen, and underscore.
4988
-
4989
FTTKEY(keyword, > status)
4990
-
4991
>5 Test that the keyword record contains only legal printable ASCII
4992
> characters
4993
-
4994
FTTREC(card, > status)
4995
-
4996
>6 Test whether the current header contains any NULL (ASCII 0) characters.
4997
These characters are illegal in the header, but they will go undetected
4998
by most of the CFITSIO keyword header routines, because the null is
4999
interpreted as the normal end-of-string terminator. This routine returns
5000
the position of the first null character in the header, or zero if there
5001
are no nulls. For example a returned value of 110 would indicate that
5002
the first NULL is located in the 30th character of the second keyword
5003
in the header (recall that each header record is 80 characters long).
5004
Note that this is one of the few FITSIO routines in which the returned
5005
> value is not necessarily equal to the status value).
5006
-
5007
FTNCHK(unit, > status)
5008
-
5009
>7 Parse a header keyword record and return the name of the keyword
5010
and the length of the name.
5011
The keyword name normally occupies the first 8 characters of the
5012
record, except under the HIERARCH convention where the name can
5013
> be up to 70 characters in length.
5014
-
5015
FTGKNM(card, > keyname, keylength, status)
5016
-
5017
>8 Parse a header keyword record.
5018
This subroutine parses the input header record to return the value (as
5019
a character string) and comment strings. If the keyword has no
5020
value (columns 9-10 not equal to '= '), then the value string is returned
5021
blank and the comment string is set equal to column 9 - 80 of the
5022
> input string.
5023
-
5024
FTPSVC(card, > value,comment,status)
5025
-
5026
>9 Construct a sequence keyword name (ROOT + nnn).
5027
This subroutine appends the sequence number to the root string to create
5028
> a keyword name (e.g., 'NAXIS' + 2 = 'NAXIS2')
5029
-
5030
FTKEYN(keyroot,seq_no, > keyword,status)
5031
-
5032
>10 Construct a sequence keyword name (n + ROOT).
5033
This subroutine concatenates the sequence number to the front of the
5034
> root string to create a keyword name (e.g., 1 + 'CTYP' = '1CTYP')
5035
-
5036
FTNKEY(seq_no,keyroot, > keyword,status)
5037
-
5038
>11 Determine the datatype of a keyword value string.
5039
This subroutine parses the keyword value string (usually columns 11-30
5040
> of the header record) to determine its datatype.
5041
-
5042
FTDTYP(value, > dtype,status)
5043
-
5044
>11 Return the class of input header record. The record is classified
5045
into one of the following catagories (the class values are
5046
defined in fitsio.h). Note that this is one of the few FITSIO
5047
> routines that does not return a status value.
5048
-
5049
Class Value Keywords
5050
TYP_STRUC_KEY 10 SIMPLE, BITPIX, NAXIS, NAXISn, EXTEND, BLOCKED,
5051
GROUPS, PCOUNT, GCOUNT, END
5052
XTENSION, TFIELDS, TTYPEn, TBCOLn, TFORMn, THEAP,
5053
and the first 4 COMMENT keywords in the primary array
5054
that define the FITS format.
5055
TYP_CMPRS_KEY 20 The experimental keywords used in the compressed
5056
image format ZIMAGE, ZCMPTYPE, ZNAMEn, ZVALn,
5057
ZTILEn, ZBITPIX, ZNAXISn, ZSCALE, ZZERO, ZBLANK
5058
TYP_SCAL_KEY 30 BSCALE, BZERO, TSCALn, TZEROn
5059
TYP_NULL_KEY 40 BLANK, TNULLn
5060
TYP_DIM_KEY 50 TDIMn
5061
TYP_RANG_KEY 60 TLMINn, TLMAXn, TDMINn, TDMAXn, DATAMIN, DATAMAX
5062
TYP_UNIT_KEY 70 BUNIT, TUNITn
5063
TYP_DISP_KEY 80 TDISPn
5064
TYP_HDUID_KEY 90 EXTNAME, EXTVER, EXTLEVEL, HDUNAME, HDUVER, HDULEVEL
5065
TYP_CKSUM_KEY 100 CHECKSUM, DATASUM
5066
TYP_WCS_KEY 110 CTYPEn, CUNITn, CRVALn, CRPIXn, CROTAn, CDELTn
5067
CDj_is, PVj_ms, LONPOLEs, LATPOLEs
5068
TCTYPn, TCTYns, TCUNIn, TCUNns, TCRVLn, TCRVns, TCRPXn,
5069
TCRPks, TCDn_k, TCn_ks, TPVn_m, TPn_ms, TCDLTn, TCROTn
5070
jCTYPn, jCTYns, jCUNIn, jCUNns, jCRVLn, jCRVns, iCRPXn,
5071
iCRPns, jiCDn, jiCDns, jPVn_m, jPn_ms, jCDLTn, jCROTn
5072
(i,j,m,n are integers, s is any letter)
5073
TYP_REFSYS_KEY 120 EQUINOXs, EPOCH, MJD-OBSs, RADECSYS, RADESYSs
5074
TYP_COMM_KEY 130 COMMENT, HISTORY, (blank keyword)
5075
TYP_CONT_KEY 140 CONTINUE
5076
TYP_USER_KEY 150 all other keywords
5077
5078
class = FTGKCL (char *card)
5079
-
5080
>12 Parse the 'TFORM' binary table column format string.
5081
This subroutine parses the input TFORM character string and returns the
5082
integer datatype code, the repeat count of the field, and, in the case
5083
of character string fields, the length of the unit string. The following
5084
datatype codes are returned (the negative of the value is returned
5085
> if the column contains variable-length arrays):
5086
-
5087
Datatype DATACODE value
5088
bit, X 1
5089
byte, B 11
5090
logical, L 14
5091
ASCII character, A 16
5092
short integer, I 21
5093
integer, J 41
5094
real, E 42
5095
double precision, D 82
5096
complex 83
5097
double complex 163
5098
5099
FTBNFM(tform, > datacode,repeat,width,status)
5100
-
5101
>13 Parse the 'TFORM' keyword value that defines the column format in
5102
an ASCII table. This routine parses the input TFORM character
5103
string and returns the datatype code, the width of the column,
5104
and (if it is a floating point column) the number of decimal places
5105
to the right of the decimal point. The returned datatype codes are
5106
the same as for the binary table, listed above, with the following
5107
additional rules: integer columns that are between 1 and 4 characters
5108
wide are defined to be short integers (code = 21). Wider integer
5109
columns are defined to be regular integers (code = 41). Similarly,
5110
Fixed decimal point columns (with TFORM = 'Fw.d') are defined to
5111
be single precision reals (code = 42) if w is between 1 and 7 characters
5112
wide, inclusive. Wider 'F' columns will return a double precision
5113
data code (= 82). 'Ew.d' format columns will have datacode = 42,
5114
> and 'Dw.d' format columns will have datacode = 82.
5115
-
5116
FTASFM(tform, > datacode,width,decimals,status)
5117
-
5118
>14 Calculate the starting column positions and total ASCII table width
5119
based on the input array of ASCII table TFORM values. The SPACE input
5120
parameter defines how many blank spaces to leave between each column
5121
(it is recommended to have one space between columns for better human
5122
> readability).
5123
-
5124
FTGABC(tfields,tform,space, > rowlen,tbcol,status)
5125
-
5126
>15 Parse a template string and return a formatted 80-character string
5127
suitable for appending to (or deleting from) a FITS header file.
5128
This subroutine is useful for parsing lines from an ASCII template file
5129
and reformatting them into legal FITS header records. The formatted
5130
string may then be passed to the FTPREC, FTMCRD, or FTDKEY subroutines
5131
> to append or modify a FITS header record.
5132
-
5133
FTGTHD(template, > card,hdtype,status)
5134
-
5135
The input TEMPLATE character string generally should contain 3 tokens:
5136
(1) the KEYNAME, (2) the VALUE, and (3) the COMMENT string. The
5137
TEMPLATE string must adhere to the following format:
5138
5139
>- The KEYNAME token must begin in columns 1-8 and be a maximum of 8
5140
characters long. If the first 8 characters of the template line are
5141
blank then the remainder of the line is considered to be a FITS comment
5142
(with a blank keyword name). A legal FITS keyword name may only
5143
contain the characters A-Z, 0-9, and '-' (minus sign) and
5144
underscore. This subroutine will automatically convert any lowercase
5145
characters to uppercase in the output string. If KEYNAME = 'COMMENT'
5146
or 'HISTORY' then the remainder of the line is considered to be a FITS
5147
> COMMENT or HISTORY record, respectively.
5148
5149
>- The VALUE token must be separated from the KEYNAME token by one or more
5150
spaces and/or an '=' character. The datatype of the VALUE token
5151
(numeric, logical, or character string) is automatically determined
5152
and the output CARD string is formatted accordingly. The value
5153
token may be forced to be interpreted as a string (e.g. if it is a
5154
> string of numeric digits) by enclosing it in single quotes.
5155
5156
>- The COMMENT token is optional, but if present must be separated from
5157
the VALUE token by at least one blank space. A leading '/' character
5158
may be used to mark the beginning of the comment field, otherwise the
5159
comment field begins with the first non-blank character following the
5160
> value token.
5161
5162
>- One exception to the above rules is that if the first non-blank
5163
character in the template string is a minus sign ('-') followed
5164
by a single token, or a single token followed by an equal sign,
5165
then it is interpreted as the name of a keyword which is to be
5166
> deleted from the FITS header.
5167
5168
>- The second exception is that if the template string starts with
5169
a minus sign and is followed by 2 tokens then the second token
5170
is interpreted as the new name for the keyword specified by
5171
first token. In this case the old keyword name (first token)
5172
is returned in characters 1-8 of the returned CARD string, and
5173
the new keyword name (the second token) is returned in characters
5174
41-48 of the returned CARD string. These old and new names
5175
may then be passed to the FTMNAM subroutine which will change
5176
> the keyword name.
5177
5178
The HDTYPE output parameter indicates how the returned CARD string
5179
should be interpreted:
5180
-
5181
hdtype interpretation
5182
------ -------------------------------------------------
5183
-2 Modify the name of the keyword given in CARD(1:8)
5184
to the new name given in CARD(41:48)
5185
5186
-1 CARD(1:8) contains the name of a keyword to be deleted
5187
from the FITS header.
5188
5189
0 append the CARD string to the FITS header if the
5190
keyword does not already exist, otherwise update
5191
the value/comment if the keyword is already present
5192
in the header.
5193
5194
1 simply append this keyword to the FITS header (CARD
5195
is either a HISTORY or COMMENT keyword).
5196
5197
2 This is a FITS END record; it should not be written
5198
to the FITS header because FITSIO automatically
5199
appends the END record when the header is closed.
5200
-
5201
EXAMPLES: The following lines illustrate valid input template strings:
5202
-
5203
INTVAL 7 This is an integer keyword
5204
RVAL 34.6 / This is a floating point keyword
5205
EVAL=-12.45E-03 This is a floating point keyword in exponential notation
5206
lval F This is a boolean keyword
5207
This is a comment keyword with a blank keyword name
5208
SVAL1 = 'Hello world' / this is a string keyword
5209
SVAL2 '123.5' this is also a string keyword
5210
sval3 123+ / this is also a string keyword with the value '123+ '
5211
# the following template line deletes the DATE keyword
5212
- DATE
5213
# the following template line modifies the NAME keyword to OBJECT
5214
- NAME OBJECT
5215
-
5216
5217
*IX Summary of all FITSIO User-Interface Subroutines
5218
5219
Error Status Routines page~\pageref{FTVERS}
5220
-
5221
FTVERS( > version)
5222
FTGERR(status, > errtext)
5223
FTGMSG( > errmsg)
5224
FTRPRT (stream, > status)
5225
FTPMSG(errmsg)
5226
FTCMSG
5227
-
5228
FITS File Open and Close Subroutines: page~\pageref{FTOPEN}
5229
-
5230
FTOPEN(unit,filename,rwmode, > blocksize,status)
5231
FTNOPN(unit,filename,rwmode, > status)
5232
FTREOPEN(unit, > newunit, status)
5233
FTINIT(unit,filename,blocksize, > status)
5234
FTTPLT(unit, filename, tplfilename, > status)
5235
FTFLUS(unit, > status)
5236
FTCLOS(unit, > status)
5237
FTDELT(unit, > status)
5238
FTGIOU( > iounit, status)
5239
FTFIOU(iounit, > status)
5240
FTEXTN(filename, > nhdu, status)
5241
FTFLNM(unit, > filename, status)
5242
FTFLMD(unit, > iomode, status)
5243
FFURLT(unit, > urltype, status)
5244
FTIURL(filename, > filetype, infile, outfile, extspec, filter,
5245
binspec, colspec, status)
5246
FTRTNM(filename, > rootname, status)
5247
-
5248
HDU-Level Operations: page~\pageref{FTMAHD}
5249
-
5250
FTMAHD(unit,nhdu, > hdutype,status)
5251
FTMRHD(unit,nmove, > hdutype,status)
5252
FTGHDN(unit, > nhdu)
5253
FTMNHD(unit, hdutype, extname, extver, > status)
5254
FTGHDT(unit, > hdutype, status)
5255
FTTHDU(unit, > hdunum, status)
5256
FTCRHD(unit, > status)
5257
FTIIMG(unit,bitpix,naxis,naxes, > status)
5258
FTITAB(unit,rowlen,nrows,tfields,ttype,tbcol,tform,tunit,extname, >
5259
status)
5260
FTIBIN(unit,nrows,tfields,ttype,tform,tunit,extname,varidat > status)
5261
FTRSIM(unit,bitpix,naxis,naxes,status)
5262
FTDHDU(unit, > hdutype,status)
5263
FTCOPY(iunit,ounit,morekeys, > status)
5264
FTCPHD(inunit, outunit, > status)
5265
FTCPDT(iunit,ounit, > status)
5266
-
5267
Subroutines to specify or modify the structure of the CHDU: page~\pageref{FTRDEF}
5268
-
5269
FTRDEF(unit, > status) (DEPRECATED)
5270
FTPDEF(unit,bitpix,naxis,naxes,pcount,gcount, > status) (DEPRECATED)
5271
FTADEF(unit,rowlen,tfields,tbcol,tform,nrows > status) (DEPRECATED)
5272
FTBDEF(unit,tfields,tform,varidat,nrows > status) (DEPRECATED)
5273
FTDDEF(unit,bytlen, > status) (DEPRECATED)
5274
FTPTHP(unit,theap, > status)
5275
-
5276
Header Space and Position Subroutines: page~\pageref{FTHDEF}
5277
-
5278
FTHDEF(unit,morekeys, > status)
5279
FTGHSP(iunit, > keysexist,keysadd,status)
5280
FTGHPS(iunit, > keysexist,key_no,status)
5281
-
5282
Read or Write Standard Header Subroutines: page~\pageref{FTPHPR}
5283
-
5284
FTPHPS(unit,bitpix,naxis,naxes, > status)
5285
FTPHPR(unit,simple,bitpix,naxis,naxes,pcount,gcount,extend, > status)
5286
FTGHPR(unit,maxdim, > simple,bitpix,naxis,naxes,pcount,gcount,extend,
5287
status)
5288
FTPHTB(unit,rowlen,nrows,tfields,ttype,tbcol,tform,tunit,extname, >
5289
status)
5290
FTGHTB(unit,maxdim, > rowlen,nrows,tfields,ttype,tbcol,tform,tunit,
5291
extname,status)
5292
FTPHBN(unit,nrows,tfields,ttype,tform,tunit,extname,varidat > status)
5293
FTGHBN(unit,maxdim, > nrows,tfields,ttype,tform,tunit,extname,varidat,
5294
status)
5295
-
5296
Write Keyword Subroutines: page~\pageref{FTPREC}
5297
-
5298
FTPREC(unit,card, > status)
5299
FTPCOM(unit,comment, > status)
5300
FTPHIS(unit,history, > status)
5301
FTPDAT(unit, > status)
5302
FTPKY[JLS](unit,keyword,keyval,comment, > status)
5303
FTPKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
5304
FTPKLS(unit,keyword,keyval,comment, > status)
5305
FTPLSW(unit, > status)
5306
FTPKYU(unit,keyword,comment, > status)
5307
FTPKN[JLS](unit,keyroot,startno,no_keys,keyvals,comments, > status)
5308
FTPKN[EDFG](unit,keyroot,startno,no_keys,keyvals,decimals,comments, >
5309
status)
5310
FTCPKYinunit, outunit, innum, outnum, keyroot, > status)
5311
FTPKYT(unit,keyword,intval,dblval,comment, > status)
5312
FTPKTP(unit, filename, > status)
5313
FTPUNT(unit,keyword,units, > status)
5314
-
5315
Insert Keyword Subroutines: page~\pageref{FTIREC}
5316
-
5317
FTIREC(unit,key_no,card, > status)
5318
FTIKY[JLS](unit,keyword,keyval,comment, > status)
5319
FTIKLS(unit,keyword,keyval,comment, > status)
5320
FTIKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
5321
FTIKYU(unit,keyword,comment, > status)
5322
-
5323
Read Keyword Subroutines: page~\pageref{FTGREC}
5324
-
5325
FTGREC(unit,key_no, > card,status)
5326
FTGKYN(unit,key_no, > keyword,value,comment,status)
5327
FTGCRD(unit,keyword, > card,status)
5328
FTGNXK(unit,inclist,ninc,exclist,nexc, > card,status)
5329
FTGKEY(unit,keyword, > value,comment,status)
5330
FTGKY[EDJLS](unit,keyword, > keyval,comment,status)
5331
FTGKN[EDJLS](unit,keyroot,startno,max_keys, > keyvals,nfound,status)
5332
FTGKYT(unit,keyword, > intval,dblval,comment,status)
5333
FTGUNT(unit,keyword, > units,status)
5334
-
5335
Modify Keyword Subroutines: page~\pageref{FTMREC}
5336
-
5337
FTMREC(unit,key_no,card, > status)
5338
FTMCRD(unit,keyword,card, > status)
5339
FTMNAM(unit,oldkey,keyword, > status)
5340
FTMCOM(unit,keyword,comment, > status)
5341
FTMKY[JLS](unit,keyword,keyval,comment, > status)
5342
FTMKLS(unit,keyword,keyval,comment, > status)
5343
FTMKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
5344
FTMKYU(unit,keyword,comment, > status)
5345
-
5346
Update Keyword Subroutines: page~\pageref{FTUCRD}
5347
-
5348
FTUCRD(unit,keyword,card, > status)
5349
FTUKY[JLS](unit,keyword,keyval,comment, > status)
5350
FTUKLS(unit,keyword,keyval,comment, > status)
5351
FTUKY[EDFG](unit,keyword,keyval,decimals,comment, > status)
5352
FTUKYU(unit,keyword,comment, > status)
5353
-
5354
Delete Keyword Subroutines: page~\pageref{FTDREC}
5355
-
5356
FTDREC(unit,key_no, > status)
5357
FTDKEY(unit,keyword, > status)
5358
-
5359
Define Data Scaling Parameters and Undefined Pixel Flags: page~\pageref{FTPSCL}
5360
-
5361
FTPSCL(unit,bscale,bzero, > status)
5362
FTTSCL(unit,colnum,tscal,tzero, > status)
5363
FTPNUL(unit,blank, > status)
5364
FTSNUL(unit,colnum,snull > status)
5365
FTTNUL(unit,colnum,tnull > status)
5366
-
5367
FITS Primary Array or IMAGE Extension I/O Subroutines: page~\pageref{FTPPR}
5368
-
5369
FTGIDT(unit, > bitpix,status)
5370
FTGIDM(unit, > naxis,status)
5371
FTGISZ(unit, maxdim, > naxes,status)
5372
FTGIPR(unit, maxdim, > bitpix,naxis,naxes,status)
5373
FTPPR[BIJED](unit,group,fpixel,nelements,values, > status)
5374
FTPPN[BIJED](unit,group,fpixel,nelements,values,nullval > status)
5375
FTPPRU(unit,group,fpixel,nelements, > status)
5376
FTGPV[BIJED](unit,group,fpixel,nelements,nullval, > values,anyf,status)
5377
FTGPF[BIJED](unit,group,fpixel,nelements, > values,flagvals,anyf,status)
5378
FTPGP[BIJED](unit,group,fparm,nparm,values, > status)
5379
FTGGP[BIJED](unit,group,fparm,nparm, > values,status)
5380
FTP2D[BIJED](unit,group,dim1,naxis1,naxis2,image, > status)
5381
FTP3D[BIJED](unit,group,dim1,dim2,naxis1,naxis2,naxis3,cube, > status)
5382
FTG2D[BIJED](unit,group,nullval,dim1,naxis1,naxis2, > image,anyf,status)
5383
FTG3D[BIJED](unit,group,nullval,dim1,dim2,naxis1,naxis2,naxis3, >
5384
cube,anyf,status)
5385
FTPSS[BIJED](unit,group,naxis,naxes,fpixels,lpixels,array, > status)
5386
FTGSV[BIJED](unit,group,naxis,naxes,fpixels,lpixels,incs,nullval, >
5387
array,anyf,status)
5388
FTGSF[BIJED](unit,group,naxis,naxes,fpixels,lpixels,incs, >
5389
array,flagvals,anyf,status)
5390
-
5391
Table Column Information Subroutines: page~\pageref{FTGCNO}
5392
-
5393
FTGNRW(unit, > nrows, status)
5394
FTGNCL(unit, > ncols, status)
5395
FTGCNO(unit,casesen,coltemplate, > colnum,status)
5396
FTGCNN(unit,casesen,coltemplate, > colnam,colnum,status)
5397
FTGTCL(unit,colnum, > datacode,repeat,width,status)
5398
FTGCDW(unit,colnum, > dispwidth,status)
5399
FTGACL(unit,colnum, >
5400
ttype,tbcol,tunit,tform,tscal,tzero,snull,tdisp,status)
5401
FTGBCL(unit,colnum, >
5402
ttype,tunit,datatype,repeat,tscal,tzero,tnull,tdisp,status)
5403
FTPTDM(unit,colnum,naxis,naxes, > status)
5404
FTGTDM(unit,colnum,maxdim, > naxis,naxes,status)
5405
FTDTDM(unit,tdimstr,colnum,maxdim, > naxis,naxes, status)
5406
FFGRSZ(unit, > nrows,status)
5407
-
5408
Low-Level Table Access Subroutines: page~\pageref{FTGTBS}
5409
-
5410
FTGTBS(unit,frow,startchar,nchars, > string,status)
5411
FTPTBS(unit,frow,startchar,nchars,string, > status)
5412
FTGTBB(unit,frow,startchar,nchars, > array,status)
5413
FTPTBB(unit,frow,startchar,nchars,array, > status)
5414
-
5415
Edit Rows or Columns page~\pageref{FTIROW}
5416
-
5417
FTIROW(unit,frow,nrows, > status)
5418
FTDROW(unit,frow,nrows, > status)
5419
FTDRWS(unit,rowlist,nrows, > status)
5420
FTICOL(unit,colnum,ttype,tform, > status)
5421
FTICLS(unit,colnum,ncols,ttype,tform, > status)
5422
FTMVEC(unit,colnum,newveclen, > status)
5423
FTDCOL(unit,colnum, > status)
5424
FTCPCL(inunit,outunit,incolnum,outcolnum,createcol, > status);
5425
-
5426
Read and Write Column Data Routines page~\pageref{FTPCLS}
5427
-
5428
FTPCL[SLBIJEDCM](unit,colnum,frow,felem,nelements,values, > status)
5429
FTPCN[BIJED](unit,colnum,frow,felem,nelements,values,nullval > status)
5430
FTPCLX(unit,colnum,frow,fbit,nbit,lray, > status)
5431
FTPCLU(unit,colnum,frow,felem,nelements, > status)
5432
FTGCL(unit,colnum,frow,felem,nelements, > values,status)
5433
FTGCV[SBIJEDCM](unit,colnum,frow,felem,nelements,nullval, >
5434
values,anyf,status)
5435
FTGCF[SLBIJEDCM](unit,colnum,frow,felem,nelements, >
5436
values,flagvals,anyf,status)
5437
FTGSV[BIJED](unit,colnum,naxis,naxes,fpixels,lpixels,incs,nullval, >
5438
array,anyf,status)
5439
FTGSF[BIJED](unit,colnum,naxis,naxes,fpixels,lpixels,incs, >
5440
array,flagvals,anyf,status)
5441
FTGCX(unit,colnum,frow,fbit,nbit, > lray,status)
5442
FTGCX[IJD](unit,colnum,frow,nrows,fbit,nbit, > array,status)
5443
FTGDES(unit,colnum,rownum, > nelements,offset,status)
5444
FTPDES(unit,colnum,rownum,nelements,offset, > status)
5445
-
5446
Row Selection and Calculator Routines: page~\pageref{FTFROW}
5447
-
5448
FTFROW(unit,expr,firstrow, nrows, > n_good_rows, row_status, status)
5449
FTFFRW(unit, expr, > rownum, status)
5450
FTSROW(inunit, outunit, expr, > status )
5451
FTCROW(unit,datatype,expr,firstrow,nelements,nulval, >
5452
array,anynul,status)
5453
FTCALC(inunit, expr, outunit, parName, parInfo, > status)
5454
FTCALC_RNG(inunit, expr, outunit, parName, parInfo,
5455
nranges, firstrow, lastrow, > status)
5456
FTTEXP(unit, expr, > datatype, nelem, naxis, naxes, status)
5457
-
5458
Celestial Coordinate System Subroutines: page~\pageref{FTGICS}
5459
-
5460
FTGICS(unit, > xrval,yrval,xrpix,yrpix,xinc,yinc,rot,coordtype,status)
5461
FTGTCS(unit,xcol,ycol, >
5462
xrval,yrval,xrpix,yrpix,xinc,yinc,rot,coordtype,status)
5463
FTWLDP(xpix,ypix,xrval,yrval,xrpix,yrpix,xinc,yinc,rot,
5464
coordtype, > xpos,ypos,status)
5465
FTXYPX(xpos,ypos,xrval,yrval,xrpix,yrpix,xinc,yinc,rot,
5466
coordtype, > xpix,ypix,status)
5467
-
5468
File Checksum Subroutines: page~\pageref{FTPCKS}
5469
-
5470
FTPCKS(unit, > status)
5471
FTUCKS(unit, > status)
5472
FTVCKS(unit, > dataok,hduok,status)
5473
FTGCKS(unit, > datasum,hdusum,status)
5474
FTESUM(sum,complement, > checksum)
5475
FTDSUM(checksum,complement, > sum)
5476
5477
-
5478
Time and Date Utility Subroutines: page~\pageref{FTGSDT}
5479
-
5480
FTGSDT( > day, month, year, status )
5481
FTGSTM(> datestr, timeref, status)
5482
FTDT2S( year, month, day, > datestr, status)
5483
FTTM2S( year, month, day, hour, minute, second, decimals,
5484
> datestr, status)
5485
FTS2DT(datestr, > year, month, day, status)
5486
FTS2TM(datestr, > year, month, day, hour, minute, second, status)
5487
-
5488
General Utility Subroutines: page~\pageref{FTGHAD}
5489
-
5490
FTGHAD(unit, > curaddr,nextaddr)
5491
FTUPCH(string)
5492
FTCMPS(str_template,string,casesen, > match,exact)
5493
FTTKEY(keyword, > status)
5494
FTTREC(card, > status)
5495
FTNCHK(unit, > status)
5496
FTGKNM(unit, > keyword, keylength, status)
5497
FTPSVC(card, > value,comment,status)
5498
FTKEYN(keyroot,seq_no, > keyword,status)
5499
FTNKEY(seq_no,keyroot, > keyword,status)
5500
FTDTYP(value, > dtype,status)
5501
class = FTGKCL(card)
5502
FTASFM(tform, > datacode,width,decimals,status)
5503
FTBNFM(tform, > datacode,repeat,width,status)
5504
FTGABC(tfields,tform,space, > rowlen,tbcol,status)
5505
FTGTHD(template, > card,hdtype,status)
5506
-
5507
5508
*X. Parameter Definitions
5509
-
5510
anyf - (logical) set to TRUE if any of the returned data values are undefined
5511
array - (any datatype except character) array of bytes to be read or written.
5512
bitpix - (integer) bits per pixel: 8, 16, 32, -32, or -64
5513
blank - (integer) value used for undefined pixels in integer primary array
5514
blocksize - (integer) 2880-byte logical record blocking factor
5515
(if 0 < blocksize < 11) or the actual block size in bytes
5516
(if 10 < blocksize < 28800). As of version 3.3 of FITSIO,
5517
blocksizes greater than 2880 are no longer supported.
5518
bscale - (double precision) scaling factor for the primary array
5519
bytlen - (integer) length of the data unit, in bytes
5520
bzero - (double precision) zero point for primary array scaling
5521
card - (character*80) header record to be read or written
5522
casesen - (logical) will string matching be case sensitive?
5523
checksum - (character*16) encoded checksum string
5524
colname - (character) ASCII name of the column
5525
colnum - (integer) number of the column (first column = 1)
5526
coltemplate - (character) template string to be matched to column names
5527
comment - (character) the keyword comment field
5528
comments - (character array) keyword comment fields
5529
compid - (integer) the type of computer that the program is running on
5530
complement - (logical) should the checksum be complemented?
5531
coordtype - (character) type of coordinate projection (-SIN, -TAN, -ARC,
5532
-NCP, -GLS, -MER, or -AIT)
5533
cube - 3D data cube of the appropriate datatype
5534
curaddr - (integer) starting address (in bytes) of the CHDU
5535
datacode - (integer) symbolic code of the binary table column datatype
5536
dataok - (integer) was the data unit verification successful (=1) or
5537
not (= -1). Equals zero if the DATASUM keyword is not present.
5538
datasum - (double precision) 32-bit 1's complement checksum for the data unit
5539
datatype - (character) datatype (format) of the binary table column
5540
datestr - (string) FITS date/time string: 'YYYY-MM-DDThh:mm:ss.ddd',
5541
'YYYY-MM-dd', or 'dd/mm/yy'
5542
day - (integer) current day of the month
5543
dblval - (double precision) fractional part of the keyword value
5544
decimals - (integer) number of decimal places to be displayed
5545
dim1 - (integer) actual size of the first dimension of the image or cube array
5546
dim2 - (integer) actual size of the second dimension of the cube array
5547
dispwidth - (integer) - the display width (length of string) for a column
5548
dtype - (character) datatype of the keyword ('C', 'L', 'I', or 'F')
5549
C = character string
5550
L = logical
5551
I = integer
5552
F = floating point number
5553
errmsg - (character*80) oldest error message on the internal stack
5554
errtext - (character*30) descriptive error message corresponding to error number
5555
casesen - (logical) true if column name matching is case sensitive
5556
exact - (logical) do the strings match exactly, or were wildcards used?
5557
exclist (character array) list of names to be excluded from search
5558
extend - (logical) true if there may be extensions following the primary data
5559
extname - (character) value of the EXTNAME keyword (if not blank)
5560
fbit - (integer) first bit in the field to be read or written
5561
felem - (integer) first pixel of the element vector (ignored for ASCII tables)
5562
filename - (character) name of the FITS file
5563
flagvals - (logical array) True if corresponding data element is undefined
5564
fparm - (integer) sequence number of the first group parameter to read or write
5565
fpixel - (integer) the first pixel position
5566
fpixels - (integer array) the first included pixel in each dimension
5567
frow - (integer) beginning row number (first row of table = 1)
5568
gcount - (integer) value of the GCOUNT keyword (usually = 1)
5569
group - (integer) sequence number of the data group (=0 for non-grouped data)
5570
hdtype - (integer) header record type: -1=delete; 0=append or replace;
5571
1=append; 2=this is the END keyword
5572
hduok - (integer) was the HDU verification successful (=1) or
5573
not (= -1). Equals zero if the CHECKSUM keyword is not present.
5574
hdusum - (double precsion) 32 bit 1's complement checksum for the entire CHDU
5575
hdutype - (integer) type of HDU: 0 = primary array or IMAGE, 1 = ASCII table,
5576
2 = binary table, -1 = unknown
5577
history - (character) the HISTORY keyword comment string
5578
hour - (integer) hour from 0 - 23
5579
image - 2D image of the appropriate datatype
5580
inclist (character array) list of names to be included in search
5581
incs - (integer array) sampling interval for pixels in each FITS dimension
5582
intval - (integer) integer part of the keyword value
5583
iounit - (integer) value of an unused I/O unit number
5584
iunit - (integer) logical unit number associated with the input FITS file, 1-199
5585
key_no - (integer) sequence number (starting with 1) of the keyword record
5586
keylength - (integer) length of the keyword name
5587
keyroot - (character) root string for the keyword name
5588
keysadd -(integer) number of new keyword records which can fit in the CHU
5589
keysexist - (integer) number of existing keyword records in the CHU
5590
keyval - value of the keyword in the appropriate datatype
5591
keyvals - (array) value of the keywords in the appropriate datatype
5592
keyword - (character*8) name of a keyword
5593
lray - (logical array) array of logical values corresponding to the bit array
5594
lpixels - (integer array) the last included pixel in each dimension
5595
match - (logical) do the 2 strings match?
5596
maxdim - (integer) dimensioned size of the NAXES, TTYPE, TFORM or TUNIT arrays
5597
max_keys - (integer) maximum number of keywords to search for
5598
minute - (integer) minute of an hour (0 - 59)
5599
month - (integer) current month of the year (1 - 12)
5600
morekeys - (integer) will leave space in the header for this many more keywords
5601
naxes - (integer array) size of each dimension in the FITS array
5602
naxis - (integer) number of dimensions in the FITS array
5603
naxis1 - (integer) length of the X/first axis of the FITS array
5604
naxis2 - (integer) length of the Y/second axis of the FITS array
5605
naxis3 - (integer) length of the Z/third axis of the FITS array
5606
nbit - (integer) number of bits in the field to read or write
5607
nchars - (integer) number of characters to read and return
5608
ncols - (integer) number of columns
5609
nelements - (integer) number of data elements to read or write
5610
nexc (integer) number of names in the exclusion list (may = 0)
5611
nhdu - (integer) absolute number of the HDU (1st HDU = 1)
5612
ninc (integer) number of names in the inclusion list
5613
nmove - (integer) number of HDUs to move (+ or -), relative to current position
5614
nfound - (integer) number of keywords found (highest keyword number)
5615
no_keys - (integer) number of keywords to write in the sequence
5616
nparm - (integer) number of group parameters to read or write
5617
nrows - (integer) number of rows in the table
5618
nullval - value to represent undefined pixels, of the appropriate datatype
5619
nextaddr - (integer) starting address (in bytes) of the HDU following the CHDU
5620
offset - (integer) byte offset in the heap to the first element of the array
5621
oldkey - (character) old name of keyword to be modified
5622
ounit - (integer) logical unit number associated with the output FITS file 1-199
5623
pcount - (integer) value of the PCOUNT keyword (usually = 0)
5624
repeat - (integer) length of element vector (e.g. 12J); ignored for ASCII table
5625
rot - (double precision) celestial coordinate rotation angle (degrees)
5626
rowlen - (integer) length of a table row, in characters or bytes
5627
rowlist - (integer array) list of row numbers to be deleted in increasing order
5628
rownum - (integer) number of the row (first row = 1)
5629
rwmode - (integer) file access mode: 0 = readonly, 1 = readwrite
5630
second (double)- second within minute (0 - 60.9999999999) (leapsecond!)
5631
seq_no - (integer) the sequence number to append to the keyword root name
5632
simple - (logical) does the FITS file conform to all the FITS standards
5633
snull - (character) value used to represent undefined values in ASCII table
5634
space - (integer) number of blank spaces to leave between ASCII table columns
5635
startchar - (integer) first character in the row to be read
5636
startno - (integer) value of the first keyword sequence number (usually 1)
5637
status - (integer) returned error status code (0 = OK)
5638
str_template (character) template string to be matched to reference string
5639
stream - (character) output stream for the report: either 'STDOUT' or 'STDERR'
5640
string - (character) character string
5641
sum - (double precision) 32 bit unsigned checksum value
5642
tbcol - (integer array) column number of the first character in the field(s)
5643
tdisp - (character) Fortran type display format for the table column
5644
template-(character) template string for a FITS header record
5645
tfields - (integer) number of fields (columns) in the table
5646
tform - (character array) format of the column(s); allowed values are:
5647
For ASCII tables: Iw, Aw, Fww.dd, Eww.dd, or Dww.dd
5648
For binary tables: rL, rX, rB, rI, rJ, rA, rAw, rE, rD, rC, rM
5649
where 'w'=width of the field, 'd'=no. of decimals, 'r'=repeat count
5650
Note that the 'rAw' form is non-standard extension to the
5651
TFORM keyword syntax that is not specifically defined in the
5652
Binary Tables definition document.
5653
theap - (integer) zero indexed byte offset of starting address of the heap
5654
relative to the beginning of the binary table data
5655
tnull - (integer) value used to represent undefined values in binary table
5656
ttype - (character array) label for table column(s)
5657
tscal - (double precision) scaling factor for table column
5658
tunit - (character array) physical unit for table column(s)
5659
tzero - (double precision) scaling zero point for table column
5660
unit - (integer) logical unit number associated with the FITS file (1-199)
5661
units - (character) the keyword units string (e.g., 'km/s')
5662
value - (character) the keyword value string
5663
values - array of data values of the appropriate datatype
5664
varidat - (integer) size in bytes of the 'variable length data area'
5665
following the binary table data (usually = 0)
5666
version - (real) current revision number of the library
5667
width - (integer) width of the character string field
5668
xcol - (integer) number of the column containing the X coordinate values
5669
xinc - (double precision) X axis coordinate increment at reference pixel (deg)
5670
xpix - (double precision) X axis pixel location
5671
xpos - (double precision) X axis celestial coordinate (usually RA) (deg)
5672
xrpix - (double precision) X axis reference pixel array location
5673
xrval - (double precision) X axis coordinate value at the reference pixel (deg)
5674
ycol - (integer) number of the column containing the X coordinate values
5675
year - (integer) last 2 digits of the year (00 - 99)
5676
yinc - (double precision) Y axis coordinate increment at reference pixel (deg)
5677
ypix - (double precision) y axis pixel location
5678
ypos - (double precision) y axis celestial coordinate (usually DEC) (deg)
5679
yrpix - (double precision) Y axis reference pixel array location
5680
yrval - (double precision) Y axis coordinate value at the reference pixel (deg)
5681
-
5682
5683
*XI. FITSIO Error Status Codes
5684
-
5685
Status codes in the range -99 to -999 and 1 to 999 are reserved for future
5686
FITSIO use.
5687
5688
0 OK, no error
5689
-9 used in ffiimg to prepend a new primary array
5690
101 input and output files are the same
5691
103 too many FITS files open at once; all internal buffers full
5692
104 error opening existing file
5693
105 error creating new FITS file; (does a file with this name already exist?)
5694
106 error writing record to FITS file
5695
107 end-of-file encountered while reading record from FITS file
5696
108 error reading record from file
5697
110 error closing FITS file
5698
111 internal array dimensions exceeded
5699
112 Cannot modify file with readonly access
5700
113 Could not allocate memory
5701
114 illegal logical unit number; must be between 1 - 199, inclusive
5702
115 NULL input pointer to routine
5703
116 error seeking position in file
5704
5705
121 invalid URL prefix on file name
5706
122 tried to register too many IO drivers
5707
123 driver initialization failed
5708
124 matching driver is not registered
5709
125 failed to parse input file URL
5710
5711
151 bad argument in shared memory driver
5712
152 null pointer passed as an argument
5713
153 no more free shared memory handles
5714
154 shared memory driver is not initialized
5715
155 IPC error returned by a system call
5716
156 no memory in shared memory driver
5717
157 resource deadlock would occur
5718
158 attempt to open/create lock file failed
5719
159 shared memory block cannot be resized at the moment
5720
5721
5722
201 header not empty; can't write required keywords
5723
202 specified keyword name was not found in the header
5724
203 specified header record number is out of bounds
5725
204 keyword value field is blank
5726
205 keyword value string is missing the closing quote character
5727
207 illegal character in keyword name or header record
5728
208 keyword does not have expected name. Keyword out of sequence?
5729
209 keyword does not have expected integer value
5730
210 could not find the required END header keyword
5731
211 illegal BITPIX keyword value
5732
212 illegal NAXIS keyword value
5733
213 illegal NAXISn keyword value: must be 0 or positive integer
5734
214 illegal PCOUNT keyword value
5735
215 illegal GCOUNT keyword value
5736
216 illegal TFIELDS keyword value
5737
217 negative ASCII or binary table width value (NAXIS1)
5738
218 negative number of rows in ASCII or binary table (NAXIS2)
5739
219 column name (TTYPE keyword) not found
5740
220 illegal SIMPLE keyword value
5741
221 could not find the required SIMPLE header keyword
5742
222 could not find the required BITPIX header keyword
5743
223 could not find the required NAXIS header keyword
5744
224 could not find all the required NAXISn keywords in the header
5745
225 could not find the required XTENSION header keyword
5746
226 the CHDU is not an ASCII table extension
5747
227 the CHDU is not a binary table extension
5748
228 could not find the required PCOUNT header keyword
5749
229 could not find the required GCOUNT header keyword
5750
230 could not find the required TFIELDS header keyword
5751
231 could not find all the required TBCOLn keywords in the header
5752
232 could not find all the required TFORMn keywords in the header
5753
233 the CHDU is not an IMAGE extension
5754
234 illegal TBCOL keyword value; out of range
5755
235 this operation only allowed for ASCII or BINARY table extension
5756
236 column is too wide to fit within the specified width of the ASCII table
5757
237 the specified column name template matched more than one column name
5758
241 binary table row width is not equal to the sum of the field widths
5759
251 unrecognizable type of FITS extension
5760
252 unrecognizable FITS record
5761
253 END keyword contains non-blank characters in columns 9-80
5762
254 Header fill area contains non-blank characters
5763
255 Data fill area contains non-blank on non-zero values
5764
261 unable to parse the TFORM keyword value string
5765
262 unrecognizable TFORM datatype code
5766
263 illegal TDIMn keyword value
5767
5768
301 illegal HDU number; less than 1 or greater than internal buffer size
5769
302 column number out of range (1 - 999)
5770
304 attempt to move to negative file record number
5771
306 attempted to read or write a negative number of bytes in the FITS file
5772
307 illegal starting row number for table read or write operation
5773
308 illegal starting element number for table read or write operation
5774
309 attempted to read or write character string in non-character table column
5775
310 attempted to read or write logical value in non-logical table column
5776
311 illegal ASCII table TFORM format code for attempted operation
5777
312 illegal binary table TFORM format code for attempted operation
5778
314 value for undefined pixels has not been defined
5779
317 attempted to read or write descriptor in a non-descriptor field
5780
320 number of array dimensions out of range
5781
321 first pixel number is greater than the last pixel number
5782
322 attempt to set BSCALE or TSCALn scaling parameter = 0
5783
323 illegal axis length less than 1
5784
5785
340 NOT_GROUP_TABLE 340 Grouping function error
5786
341 HDU_ALREADY_MEMBER
5787
342 MEMBER_NOT_FOUND
5788
343 GROUP_NOT_FOUND
5789
344 BAD_GROUP_ID
5790
345 TOO_MANY_HDUS_TRACKED
5791
346 HDU_ALREADY_TRACKED
5792
347 BAD_OPTION
5793
348 IDENTICAL_POINTERS
5794
349 BAD_GROUP_ATTACH
5795
350 BAD_GROUP_DETACH
5796
5797
360 NGP_NO_MEMORY malloc failed
5798
361 NGP_READ_ERR read error from file
5799
362 NGP_NUL_PTR null pointer passed as an argument.
5800
Passing null pointer as a name of
5801
template file raises this error
5802
363 NGP_EMPTY_CURLINE line read seems to be empty (used
5803
internally)
5804
364 NGP_UNREAD_QUEUE_FULL cannot unread more then 1 line (or single
5805
line twice)
5806
365 NGP_INC_NESTING too deep include file nesting (infinite
5807
loop, template includes itself ?)
5808
366 NGP_ERR_FOPEN fopen() failed, cannot open template file
5809
367 NGP_EOF end of file encountered and not expected
5810
368 NGP_BAD_ARG bad arguments passed. Usually means
5811
internal parser error. Should not happen
5812
369 NGP_TOKEN_NOT_EXPECT token not expected here
5813
5814
401 error attempting to convert an integer to a formatted character string
5815
402 error attempting to convert a real value to a formatted character string
5816
403 cannot convert a quoted string keyword to an integer
5817
404 attempted to read a non-logical keyword value as a logical value
5818
405 cannot convert a quoted string keyword to a real value
5819
406 cannot convert a quoted string keyword to a double precision value
5820
407 error attempting to read character string as an integer
5821
408 error attempting to read character string as a real value
5822
409 error attempting to read character string as a double precision value
5823
410 bad keyword datatype code
5824
411 illegal number of decimal places while formatting floating point value
5825
412 numerical overflow during implicit datatype conversion
5826
413 error compressing image
5827
414 error uncompressing image
5828
420 error in date or time conversion
5829
5830
431 syntax error in parser expression
5831
432 expression did not evaluate to desired type
5832
433 vector result too large to return in array
5833
434 data parser failed not sent an out column
5834
435 bad data encounter while parsing column
5835
436 parse error: output file not of proper type
5836
5837
501 celestial angle too large for projection
5838
502 bad celestial coordinate or pixel value
5839
503 error in celestial coordinate calculation
5840
504 unsupported type of celestial projection
5841
505 required celestial coordinate keywords not found
5842
506 approximate wcs keyword values were returned
5843
-
5844
\end{document}
Loggerhead is a web-based interface for Breezy
Version: 2.0.1