FITS

NAME

PDL::IO::FITS -- Simple FITS support for PDL

SYNOPSIS

 use PDL;
 use PDL::IO::FITS;

 $a = rfits('foo.fits');          # read a FITS file

 $a->wfits('bar.fits');           # write a FITS file

DESCRIPTION

This module provides basic FITS support for PDL, in the sense of reading and writing whole FITS files. (For more complex operations, such as prefiltering rows out of tables or performing operations on the FITS file in-place on disk), you can use the Astro::FITS::CFITSIO module that is available on CPAN.

Basic FITS image files are supported, along with BINTABLE and IMAGE extensions.

AUTHOR

Copyright (C) Karl Glazebrook and Craig DeForest, 1997-2003. There is no warranty. You are allowed to redistribute and/or modify this software under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be pasted into in this file.

FUNCTIONS

rfits()

Simple piddle FITS reader.

  $pdl = rfits('file.fits');   # Read a simple FITS image

Suffix magic:

  $pdl = rfits('file.fits.gz'); # Read a file with gunzip(1)
  $pdl = rfits('file.fits.Z');  # Read a file with uncompress(1)

  $pdl = rfits('file.fits[2]');    # Read 2nd extension
  $pdl = rfits('file.fits.gz[3]'); # Read 3rd extension
  @pdls = rfits('file.fits');      # Read primary data and extensions

In list context, "rfits" reads the primary image and all possible extensions, returning them in the same order that they occurred in the file. In scalar context, the default is to read the primary HDU. One can read other HDU's by using the [n] syntax, the second one is [1]. Currently recognized extensions are IMAGE and BINTABLE. (See the addendum on EXTENSIONS for details).

FITS image headers are stored in the output PDL and can be retrieved with hdr or gethdr. The hdrcpy flag of the PDL is set so that the header is copied to derived piddles by default.

The header is a hash whose keys are the keywords in the FITS header. If you have the ``Astro::FITS::Header'' module installed, the header is actually a tied hash to a FITS header object, which can give you more control over card order, comment fields, and variable types. (see Astro::FITS::Header for details).

The header keywords are converted to uppercase per the FITS standard. Access is case-insensitive on the perl side, provided that Astro::FITS::Header is installed.

Keyword-associated comments in the headers are stored as under the hash key "<keyword>_COMMENT". All HISTORY cards in the header are collected into a single multiline string stored in the "HISTORY" key. All COMMENT cards are similarly collected under the "COMMENT" key.

BSCALE/BZERO

If the BSCALE and/or BZERO keywords are set, they are applied to the image before it is returned. The returned PDL is promoted as necessary to contain the multiplied values, and the BSCALE and BZERO keywords are deleted from the header for clarity. If you don't want this type of processing, set 'bscale=>0' in the options hash.

BINTABLE EXTENSIONS

Binary tables are handled.

The return value for a binary table is a hash ref containing the names of the columns in the table (in UPPER CASE as per the FITS standard). Each element of the hash contains a PDL (for numerical values) or a perl list (for string values). The PDL's 0th dimension runs across rows; the 1st dimension runs across the repeat index within the row (for rows with more than one value).

Thus, if your table contains a column named "FOO" with type "5D", the expression

  $a->{FOO}->((2))

returns a 5-element double-precision PDL containing the values of FOO from the third row of the table.

The header of the table itself is parsed as with a normal FITS HDU, and is returned in the element 'hdr' of the returned hash. You can use that to presere the original column order, if you like.

Because different columns in the table might have identical names, the binary table reader practices collision avoidance. If you have multiple columns named ``FOO'', then the first one encountered (numerically) gets the name ``FOO'', the next one gets ``FOO_1'', and the next ``FOO_2'', etc. The appropriate TTYPEn fields in the header are changed to match the renamed column fields.

Scaling and zero-point adjustment are performed as with BSCALE/BZERO: the appropriate keywords are deleted from the as-returned header. To avoid this behavior, set 'bscale=>0' in the options hash.

If a FITS file contains the "BLANK" keyword (and has "BITPIX > 0"), the piddle will have its bad flag set, and those elements which equal the "BLANK" value will be set bad. For "BITPIX < 0", any NaN's are converted to bad (if necessary).

rfitshdr()

Read only the header of a FITS file or an extension within it.

This is syntactic sugar for the "data="0> option to rfits.

See rfits for details on header handling. rfitshdr() runs the same code to read the header, but returns it rather than reading in a data structure as well.

wfits()

Simple PDL FITS writer

  wfits $pdl, 'filename.fits', [$BITPIX];
  $pdl->wfits('foo.fits',-32);

Suffix magic:

  # Automatically compress through pipe to gzip
  wfits $pdl, 'filename.fits.gz';
  # Automatically compress through pipe to compress 
  wfits $pdl, 'filename.fits.Z';

$BITPIX is optional and coerces the output format.

Header handling:

If $pdl has a FITS header attached to it (actually, any hash that contains a SIMPLE=>T keyword), then that FITS header is written out to the file. The image dimension tags are adjusted to the actual dataset. If there's a mismatch between the dimensions of the data and the dimensions in the FITS header, then the header gets corrected and a warning is printed.

For integer types (ie "BITPIX > 0"), the "BLANK" keyword is set to the bad value. For floating-point types, the bad value is converted to NaN (if necessary) before writing.