CCfits Documentation

2.0

CCfits-2.0 requires cfitsio version 3.02 or later Return To CCfits Home Page

Introduction

CCfits is an object oriented interface to the cfitsio library. cfitsio is a widely used library for manipulating FITS (Flexible Image Transport System) formatted files. This following documentation assumes prior knowledge of the FITS format and some knowledge of the use of the cfitsio library, which is in wide use, well developed, and available on many platforms.

For information about FITS and cfitsio, refer to:

• Details about the FITS format and the current standard
• Home page for the cfitsio library

The CCfits library provides an interface that allows the user to manipulate FITS format data through the high-level building blocks of FITS files and Header-Data Units (HDUs). The implementation is designed to hide the details of performing FITS I/O from the user, who will write calls that manipulate FITS objects by passing filenames and lists of strings that represent HDUs, keywords, image data and data columns. Unlike cfitsio, which typically requires several calls to access data (e.g. open file, move to correct header, determine column containing table data, read data) CCfits is designed to make reading data atomic. For example, it exploits internally existing optimization techniques for FITS I/O, choosing the optimal reading strategy as available [see the cfitsio manual, Chapter 13] when data are read on initialization. Data written by CCfits will also be compliant with the FITS standard by specification of class constructors representing FITS dataset elements.

CCfits necessarily works in a fundamentally different way than cfitsio. The general pattern of usage for CCfits is: create a FITS object, which either opens a disk file or creates a new disk file, create references to existing or new HDU objects within it, and manipulated the data through the references. For files with Write access the library is designed to keep the FITS object on disk in sync with the memory copy. The additional memory copy increases the resources required by a calling program in return for some flexibility in accessing the data.

About this Manual

This document lays out the specification for the CCfits library.

The hyperlinks below document the installation procedure, and the demonstration program cookbook which gives examples of usage with comments.

• Installing the Package
• Getting Started
• What's Present, What's Missing, and Calling CFITSIO
• Implementation Notes

Release Notes For Version 2.0 Feb 2008

Enhancements to CCfits:

• Checksum Capability: 4 checksum related functions have been added to the HDU class, which now allows users to set and verify checksums directly from inside CCfits.
• Capturing Error Messages: The FitsException base class now stores its output error message, and it can be retrieved from any of the exception subclass objects with a call to the new FitsException::message() function.
• Improved Keyword Handling: New functions copyAllKeys, keywordCategories, and a second addKey function have been added to the HDU class. The Keyword class now offers a public setValue function to modify an existing keyword. Also the class member documentation for keyword related functions has been upgraded and expanded.
• Image Scaling: In the HDU class (for instances of its PHDU and image ExtHDU subclasses), scale and zero set functions can now write BSCALE and BZERO keywords to the file. A new suppressScaling function has been added to temporarily turn off scaling. The ImageExt<T> class has also been added to the documentation.
• Miscellaneous New Functions:Table::getRowsize() (submitted by Patrik Jonsson), Fits::fitsPointer(), Column::parent().

Bug Fixes:

• FITS constructor in Write mode caused a segmentation fault when used on read-only files. (Reported by Gerard Zins)
• Column write functions were not turning off NULL checking even when the nulval pointer was set to 0. (Reported by Gerard Zins)
• For the FITS constructor which takes an existing FITS object as an argument, when given the filename of an existing file (and without the '!' specifier), it places a new primary HDU in the first extension. It shouldn't allow a write operation at all in this case. (Reported by Andy Beardmore)
• Some additional include statements are needed for compilation on a test version of g++4.3 (Reported by Aurelien Jarno)

Backwards Compatibility Issues:

• The following documented public access member functions have now been removed or made protected/private. As these functions were either never fully implemented or could not successfully be used from external code, it is hoped that these removals will not break any pre-existing code: FITS::clone, HDU::setKeyWord, the HDU::bitpix set function, the Keyword class constructors.

For a more complete listing, see the CHANGES file distributed with the software. For earlier versions, see Previous Release Notes.

Authors and Acknowledgements

CCfits was written as part of a re-engineering effort for the X-Ray data analysis program, XSPEC. It was designed using Rational Rose and originally implemented on a Solaris platform by Ben Dorman to whom blame should be attached. Sandhia Bansal worked on part of the implementation and, and Paul Kunz (pfkeb@slac.stanford.edu) wrote the configuration scheme and dispensed helpful advice: both are also thanked profusely for the port to Windows2000/VC++.net. Thanks to R. Mathar (MPIA) and Patrik Jonsson (Lick Obs.) for contributing many helpful suggestions and bug reports, and ports to HP-UX and AIX respectively.

CCfits is currently maintained by Craig Gordon and Bryan Irby (ccfits@heasarc.gsfc.nasa.gov). Suggestions and bug reports are welcome, as are offers to fill out parts of the implementation that are missing. We are also interested in knowing which parts of cfitsio that are not currently supported should be the highest priority for future extensions.

---