/ 
CFITSIO-0.50
/ 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, although you probably won't need that much funtionality. One should also 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);

my $naxis1;

$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 * datatype as the first argument.

Namespace

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 namespace being invaded by nearly 1000 funtion and constant names.

To deal with this situation, CFITIO.pm makes use of the Exporter class 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. Otherwise it unpacks the array into a format that the C routine can understand.

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 would be roughly equivalent:

fits_read_col_int(fptr,key,value,NULL,&status)

fits_read_col_int($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 the testprog/testprog.pl under the distribution directory. It should produce output identical to the testprog.c which comes with the CFITSIO library. Actually, that's not quite true - there will be a difference in line 5 of the output, but it is inconsequential. Additionally, the versions named testprog_longnames.pl and testprog_OO.pl test the long-name and object-oriented APIs, respectively.

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

image_read.pl

reads an image of M51 (attributed to whom???) 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

BUGS

  • testprog.pl segfaults at various places on different architectures. Search for 'PROBLEM' in the script to see my comments on Linux and Solaris. Certainly there is still work to be done.

  • Have not tested the PDL-compatible unpacking stuff much. Performed a read and imag() of m51.fits successfully though. See examples/image_read_pdl.pl.

AUTHOR

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

SEE ALSO

perl(1).