1CFITSIO(3) User Contributed Perl Documentation CFITSIO(3)
2
6 Astro::FITS::CFITSIO - Perl extension for using the cfitsio library
7
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
15 Perl interface to William Pence's cfitsio subroutine library. For more
16 information on cfitsio, see http://heasarc.gsfc.nasa.gov/fitsio.
17 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 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
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 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 my $status = 0;
39 my $fptr = Astro::FITS::CFITSIO::open_file($filename,
40 Astro::FITS::CFITSIO::READONLY(),$status);
41 $fptr->read_key_str('NAXIS1',$naxis1,undef,$status);
43 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 As an added benefit, whenever a filehandle goes out of scope, ffclos()
49 is automatically closed:
50 {
52 my $fptr = Astro::FITS::CFITSIO::open_file($filename,
53 Astro::FITS::CFITSIO::READWRITE(),$status);
54 [manipulate $fptr]
55 # neither of the following are needed
57 # ffclos($fptr,$status);
58 # $fptr->close_file($status);
59 }
60 It there is an error, it will croak().
62
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 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 use Astro::FITS::CFITSIO qw( :longnames );
75 and the short-named routines with
77 use Astro::FITS::CFITSIO qw( :shortnames );
79 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 use Astro::FITS::CFITSIO qw( :constants );
85 which would allow you to simply say "TSTRING".
87
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 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 fits_read_key_lng(fptr,key,&value,NULL,&status);
105 fits_read_key_lng($fptr,$key,$value,undef,$status);
107 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 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 # turn ON unpacking into Perl arrays. This is the default
125 PerlyUnpacking(1);
126 # turn OFF unpacking into Perl arrays, i.e. put in machine-native
128 # format
129 PerlyUnpacking(0);
130 # retrieve the current state:
132 $state = PerlyUnpacking();
133 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 # track PerlyUnpacking(). This is the default
139 $fptr->perlyunpacking(-1);
140 # turn ON unpacking into Perl arrays
142 $fptr->perlyunpacking(1);
143 # turn OFF unpacking into Perl arrays
145 $fptr->perlyunpacking(0);
146 # retrieve the current state:
148 $state = $fptr->perlyunpacking;
149
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 There is also an examples/ directory with scripts which do the
159 following:
160 image_read.pl
162 reads a FITS primary image and displays it using PGPLOT
163 image_read_pdl.pl
165 same as above, but uses machine-native unpacking with PDL
166 bintable_read_pdl.pl
168 reads binary table column into PDL object, makes histogram and
169 plots it
170
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 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 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 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 In more succinct language:
210 @output = (0..199);
212 fits_read_col_lng($fptr,2,1,1,100,0,\@output,$anynul,$status);
213 # @output still has 200 elements, only first 100 are from FITS
215 # file
216
218 Some extra commands that use sets of cfitsio routines are supplied to
219 simplify some standard tasks:
220 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 ($hash_ref, $status) = fits_read_header ($file);
229 $hash_ref = fits_read_header($file);
230 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 $fitsfile = Astro::FITS::CFITSIO::open_file($file);
236 $hash_ref = $fitsfile->read_header;
237 ($hash_ref, $status) = $fitsfile->read_header;
238 sizeof_datatype(datatype)
240 Returns the size of the given Astro::FITS::CFITSIO datatype
241 constant (e.g., "Astro::FITS::CFITSIO::TSHORT()").
242
244 FIXME
245
247 Pete Ratzlaff <pratzlaff@cfa.harvard.edu>, with a great deal of code
248 taken from Karl Glazebrook's PGPLOT module.
249 Contributors include:
251 Diab Jerius, <djerius@cpan.org>
253 general improvements
254 Tim Jenness, <t.jenness@jach.hawaii.edu>
256 convenience routines
257 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 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/
267perl v5.36.0 2022-07-22 CFITSIO(3)