/ 
CFITSIO-0.92
/ CFITSIO

NAME

CFITSIO - Perl extension for using the CFITSIO library

SYNOPSIS

use CFITSIO;
use CFITSIO qw( :longnames );
use CFITSIO qw( :shortnames );
use CFITSIO qw( :constants );

DESCRIPTION

Perl interface to William Pence's CFITSIO subroutine library. For more information on CFITSIO, see http://heasarc.gsfc.nasa.gov/fitsio.

This module attempts to provide a wrapper for nearly every CFITSIO routine, while retaining as much CFITSIO behavior as possible. As such, one should be aware that it is still somewhat low-level, in the sense that handing an array which is not the correct size to a routine like fits_write_img() may cause SEGVs.

My goal is to eventually use these routines to build a more Perl-like interface to many common tasks such as reading and writing of images and ASCII and binary tables.

CFITSIO API MAPPING

CFITSIO.pm allows one to use either the long or short name forms of the CFITSIO routines. These work by using the exact same form of arguments as one would find in an equivalent C program.

There is also an object-oriented API which uses the same function names as the long-name API, but with the leading "fits_" stripped. To get a CFITSIO "object" one would call open_file(), create_file() or create_template():

my $status = 0;
my $fptr = CFITSIO::open_file($filename,CFITSIO::READONLY(),$status);

$fptr->read_key_str('NAXIS1',$naxis1,undef,$status);

Note that the object-oriented forms of function names are only available for those CFITSIO routines which demand a fitsfile* data-type as the first argument.

NAME SPACE

All CFITSIO routines, with the exception of fits_iterate_data() and fits_open_memfile(), are available in both long and short name forms (e.g., fits_read_key <=> ffgky), as well as all constants defined in the fitsio.h header file. This raises the possibility of your name space being invaded by nearly 1000 function and constant names.

To deal with this situation, CFITSIO.pm makes use of the Exporter package support for %EXPORT_TAGS. You can import the long-named functions with

use CFITSIO qw( :longnames );

and the short-named routines with

use CFITSIO qw( :shortnames );

Constants are actually implemented as AUTOLOADed functions, so TSTRING, for instance, would be accessed via CFITSIO::TSTRING(). Alternatively you can

use CFITSIO qw( :constants );

which would allow you to simply say TSTRING.

DATA STORAGE DETAILS

Input Variables

If a routine expects an N-dimensional array as input, and you hand it a reference to a scalar, then CFITSIO.pm simply uses the data in the scalar which the argument is referencing. Otherwise it expects the argument to be a Perl array reference whose total number of elements satisfies the input demands of the corresponding C routine. CFITSIO.pm then unpacks the array reference into a format that the C routine can understand. If your input array does not hold enough data for the C routine then a segfault is likely to occur.

CFITSIO functions which take an optional NULL pointer - indicating no output in that place is desired - can instead be given an undef. In other words, the following C and Perl statements which read a keyword but ignore the comment would be roughly equivalent:

fits_read_key_lng(fptr,key,&value,NULL,&status);

fits_read_key_lng($fptr,$key,$value,undef,$status);

Output Variables

Calling CFITSIO routines which read data from FITS files causes the output variable to be transformed into a Perl array of the appropriate dimensions. The exception to this is if one wants the output to be in the machine-native format (e.g., for use with PDL). In this case you can use the routine PerlyUnpacking(0). Then all output variables will become scalars containing the appropriate data. The exception here is with routines which read arrays of strings (e.g., fits_read_col_str()). In this case the output is again a Perl array reference.

EXAMPLES

Take a look at testprog/testprog.pl under the distribution directory. It should produce output identical to testprog.c which comes with the CFITSIO library. Additionally, the versions named testprog_longnames.pl, testprog_OO.pl and testprog_pdl.pl test the long-name and object-oriented APIs, and machine-native unpacking with PDL.

There is also an examples/ directory with scripts which do the following:

image_read.pl

reads a FITS primary image and displays it using PGPLOT

image_read_pdl.pl

same as above, but uses machine-native unpacking with PDL

bintable_read_pdl.pl

reads binary table column into PDL object, makes histogram and plots it

CONSIDERATIONS

Ensure your input arrays contain enough data

The caller is responsible for ensuring that the input arrays given to CFITSIO routines are large enough to satisfy the access demands of said routines. For example, if you tell fits_write_col() to write a data column containing 100 elements, your Perl array should contain at least 100 elements. Segfaults abound, so beware!

maxdim semantics

Some CFITSIO routines take a parameter named something like 'maxdim', indicating that no more than that many elements should be placed into the output data area. An example of this would be fits_read_tdim(). In these cases CFITSIO.pm will automatically determine how much storage space is needed for the full amount of output possible and the caller's input value for that argument will essentially be ignored. This is for convenience, and should be considered a feature. Currently the routines for which this is done are fits_read_atblhdr, fits_read_btblhdr, fits_read_imghdr, fits_decode_tdim, fits_read_tdim and fits_test_expr.

Output arrays remain as undisturbed as possible

For routines like fits_read_col(), CFITSIO unpacks the output into a Perl array reference (unless PerlyUnpacking(0) has been called, of course). Prior to doing this, it ensures the scalar passed is a reference to an array large enough to hold the data. If the argument is an array reference which is too small, it expands the array pointed to appropriately. But, if the array is large enough already, the data are just unpacked into the array. The upshot: If you call fits_read_col(), telling it to read 100 data elements, and the array you are placing the data into already has 200 elements, then after fits_read_col() returns your array will still have 200 elements, only the first 100 of which actually correspond to the data read by the routine.

In more succinct language:

@output = (0..199);
fits_read_col_lng($fptr,2,1,1,100,0,\@output,$anynul,$status);

# @output still has 200 elements, only first 100 are from FITS
# file

EXTRA COMMANDS

Some extra commands that use sets of CFITSIO routines are supplied to simplify some standard tasks:

fits_read_header(filename)

This command reads in a primary fits header from the specified filename and returns the header as a hash reference and a status (when called in an array context) or simply a hash reference (when called in a scalar context):

($hash_ref, $status) = fits_read_header ($file);
$hash_ref = fits_read_header($file);

An object-oriented interface is also provided for reading headers from FITS files that have already been opened.

$fitsfile = CFITSIO::open_file($file);
$hash_ref = $fitsfile->read_header;
($hash_ref, $status) = $fitsfile->read_header;

BUGS

  • FIXME

AUTHOR

Pete Ratzlaff <pratzlaff@cfa.harvard.edu>, with a great deal of code recycled from Karl Glazebrook's PGPLOT module.

Contributors include:

Tim Jenness <t.jenness@jach.hawaii.edu>

convenience routines