1CFITSIO(3)            User Contributed Perl Documentation           CFITSIO(3)
2
3
4

NAME

6       Astro::FITS::CFITSIO - Perl extension for using the cfitsio library
7

SYNOPSIS

9         use Astro::FITS::CFITSIO;
10         use Astro::FITS::CFITSIO qw( :longnames );
11         use Astro::FITS::CFITSIO qw( :shortnames );
12         use Astro::FITS::CFITSIO qw( :constants );
13

DESCRIPTION

15       Perl interface to William Pence's cfitsio subroutine library. For more
16       information on cfitsio, see http://heasarc.gsfc.nasa.gov/fitsio.
17
18       This module attempts to provide a wrapper for nearly every cfitsio
19       routine, while retaining as much cfitsio behavior as possible. As such,
20       one should be aware that it is still somewhat low-level, in the sense
21       that handing an array which is not the correct size to a routine like
22       "fits_write_img()" may cause SIGSEGVs.
23
24       My goal is to eventually use these routines to build a more Perl-like
25       interface to many common tasks such as reading and writing of images
26       and ASCII and binary tables.
27

cfitsio API MAPPING

29       Astro::FITS::CFITSIO allows one to use either the long or short name
30       forms of the cfitsio routines. These work by using the exact same form
31       of arguments as one would find in an equivalent C program.
32
33       There is also an object-oriented API which uses the same function names
34       as the long-name API, but with the leading "fits_" stripped. To get a
35       Astro::FITS::CFITSIO "object" one would call "open_file()",
36       "create_file()" or "create_template()":
37
38           my $status = 0;
39           my $fptr = Astro::FITS::CFITSIO::open_file($filename,
40                               Astro::FITS::CFITSIO::READONLY(),$status);
41
42           $fptr->read_key_str('NAXIS1',$naxis1,undef,$status);
43
44       Note that the object-oriented forms of function names are only
45       available for those cfitsio routines which accept a "fitsfile*" data-
46       type as the first argument.
47
48       As an added benefit, whenever a filehandle goes out of scope, ffclos()
49       is automatically closed:
50
51           {
52             my $fptr = Astro::FITS::CFITSIO::open_file($filename,
53                               Astro::FITS::CFITSIO::READWRITE(),$status);
54             [manipulate $fptr]
55
56             # neither of the following are needed
57             # ffclos($fptr,$status);
58             # $fptr->close_file($status);
59           }
60
61       It there is an error, it will croak().
62

NAME SPACE

64       All cfitsio routines, with the exception of "fits_iterate_data()" and
65       "fits_open_memfile()", are available in both long and short name forms
66       (e.g., "fits_read_key" <=> "ffgky"), as well as all constants defined
67       in the fitsio.h header file. This raises the possibility of your name
68       space being invaded by nearly 1000 function and constant names.
69
70       To deal with this situation, Astro::FITS::CFITSIO makes use of the
71       Exporter package support for %EXPORT_TAGS. You can import the long-
72       named functions with
73
74           use Astro::FITS::CFITSIO qw( :longnames );
75
76       and the short-named routines with
77
78           use Astro::FITS::CFITSIO qw( :shortnames );
79
80       Constants are actually implemented as AUTOLOADed functions, so
81       "TSTRING", for instance, would be accessed via
82       "Astro::FITS::CFITSIO::TSTRING()". Alternatively you can
83
84           use Astro::FITS::CFITSIO qw( :constants );
85
86       which would allow you to simply say "TSTRING".
87

DATA STORAGE DETAILS

89   Input Variables
90       If a routine expects an N-dimensional array as input, and you hand it a
91       reference to a scalar, then Astro::FITS::CFITSIO simply uses the data
92       in the scalar which the argument is referencing.  Otherwise it expects
93       the argument to be a Perl array reference whose total number of
94       elements satisfies the input demands of the corresponding C routine.
95       Astro::FITS::CFITSIO then unpacks the array reference into a format
96       that the C routine can understand. If your input array does not hold
97       enough data for the C routine then a segfault is likely to occur.
98
99       cfitsio functions which take an optional NULL pointer - indicating no
100       output in that place is desired - can instead be given an "undef". In
101       other words, the following C and Perl statements which read a keyword
102       but ignore the comment would be roughly equivalent:
103
104           fits_read_key_lng(fptr,key,&value,NULL,&status);
105
106           fits_read_key_lng($fptr,$key,$value,undef,$status);
107
108   Output Variables
109       Calling cfitsio routines which read data from FITS files causes the
110       output variable to be transformed into a Perl array of the appropriate
111       dimensions.  The exception to this is if one wants the output to be in
112       the machine-native format (e.g., for use with PDL).  Then all output
113       variables will become scalars containing the appropriate data. The
114       exception here is with routines which read arrays of strings (e.g.,
115       "fits_read_col_str()").  In this case the output is again a Perl array
116       reference.
117
118       There are two ways to specify how data are retrieved.  The behavior can
119       be specified either globally or on a per filehandle basis.  The global
120       selection is done by calling the PerlyUnpacking function.  This sets
121       the behavior for all file handles which do not explicitly choose not to
122       follow it.
123
124         # turn ON unpacking into Perl arrays.  This is the default
125         PerlyUnpacking(1);
126
127         # turn OFF unpacking into Perl arrays, i.e. put in machine-native
128         # format
129         PerlyUnpacking(0);
130
131         # retrieve the current state:
132         $state = PerlyUnpacking();
133
134       To change the behavior for a particular file handle, use the
135       perlyunpacking method.  The default behavior for a file handle is to
136       track what is done with PerlyUnpacking()
137
138         # track PerlyUnpacking().  This is the default
139         $fptr->perlyunpacking(-1);
140
141         # turn ON unpacking into Perl arrays
142         $fptr->perlyunpacking(1);
143
144         # turn OFF unpacking into Perl arrays
145         $fptr->perlyunpacking(0);
146
147         # retrieve the current state:
148         $state = $fptr->perlyunpacking;
149

