/*! \mainpage CCfits Documentation
CCfits requires CFITSIO
\htmlonly Return To CCfits Home Page

\endhtmlonly \section intro 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. \htmlonly For information about FITS and cfitsio, refer to: \endhtmlonly \latexonly Readers unfamiliar with FITS but in need of performing I/O with FITS data sets are directed to the first cfitsio manual, available at {\it http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html} Information about the FITS file format and the current standard is available from {\it http://fits.gsfc.nasa.gov} \endlatexonly 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. \section about About this Manual This document lays out the specification for the CCfits library. \latexonly The next sections document the installation procedure and the demonstration program {\it 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. \endlatexonly \htmlonly The hyperlinks below document the installation procedure, and the demonstration program cookbook which gives examples of usage with comments. \endhtmlonly \section rel1 Release Notes for Version 2.5 Jan 2016 Backwards Compatibility Issues: - As part of an effort to allow tables to hold multiple columns with the same name (see "Enhancements" section), the Table class now stores Column objects in an internal multimap rather than a map. This affects the public interface in 2 places: the ExtHDU::column() and Table::column() accessor functions. These used to return a std::map reference, but now return a std::multimap (using new typedef 'ColMap' defined in CCfits.h). - Removed the ImageExt::image() accessor function from the public interface. This was only ever intended for internal use. Enhancements: - Added scripts for building with the CMake system, primarily intended for builds on Windows platforms. - New functions: ExtHDU::copyColumn, HDU::readNextKey, HDU::resetImageRead, and a new Column::read overload for returning a single row into a std::vector. - Keyword reads can now convert numerical types into strings. - Added support for variable-width string columns (with new ValueType enum = VTstring). - Image write functions are now allowed to dynamically increase the size of the outer dimension as needed. The corresponding NAXIS keyword will be updated automatically. - Tables can now handle having multiple columns with the same column name. (Also see "Backwards Compatibility" section.) - Added support for read/write of LONGLONG types for images. - Added handling of 'D' exponent notation when reading keyword values with floating-point types. Bug Fixes: - Improved memory caching when reading images, reducing the number of unnecessary disk reads. - Removed header inclusion of config.h due to potential conflicts with users' customized autotools config.h files. - HDU's '<<' output operator was not showing output for the highest numbered axis. - Removed unused NewColumn.h code file. - Fixed memory leak in internal Column::setLimits function. - Added #include statements to various files, the absence of which was causing compilation failures on recent Windows Visual Studio builds. - Added missing 'break' statement for Tlonglong case in internal FITSType2String function. - Replaced a valarray operation in ColumnVectorData.h file which caused a compiler glitch on certain Mac platforms. (This was previously released as a patch.) - Fix made to HDU's getHistory and getComments internal search algorithm. - Fix to FITS::addTable function for case where new table shares its name with a pre-existing HDU but has a different version number. - Fix to memory management for certain Column write operations. For a more complete listing, see the CHANGES file distributed with the software. For earlier versions, see \ref releases. \section ack 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. */ /*! \page implementation Implementation Notes This section comments on some of the design decisions for CCfits. We note the role of cfitsio in CCfits as the underlying "engine," the use of the C++ standard library. We also explain some of the choices made for standard library containers in the implementation - all of which is hidden from the user [as it should be]. \subsection wrapper CCfits wraps, not replaces, cfitsio. Most importantly, the library wraps rather than replaces the use of cfitsio library; it does not perform direct disk I/O. The scheme is designed to retain the well-developed facilities of cfitsio (in particular, the extended file syntax), and make them available to C++ programmers in an OO framework. Some efficiency is lost over a 'pure' C++ FITS library, since the internal C implementation of many functions requires processing if blocks or switch statements that could be recoded in C++ using templates. However, we believe that the current version strikes a resonable compromise between developer time, utility and efficiency. \subsection ansi ANSI C++ and the Standard C++ Library The implementation of CCfits uses the C++ Standard Library containers and algorithms [also referred to as the Standard Template Library, (STL)] and exception handling. Here is a summary of the rationale behind the implementation decisions made. */