# E.S.O. - VLT project 
#
# "@(#) $Id: FitsIO.man3,v 1.1.1.1 2009/03/31 14:11:52 cguirao Exp $" 
#
# This file is processed by the ESO/VLT docDoManPages command to
# produce a man page in nroff, TeX and MIF formats. 
# See docDoManPages(1) for a description of the input format.
# 
# who             when       what
# --------------  ---------  ----------------------------------------
# Allan Brighton  21 Feb 96  Created
#

NAME
FitsIO - C++ Class for Reading, Writing and Managing FITS Images

SYNOPSIS
#include "FitsIO.h"

class FitsIO : public ImageIORep {
...
public:
    FitsIO(int width, int height, int bitpix, double bzero, 
	   double bscale, const Mem& header, const Mem& data,
	   fitsfile* fitsio = NULL);
    ~FitsIO();

    int wcsinit();
    int usingNetBO() const;
    const char* classname() const;

    static FitsIO* read(const char* filename, int memOptions = 0);
    int write(const char *filename) const;

    static const char* check_compress(const char* filename, char* buf, int bufsz, 
				      int& istemp, int decompress_flag = 1, 
				      int bitpix = 0);

    static FitsIO* initialize(Mem& header);
    static FitsIO* initialize(Mem& header, Mem& data);

    static FitsIO* blankImage(double ra, double dec, double equinox, 
			      double radius, int width, int height, 
			      unsigned long color0);

    int get(const char* keyword, double& val) const;
    int get(const char* keyword, float& val) const;
    int get(const char* keyword, int& val) const;
    int get(const char* keyword, long& val) const;
    int get(const char* keyword, unsigned char& val) const;
    int get(const char* keyword, unsigned short& val) const;
    int get(const char* keyword, short& val) const;
    char* get(const char* keyword) const;
    char* get(const char* keyword, char* buf, int bufsz) const;

    static int get(fitsfile*, const char* keyword, double& val);
    static int get(fitsfile*, const char* keyword, float& val);
    static int get(fitsfile*, const char* keyword, int& val);
    static int get(fitsfile*, const char* keyword, long& val);
    static int get(fitsfile*, const char* keyword, unsigned char& val);
    static int get(fitsfile*, const char* keyword, unsigned short& val);
    static int get(fitsfile*, const char* keyword, short& val);
    static char* get(fitsfile*, const char* keyword);

    int getFitsHeader(ostream& os) const;

    int put(const char* keyword, double val, const char* comment = NULL);
    int put(const char* keyword, float val, const char* comment = NULL);
    int put(const char* keyword, int val, const char* comment = NULL);
    int put(const char* keyword, const char* val, const char* comment = NULL);

    int getNumHDUs();
    const char* getHDUType();
    int getHDUNum();
    int setHDU(int num);
    int deleteHDU(int num);

    int getTableDims(long& rows, int& cols);
    char* getTableHead(int col);
    char* getTableValue(long row, int col);
    int getTableColumn(int col, double* values, int numValues);
    int createTable(const char* extname, long rows, int cols,
    int setTableValue(long row, int col, const char* value);
};


DESCRIPTION
This class manages the reading and writing of FITS images, including
ASCII and binary tables, FITS headers and keywords. FITS file access
is based on William Pence's CFITSIO package.  World coordinates
support is based on Doug Mink's WCSSUBS package (also used by
saoimage). The sources from both packages are included in this
package.

This class is a subclass of ImageIORep, which is the internal class
used by class ImageIO for reference counting. The public interface is
generally through the ImageIO class, although class FitsIO may be used
directly in cases where you know that the image is already in FITS
format or you are creating a new image in FITS format. 

Besides reading and writing FITS images, this class can be used to
create a FITS image from data in memory and to create a "blank" image
with World Coordinate information for plotting astronomical objects.

CREATING A FITSIO OBJECT
To create a FitsIO object from a FITS file, use the read method, which
returns a pointer to an allocated FitsIO object given the file name.
If you have the image data in memory, you can use one of the
constructors to create the object.

You can pass a pointer to a FitsIO object to the ImageIO constructor
to create a reference counted ImageIO object, for example:

	ImageIO imio = FitsIO::read(filename);
or
	ImageIO imio = new FitsIO(w, h, type, bzero, bscale, header, data);

