NAME

CFITSIO - Perl extension for using the CFITSIO library

SYNOPSIS

use CFITSIO;

DESCRIPTION

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

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.

Available Routines

As stated above, nearly every routine is available, in the long-name form (i.e., fits_read_img instead of ffgpv). You would use the exact same arguments as in a C program, and the input and output variables are magically transformed into whatever the C program would have intended.

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.

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.pl in the distribution directory. It should produce output identical to the testprog.c which comes with the CFITSIO library.

BUGS

fits_open_file causes SEGV on Solaris 2.5, Perl 5.004. This is troubling because the xsub is very simple and doesn't even rely on any of the data packing/unpacking routines.

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 much 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.pl.

AUTHOR

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

SEE ALSO

perl(1).

Exported constants

ANGLE_TOO_BIG
ANY_HDU
ARRAY_TOO_BIG
ASCII_TBL
BAD_ATABLE_FORMAT
BAD_BITPIX
BAD_BTABLE_FORMAT
BAD_C2D
BAD_C2F
BAD_C2I
BAD_COL_NUM
BAD_DATATYPE
BAD_DATA_FILL
BAD_DATE
BAD_DECIM
BAD_DIMEN
BAD_DOUBLEKEY
BAD_ELEM_NUM
BAD_F2C
BAD_FILEPTR
BAD_FLOATKEY
BAD_GCOUNT
BAD_GROUP_ID
BAD_HDU_NUM
BAD_HEADER_FILL
BAD_I2C
BAD_INTKEY
BAD_KEYCHAR
BAD_LOGICALKEY
BAD_NAXES
BAD_NAXIS
BAD_OPTION
BAD_ORDER
BAD_PCOUNT
BAD_PIX_NUM
BAD_ROW_NUM
BAD_ROW_WIDTH
BAD_SIMPLE
BAD_TBCOL
BAD_TDIM
BAD_TFIELDS
BAD_TFORM
BAD_TFORM_DTYPE
BAD_URL_PREFIX
BAD_WCS_PROJ
BAD_WCS_VAL
BINARY_TBL
BYTE_IMG
CASEINSEN
CASESEN
COL_NOT_FOUND
COL_NOT_UNIQUE
COL_TOO_WIDE
DOUBLENULLVALUE
DOUBLE_IMG
DRIVER_INIT_FAILED
END_JUNK
END_OF_FILE
FALSE
FILE_NOT_CLOSED
FILE_NOT_CREATED
FILE_NOT_OPENED
FLEN_CARD
FLEN_COMMENT
FLEN_ERRMSG
FLEN_FILENAME
FLEN_KEYWORD
FLEN_STATUS
FLEN_VALUE
FLOATNULLVALUE
FLOAT_IMG
GROUP_NOT_FOUND
GT_ID_ALL
GT_ID_ALL_URI
GT_ID_POS
GT_ID_POS_URI
GT_ID_REF
GT_ID_REF_URI
HDU_ALREADY_MEMBER
HDU_ALREADY_TRACKED
HEADER_NOT_EMPTY
IDENTICAL_POINTERS
IMAGE_HDU
InputCol
InputOutputCol
KEY_NO_EXIST
KEY_OUT_BOUNDS
LONG_IMG
MAXHDU
MEMBER_NOT_FOUND
MEMORY_ALLOCATION
NEG_AXIS
NEG_BYTES
NEG_FILE_POS
NEG_ROWS
NEG_WIDTH
NOT_ASCII_COL
NOT_ATABLE
NOT_BTABLE
NOT_GROUP_TABLE
NOT_IMAGE
NOT_LOGICAL_COL
NOT_POS_INT
NOT_TABLE
NOT_VARI_LEN
NO_BITPIX
NO_END
NO_GCOUNT
NO_MATCHING_DRIVER
NO_NAXES
NO_NAXIS
NO_NULL
NO_PCOUNT
NO_QUOTE
NO_SIMPLE
NO_TBCOL
NO_TFIELDS
NO_TFORM
NO_WCS_KEY
NO_XTENSION
NULL_INPUT_PTR
NUM_OVERFLOW
OPT_CMT_MBR
OPT_CMT_MBR_DEL
OPT_GCP_ALL
OPT_GCP_GPT
OPT_GCP_MBR
OPT_MCP_ADD
OPT_MCP_MOV
OPT_MCP_NADD
OPT_MCP_REPL
OPT_MRG_COPY
OPT_MRG_MOV
OPT_RM_ALL
OPT_RM_ENTRY
OPT_RM_GPT
OPT_RM_MBR
OVERFLOW_ERR
OutputCol
PARSE_BAD_COL
PARSE_BAD_OUTPUT
PARSE_BAD_TYPE
PARSE_LRG_VECTOR
PARSE_NO_OUTPUT
PARSE_SYNTAX_ERR
READONLY
READONLY_FILE
READWRITE
READ_ERROR
SAME_FILE
SEEK_ERROR
SHORT_IMG
TBIT
TBYTE
TCOMPLEX
TDBLCOMPLEX
TDOUBLE
TFLOAT
TINT
TLOGICAL
TLONG
TOO_MANY_DRIVERS
TOO_MANY_FILES
TOO_MANY_HDUS_TRACKED
TRUE
TSHORT
TSTRING
TUINT
TULONG
TUSHORT
ULONG_IMG
UNKNOWN_EXT
UNKNOWN_REC
URL_PARSE_ERROR
USE_MEM_BUFF
USHORT_IMG
VALIDSTRUC
VALUE_UNDEFINED
WCS_ERROR
WRITE_ERROR
ZERO_SCALE