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 rou‐
19 tine, 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()", "cre‐
36 ate_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 avail‐
45 able for those cfitsio routines which accept a "fitsfile*" data-type as
46 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 "Astro::FITS::CFIT‐
82 SIO::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
92 reference to a scalar, then Astro::FITS::CFITSIO simply uses the data
93 in the scalar which the argument is referencing. Otherwise it expects
94 the argument to be a Perl array reference whose total number of ele‐
95 ments satisfies the input demands of the corresponding C routine.
96 Astro::FITS::CFITSIO then unpacks the array reference into a format
97 that the C routine can understand. If your input array does not hold
98 enough data for the C routine then a segfault is likely to occur.
99 cfitsio functions which take an optional NULL pointer - indicating no
101 output in that place is desired - can instead be given an "undef". In
102 other words, the following C and Perl statements which read a keyword
103 but ignore the comment would be roughly equivalent:
104 fits_read_key_lng(fptr,key,&value,NULL,&status);
106 fits_read_key_lng($fptr,$key,$value,undef,$status);
108 Output Variables
110 Calling cfitsio routines which read data from FITS files causes the
112 output variable to be transformed into a Perl array of the appropriate
113 dimensions. The exception to this is if one wants the output to be in
114 the machine-native format (e.g., for use with PDL). Then all output
115 variables will become scalars containing the appropriate data. The
116 exception here is with routines which read arrays of strings (e.g.,
117 "fits_read_col_str()"). In this case the output is again a Perl array
118 reference.
119 There are two ways to specify how data are retrieved. The behavior can
121 be specified either globally or on a per filehandle basis. The global
122 selection is done by calling the PerlyUnpacking function. This sets
123 the behavior for all file handles which do not explicitly choose not to
124 follow it.
125 # turn ON unpacking into Perl arrays. This is the default
127 PerlyUnpacking(1);
128 # turn OFF unpacking into Perl arrays, i.e. put in machine-native
130 # format
131 PerlyUnpacking(0);
132 # retrieve the current state:
134 $state = PerlyUnpacking();
135 To change the behavior for a particular file handle, use the perlyun‐
137 packing method. The default behavior for a file handle is to track
138 what is done with PerlyUnpacking()
139 # track PerlyUnpacking(). This is the default
141 $fptr->perlyunpacking(-1);
142 # turn ON unpacking into Perl arrays
144 $fptr->perlyunpacking(1);
145 # turn OFF unpacking into Perl arrays
147 $fptr->perlyunpacking(0);
148 # retrieve the current state:
150 $state = $fptr->perlyunpacking;
151
153 Take a look at testprog/testprog.pl under the distribution directory.
154 It should produce output identical to testprog.c which comes with the
155 cfitsio library. Additionally, the versions named testprog_long‐
156 names.pl, testprog_OO.pl and testprog_pdl.pl test the long-name and
157 object-oriented APIs, and machine-native unpacking with PDL.
158 There is also an examples/ directory with scripts which do the follow‐
160 ing:
161 image_read.pl
163 reads a FITS primary image and displays it using PGPLOT
164 image_read_pdl.pl
166 same as above, but uses machine-native unpacking with PDL
167 bintable_read_pdl.pl
169 reads binary table column into PDL object, makes histogram and
170 plots it
171
173 Ensure your input arrays contain enough data
174 The caller is responsible for ensuring that the input arrays given
175 to Astro::FITS::CFITSIO routines are large enough to satisfy the
176 access demands of said routines. For example, if you tell
177 "fits_write_col()" to write a data column containing 100 elements,
178 your Perl array should contain at least 100 elements. Segfaults
179 abound, so beware!
180 maxdim semantics
182 Some cfitsio routines take a parameter named something like
183 '"maxdim"', indicating that no more than that many elements should
184 be placed into the output data area. An example of this would be
185 "fits_read_tdim()". In these cases Astro::FITS::CFITSIO will auto‐
186 matically determine how much storage space is needed for the full
187 amount of output possible. As a result, the arguments expected in
188 Astro::FITS::CFITSIO are slightly different than one would use in a
189 C program, in that the '"maxdim"' argument is unnecessary.
190 Currently the routines for which this is the case are
192 "fits_read_atblhdr()", "fits_read_btblhdr()", "fits_read_imghdr()",
193 "fits_decode_tdim()", "fits_read_tdim()" "fits_test_expr()",
194 "fits_get_img_parm()" and "fits_get_img_size()".
195 Output arrays remain as undisturbed as possible
197 For routines like "fits_read_col()", Astro::FITS::CFITSIO unpacks
198 the output into a Perl array reference (unless PerlyUnpacking(0)
199 has been called, of course). Prior to doing this, it ensures the
200 scalar passed is a reference to an array large enough to hold the
201 data. If the argument is an array reference which is too small, it
202 expands the array pointed to appropriately. But, if the array is
203 large enough already, the data are just unpacked into the array.
204 The upshot: If you call "fits_read_col()", telling it to read 100
205 data elements, and the array you are placing the data into already
206 has 200 elements, then after "fits_read_col()" returns your array
207 will still have 200 elements, only the first 100 of which actually
208 correspond to the data read by the routine.
209 In more succinct language:
211 @output = (0..199);
213 fits_read_col_lng($fptr,2,1,1,100,0,\@output,$anynul,$status);
214 # @output still has 200 elements, only first 100 are from FITS
216 # file
217
219 Some extra commands that use sets of cfitsio routines are supplied to
220 simplify some standard tasks:
221 fits_read_header(filename)
223 This command reads in a primary fits header (unless one is using
224 the extended filename sytax to move to a different HDU on open)
225 from the specified filename and returns the header as a hash refer‐
226 ence and a status (when called in an array context) or simply a
227 hash reference (when called in a scalar context):
228 ($hash_ref, $status) = fits_read_header ($file);
230 $hash_ref = fits_read_header($file);
231 An object-oriented interface is also provided for reading headers
233 from FITS files that have already been opened. In this case, the
234 header read is from the current HDU.
235 $fitsfile = Astro::FITS::CFITSIO::open_file($file);
237 $hash_ref = $fitsfile->read_header;
238 ($hash_ref, $status) = $fitsfile->read_header;
239 sizeof_datatype(datatype)
241 Returns the size of the given Astro::FITS::CFITSIO datatype con‐
242 stant (e.g., "Astro::FITS::CFITSIO::TSHORT()").
243
245 FIXME
246
248 Pete Ratzlaff <pratzlaff@cfa.harvard.edu>, with a great deal of code
249 taken from Karl Glazebrook's PGPLOT module.
250 Contributors include:
252 Tim Jenness <t.jenness@jach.hawaii.edu>
254 convenience routines
255 Tim Conrow <tim@ipac.caltech.edu>
257 function implementations, bug fixes
258perl v5.8.8 2006-06-28 CFITSIO(3)