CCfits Documentation
1.8
CCfits-1.8 requires cfitsio version 3.02 or later
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:
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.
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.
Following sections give a list of what is implemented in CCfits compared to the cfitsio library. For background information and as an example there is a section describing how CCfits is to be used in XSPEC, for which it was originally designed, which may serve to give the reader some insight into the design decisions made.
Changes for CCfits 1.8 release 10/07.
- Fixes made to bugs in Column write and writeArrays functions which were preventing the writing of variable-width columns. Also now allows writing to fixed-width columns with arrays that are shorter than the fixed width.
- The HDU::readAllKeys() function will no longer throw if it is unable to read a particular keyword. Instead it will skip it and move to the next keyword. This was done primarily to prevent it from tripping on undefined keywords.
Changes for CCfits 1.7 release 6/07. Fixes for the following bugs:
- The FITS::copy function merely wrote the copied HDU to the file, but did not allow it to be accessed for further modifications within CCfits.
- When reading compressed images, CCfits should use the ZBITPIX and ZNAXIS keywords rather than BITPIX and NAXIS. (Fix is based on a patch submitted by Patrik Jonsson.)
- The BSCALE keyword was being ignored if the BZERO keyword didn't also exist.
- Cases of out-of-scope usage of std::string's c_str() pointers, could potentially cause crash. (Fix submitted by Jeremy Sanders.)
Changes for CCfits 1.6 release 11/06
- Added capbility to write compressed images, including 6 new wrapper public functions in FITS class.
- In FITS::addImage, corrected the logic which checks for a pre-existing image extension with the same version number.
- CFITSIO 3.02 renamed fitsfile struct member rice_nbits to noise_nbits. Made corresponding change in copyFitsPtr function in FITSUtil.cxx. As it stands, this makes this version of CCfits incompatible with earlier versions of CFITSIO
- In FITS.h definition, removed both friend declarations of HDUCreator Make functions. It seems neither function needs to be a friend, and one of them is actually private. Some compilers don't allow this (report came from MS VisualC++ user).
- Bug fix in Make function of HDUCreator.cxx. When creating a new ImageExt (and not the primary), it was only passing the version number along for float and double types. This causes problems when there is more than 1 image extension with the same name, and it needs the version number to distinguish them.
- A couple of bug fixes to the first/last/stride version of PHDU read image subset. It was not passing the proper parameters to fits_read_subset, and was not always correctly resizing the internal m_image array.
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.
Generated on Fri Oct 12 13:39:38 2007 for CCfits by
1.4.7