CCfits  2.6
What's Present, What's Missing, and Calling CFITSIO

What's Present

Most of the functionality of cfitsio described in Chapter 5 of the cfitsio manual is present, although CCfits is designed to provide atomic read/write operations rather than primitive file manipulation. For example, opening and creating FITS files are private operations which are called by reading and writing constructors. Similarly, errors are treated by C++ exception handling rather than returning status codes, and moving between HDUs within a file is a primitive rather than an atomic operation [in CCfits, operations typically call an internal HDU::makeThisCurrent() call on a specific table or image extension, and then perform the requested read/write operation].

Read/Write operations for keys (in the HDU class) are provided; these implement calls to fits_read_key and fits_update_key respectively. In the case of keywords, which have one of five data types (Integer, Logical, String, Floating and Complex), CCfits will handle certain type conversions between the keyword value and the data type of the user-supplied variable. This is described in detail in the Keyword class reference page. In reading image and table data, intrinsic type conversions are performed as in cfitsio with the exception that reading numeric data into character data is not supported. There is an extensive set of member functions supporting equivalents of most of cfitsio's read/write operations: the classes PHDU [primary HDU] and ExtHDU [with subclasses Table and template <typename T>ImageExt<T>], provide multiple overloaded versions of read and write functions. The Column class, instances of which can be held in Table instances [with subclasses AsciiTable and BinTable] has also an extensive set of read/write operations.

A special constructor is provided which creates a new file with the Primary HDU of a source file. A FITS::copy(const HDU&) function copies HDUs from one file into another. Support for filtering table rows by expression is provided by a FITS::filter( ... ) call which may be used to create a new filtered file or overwrite an existing HDU (see cfitsio manual section 5.6.4).

Functions are provided for adding and deleting columns, and inserting and deleting rows in tables.

HDU objects also have functions to implement writing of history, comment and date keys.

Extended file name syntax (chapter 10 of the cfitsio manual) is supported in general, though not the feature which allows the opening of a particular image stored in the row of a table.

What's Not Present

The coordinate library manipulations [cfitsio manual chapter 7] are not supported.

The iterator work functions [cfitsio manual chapter 6] are not supported. Many of the functions provided are easier to implement using the properties of the standard library, since the standard library containers either allow vectorized operations (in the case of valarrays) or standard library algorithms that take iterators or pointers. In some ways the fits_iterate_data function provide an alternative, approach to the same need for encapsulation addressed by CCfits.

The hierarchical grouping routines are not supported.

Explicit opening of in-memory data sets as described in Chapter 9 of the manual is not supported since none of the FITS constructors call the appropriate cfitsio primitives.


To gain any functionality currently missing in CCfits, it is possible of course to call the underlying CFITSIO library functions directly. The CCfits FITS and HDU classes both have the public member function fitsPointer(), which returns the fitsfile pointer required in CFITSIO function calls. One should use caution when doing this however, since any I/O changes made this way will NOT be mirrored in the CCfits FITS object (nor its component objects) associated with the file. Therefore once a FITS object has been bypassed this way, it is safest to just not use that object again, and instead continue calling CFITSIO directly or instantiate a new FITS object that will pick up the current file state.