EXAMPLES

151       Take a look at testprog/testprog.pl under the distribution directory.
152       It should produce output identical to testprog.c which comes with the
153       cfitsio library. Additionally, the versions named
154       testprog_longnames.pl, testprog_OO.pl  and testprog_pdl.pl test the
155       long-name and object-oriented APIs, and machine-native unpacking with
156       PDL.
157
158       There is also an examples/ directory with scripts which do the
159       following:
160
161       image_read.pl
162           reads a FITS primary image and displays it using PGPLOT
163
164       image_read_pdl.pl
165           same as above, but uses machine-native unpacking with PDL
166
167       bintable_read_pdl.pl
168           reads binary table column into PDL object, makes histogram and
169           plots it
170

CONSIDERATIONS

172       Ensure your input arrays contain enough data
173           The caller is responsible for ensuring that the input arrays given
174           to Astro::FITS::CFITSIO routines are large enough to satisfy the
175           access demands of said routines. For example, if you tell
176           "fits_write_col()" to write a data column containing 100 elements,
177           your Perl array should contain at least 100 elements. Segfaults
178           abound, so beware!
179
180       maxdim semantics
181           Some cfitsio routines take a parameter named something like
182           '"maxdim"', indicating that no more than that many elements should
183           be placed into the output data area. An example of this would be
184           "fits_read_tdim()".  In these cases Astro::FITS::CFITSIO will
185           automatically determine how much storage space is needed for the
186           full amount of output possible. As a result, the arguments expected
187           in Astro::FITS::CFITSIO are slightly different than one would use
188           in a C program, in that the '"maxdim"' argument is unnecessary.
189
190           Currently the routines for which this is the case are
191           "fits_read_atblhdr()", "fits_read_btblhdr()", "fits_read_imghdr()",
192           "fits_decode_tdim()", "fits_read_tdim()" "fits_test_expr()",
193           "fits_get_img_parm()" and "fits_get_img_size()".
194
195       Output arrays remain as undisturbed as possible
196           For routines like "fits_read_col()", Astro::FITS::CFITSIO unpacks
197           the output into a Perl array reference (unless PerlyUnpacking(0)
198           has been called, of course). Prior to doing this, it ensures the
199           scalar passed is a reference to an array large enough to hold the
200           data. If the argument is an array reference which is too small, it
201           expands the array pointed to appropriately. But, if the array is
202           large enough already, the data are just unpacked into the array.
203           The upshot: If you call "fits_read_col()", telling it to read 100
204           data elements, and the array you are placing the data into already
205           has 200 elements, then after "fits_read_col()" returns your array
206           will still have 200 elements, only the first 100 of which actually
207           correspond to the data read by the routine.
208
209           In more succinct language:
210
211               @output = (0..199);
212               fits_read_col_lng($fptr,2,1,1,100,0,\@output,$anynul,$status);
213
214               # @output still has 200 elements, only first 100 are from FITS
215               # file
216

EXTRA COMMANDS

218       Some extra commands that use sets of cfitsio routines are supplied to
219       simplify some standard tasks:
220
221       fits_read_header(filename)
222           This command reads in a primary fits header (unless one is using
223           the extended filename sytax to move to a different HDU on open)
224           from the specified filename and returns the header as a hash
225           reference and a status (when called in an array context) or simply
226           a hash reference (when called in a scalar context):
227
228             ($hash_ref, $status) = fits_read_header ($file);
229             $hash_ref = fits_read_header($file);
230
231           An object-oriented interface is also provided for reading headers
232           from FITS files that have already been opened. In this case, the
233           header read is from the current HDU.
234
235             $fitsfile = Astro::FITS::CFITSIO::open_file($file);
236             $hash_ref = $fitsfile->read_header;
237             ($hash_ref, $status) = $fitsfile->read_header;
238
239       sizeof_datatype(datatype)
240           Returns the size of the given Astro::FITS::CFITSIO datatype
241           constant (e.g., "Astro::FITS::CFITSIO::TSHORT()").
242

BUGS

244       FIXME
245

AUTHOR

247       Pete Ratzlaff <pratzlaff@cfa.harvard.edu>, with a great deal of code
248       taken from Karl Glazebrook's PGPLOT module.
249
250       Contributors include:
251
252       Diab Jerius, <djerius@cpan.org>
253           general improvements
254
255       Tim Jenness, <t.jenness@jach.hawaii.edu>
256           convenience routines
257
258       Tim Conrow, <tim@ipac.caltech.edu>
259           function implementations, bug fixes
260
262       Copyright (C) 2002,2004,2006,2011 by the Smithsonian Astrophysical
263       Observatory.
264
265       This software is released under the same terms as Perl. A copy of the
266       Perl license may be obtained at http://dev.perl.org/licenses/
267
268
269
270perl v5.34.0                      2022-01-20                        CFITSIO(3)
Impressum