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