COMPRESSION
Images are compressed and decompressed automatically by the read and
write methods based on the file name suffix: ".hfits" for H-compress,
".gzfits" or ".gfits" for gzip compression, and ".cfits" for UNIX
compression. See Compress for details.

IMAGE EXTENSIONS
Methods are provided to query the number of FITS HDUs (header data
units) and switch to a given HDU. You can iterate through a FITS table
by first switching to the HDU containing the table and then calling
one of the HDU methods described below. When switching HDUs, make sure
that the image display code is not still accessing a different HDU.
It might be necessary to save the current HDU number before reading a
FITS table and then restore the HDU settings afterwards in this case.

FITS TABLES
Reading and writing of FITS ASCII and binary tables is supported.
FITS tables may also be created and deleted. (Note this class does not
support the full functionality of the cfitsio library (yet), but only
the features that we needed so far.)

WRITING FITS IMAGES
Care must be taken when modifying FITS image files used with the
FitsIO class, since the files are memory mapped. When using the
"put()" method to insert FITS keywords, the FitsIO class automatically
handles adding new FITS blocks as needed and remapping the file. This
may change the starting location of the FITS image data or extensions.

METHODS
FitsIO(width, height, bitpix, bzero, bscale, header,  data)
	This constructor is called by the static "read" method once
	the FITS file has been read. The parameters are based on
	values read from the FITS header. The header and data
	arguments are instances of class Mem, which uses reference
	counting to manage shared and unshared memory.

read(filename, int memOptions = 0)
	Read a FITS file and return an initialized FitsIO object for
	it, or NULL if there are errors.  If filename is "-", stdin is
	read into a temp image file and used as the input.  The Mem
	class is used to speed up loading the file. The optional
	mem_options argument controls whether the memory is mapped
	read-only or read/write. See class Mem for the available
	options.

write(filename)
	Write the data to a FITS file.

blankImage(ra, dec, equinox, radius, width, height, color0)
	Generate a blank image with a FITS header based on the given
	fields and including support for World Coordinates. RA and DEC
	are specified in degrees. Width and Height are in
	pixels. "color0" is the value to use for the image pixels
	(usually the value for "black").

get(keyword, val)
	Find and set the value for the given FITS keyword and return 0
	if OK (found). This method is overloaded for various data types.

get(keyword)
	Find and return the string value for the given FITS keyword,
	or NULL if not found.

getFitsHeader(os)
	Write an ASCII formatted copy of the FITS header to the given
	stream, format it in 80 char lines and replace any NULL chars
	with blanks.

put(keyword, val, comment)
	Insert the given FITS keyword and value with the given comment
	in the FITS header and return 0 if all is OK. If there is not
	enough space in the FITS header, extend the size of the FITS
	header by one header block and if the header is part of an
	mmap'ed file, rewrite the file with the new enlarged
	header. 

getNumHDUs()
	Return the total number of HDUs (FITS header/data units).

getHDUType()
	Return the type of the current HDU as a string: "image",
	"ascii", or "binary" or NULL if there was as error.

getHDUNum()
	Return the index of the current HDU.

setHDU(num)
	Move to the specified HDU and make it the current one.

deleteHDU(num);
    	Delete the given HDU. All following HDUs are moved to fill the
    	space.

getTableDims(rows, cols)
	Get the dimensions of the current FITS table.

getTableHead(col);
	Return the table heading for the given column, or NULL if
	there is an error. The return value points to static
	storage.

getTableValue(row, col)
	Return the value in the current FITS table at the given row
	and column, or NULL if there was an error.  The returned
	pointer points to static storage and will be overwritten on
	the next call to this method or one of the get(keyword)
	methods.

getTableColumn(col, values, numValues)
	Get the contents of the given column as an array of doubles.
	The caller should pass an array of numValues doubles.

createTable(extname, rows, cols, headings, tform, asciiFlag)
	Create a FITS table and make it the current HDU

	extname gives the name of the table.

	The initial size will be rows x cols entries.

	tform is an array giving the FITS data type for each column
	(For example: 16A, for a 16 char string, see FITS description.)

	If asciiFlag is 1, an ASCII table is created, otherwise a
	binary table.

setTableValue(row, col, value)
	Set the value in the current FITS table at the given row and
	column (For now, all data types are treated as strings)

SEE ALSO
ImageIO(3++), ImageData, Mem(3C++), Compress(3C++)
----------------------------------------------------------------------

