Astro::FITS::CFITSIO::Simple This module presents an uncomplicated interface to reading (and eventually writing) FITS files with the CFITSIO library. It attempts to perform the intuitive action when left to its own devices, but much of its behavior can be controlled by an application. Reading FITS files rdfits reads numeric FITS data into PDL objects (piddles). String data (from tables) are stored in ordinary Perl arrays; references to those are returned. It recognizes image (primary or extension) and binary or ASCII tables. rdfits pays attention to what it is asked to read as well as the context in which it was called (i.e., whether an array or a scalar was requested). The default behavior when reading data from a single HDU (the default) is as follows: * An image is always returned as a single piddle, regardless of the calling context. $img = rdfits( 'image.fits' ); * Table data are returned as a hash if no column names are specified. %table = rdfits( 'table.fits' ); In this case all columns are returned. However, if a list of column names prefixed by the "-" character is given, these columns will *not* be returned. For example: %table = rdfits( 'table.fits', qw/ -status -boring / ); "Subtractive" column designations may not be mixed with "additive" column designations. * Table data are returned as a list if column names are specified and rdfits was called in an array (list) context. @coldata = rdfits( 'table.fits', 'col1', 'col2' ); * If a single column is read and rdfits is called in a scalar context, the data are returned as a scalar (piddle or arrayref, depending upon data type). $coldata = rdfits( 'table.fits', 'col1' ); Some of this behavior may be changed using the "rethash" option. Normally rdfits maps the FITS column type (double, long, etc) to the best matched PDL type. This may be overridden (for instance to promote floats to doubles) using the "dtypes" or "defdtype" options. Bit columns are a bit different. (See "Reading Bit Data"). rdfits can optionally return the full FITS header. If an image is read, the resultant piddle's header is set to a hash tied to a Astro::FITS::Header object. For most intents and purposes, this is just like an ordinary piddle header. $pdl = rdfits( 'image.fits' ); print $pdl->gethdr->{HDUNAME}; Retrieving the header for table data is a little more complicated. See the rethdr option below for more information. See Astro::FITS::Header for more information on its representation of FITS headers. Reading Bit Data Table data with type BIT are by default mapped onto a PDL type which best matches the FITS element size, with the packing of the bits preserved. The user may override this type using the "dtypes" or "defdtype" options (see the description under "Table Options" below). Another option is to treat each bit as an independent quantity, with each bit stored in its own piddle element. This may be accomplished by specifying the PDL type (via "dtypes" or "defdtype") as the string "logical". Bits will then be stored as bytes, with each byte representing a bit. Functions rdfits rdfits takes a single mandatory parameter which is either a file name or a CFITSIO file pointer. With no other information provided, it reads data from the first available (and recognizable) HDU. If additional scalar values are provided, they are assumed to be column names, and rdfits will search only for tables. The data are stored as described in "Reading FITS files". rdfits "croak()'s" upon error. rdfits's behavior can be controlled via a hashref passed in as the last argument: rdfits($file, [...], \%opts ); There are three categories of options: those which affect how rdfits finds an HDU to read; those which affect reading tables; and those which affect reading of columns. HDU options extname This may be set to the exact name of the HDU to read. extver This may be set to the version of the HDU to read. It requires that "extname" be set as well. hdunum The index of the HDU in the file. This may also be appended to the file name in brackets, i.e. "file[1]". hdutype The type of HDU to read. This may be one of the following strings: img image - read an image binary bintbl - read a binary table ascii - read an ascii table table - read any type of table any - read any type of data If a particular HDU is requested and the HDU type doesn't match, rdfits will croak. resethdu This takes a boolean value. If true, and rdfits was passed a CFITSIO file pointer, the HDU pointer is stored and reset just before rdfits returns. Defaults to false. Table Options These options are accepted only when reading tables. They will cause an error otherwise. dtypes defdtype Normally, rdfits will create the best fit PDL type for each column read. A default datatype for all columns can be set with "defdtype". Individual columns' datatypes can be set with "dtypes". "defdtype" takes a single value, a PDL::Type object. %data = rdfits( $file, { defdtype => double } ); "dtypes" takes a reference to a hash whose keys are the column names and whose values are "PDL::Type" objects of the type wanted. For example: ($a,$b,$c) = rdfits( $file, qw/ a b c /, { dtypes=>{ a=>float, c=>short } } ); This will force the PDL type of $a to float, and $c to short, while choosing the best match datatype for $b. It is not possible for the user to specify dtypes for "LOGICAL" and "ASCII" type columns. "BIT" columns are special; see "Reading Bit Data" above. ninc The number of rows to read incrementally. By default, this number is set according to "fits_get_rowsize()" for the table being read. This is best left unset. nullval The value with which to fill in null data values. If PDL has been built with bad value support, it defaults to the bad value for the data type. If not, it defaults to 0, which signals CFITSIO to ignore null pixels. rethash %data = rdfits('foo.fits', @cols, { rethash=>1 }); Normally when rdfits is invoked with a list of columns to read, it returns a list of piddles. This Boolean option indicates that it should return a hash (not a hashref) whose keys are the lower-cased column names with the corresponding piddles for values. This is the default mode if no columns are specified. rethdr This Boolean option indicates that the HDU's header should be returned as well as the data. * If the data are returned in a list, the header will be the first element of the list: ($hdr, @data ) = rdfits( 'foo.fits', @cols, { rethdr => 1 } ); The header is returned as an Astro::FITS::Header object. * If the data are returned as a hash, an additional element in the hash is added, with a key of "_hdr". # return the HDU header %hash = rdfits( 'foo.fits', @cols, { rethash => 1, rethdr => 1 } ); $hdr = $hash{_hdr}; The header is returned as an Astro::FITS::Header object. * If a single column is requested, and it is returned in a scalar, the returned piddle's header is set to a hash tied to a Astro::FITS::Header object. For most intents and purposes, this is just like an ordinary piddle header. $pdl = rdfits( 'foo.fits', $col, { rethdr => 1 } ); print $pdl->gethdr->{HDUNAME}; See Astro::FITS::Header for more information on tieing to that class. retinfo %data = rdfits('foo.fits', @cols, { retinfo=>1 }); This option specifies that the data will be returned as a hash, keyed off of the lowercased column names. The values in the hash are themselves hashes, with these elements: data The data read from the file idx The index of the column in the file (unary based) hdr A hashref containing the FITS keywords which are specific to the column (e.g., "TTYPE", "TLMAX", "TUNIT", etc.). The keys for these are the keyword names without the trailing column index. For example, %data = rdfitsTable('foo.fits', 'x', { retinfo => 1 }); might result in the equivalent hash of $data{'x'} = { idx => 11, data => PDL..., hdr => { ttype => 'x', cuni => 'deg', tlmax => '8.1925000E+03', tcdlt => '-1.3666666666667E-04', tunit => 'pixel', tform => '1E', tlmin => '5.0000000E-01', tcrvl => '3.2972102733253E+02', tcrpx => '4.0965000000000E+03', tctyp => 'RA---TAN', }, }; rfilter %data = rdfitsTable('foo.fits', 'x', { rfilter => 'X < 3' } }); This specifies a CFITSIO-style row filtering specification. Only the rows matching this filter will be in the output variables. The filter has access to *all* of the columns in the HDU, not just the ones being read out. This can radically reduce memory requirements if a complicated row selection is made. status This option indicates that progress status should be output. status can take one of the following values: a scalar If true, a progress bar is written to the standard error stream. If the Term::ProgressBar module is available, a fairly nice one is emitted. (The more primitive style may be forced by setting the value to -1). a file glob In this case output is sent to the specified file handle. an object reference If the object supports the print() and flush() methods, these are called to output the progress status. (Nice objects are, for example IO::File objects). a code reference The code reference is called with two parameters: the number of rows read, and the total number to be read. Typically output is produced approximately at 1% increment steps. Image Options These options are accepted only when reading images. They will cause an error otherwise. dtype Normally, rdfits will create the best fit PDL type for the image data. The application can override the output datatype with this option. The argument should be a "PDL::Type" object. For example: $float_img = rdfits( $file, { dtype => float } ); nullval The value with which to fill in null data values. If PDL has been built with bad value support, it defaults to the bad value for the data type. If not, it defaults to 0, which signals CFITSIO to ignore null pixels. rdfitstbl This is a thin wrapper around rdfits which forces a single table to be read. It is equivalent to invoking rdfits with the options. { hdutype => 'table' } It has the same calling convention as rdfits. rdfitsimg This is a thin wrapper around rdfits which forces a single table to be read. It is equivalent to invoking rdfits with the options { hdutype => 'image' } It has the same calling convention as rdfits. INSTALLATION This is a Perl module distribution. It should be installed with whichever tool you use to manage your installation of Perl, e.g. any of cpanm . cpan . cpanp -i . Consult http://www.cpan.org/modules/INSTALL.html for further instruction. Should you wish to install this module manually, the procedure is perl Build.PL ./Build ./Build test ./Build install COPYRIGHT AND LICENSE This software is Copyright (c) 2008 by Smithsonian Astrophysical Observatory. This is free software, licensed under: The GNU General Public License, Version 3, June 2007