casacore-dev 2.2.0-2 / usr / include / casacore / fits / FITS / fitsio.h

//# fitsio.h:
//# Copyright (C) 1993,1994,1995,1996,1999,2001,2003
//# Associated Universities, Inc. Washington DC, USA.
//# 
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//# 
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
//# License for more details.
//# 
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//# 
//# Correspondence concerning AIPS++ should be addressed as follows:
//#        Internet email: aips2-request@nrao.edu.
//#        Postal address: AIPS++ Project Office
//#                        National Radio Astronomy Observatory
//#                        520 Edgemont Road
//#                        Charlottesville, VA 22903-2475 USA
//#
//# $Id$

#ifndef FITS_FITSIO_H
#define FITS_FITSIO_H

#include <casacore/casa/aips.h>
# include <casacore/fits/FITS/fits.h>
# include <casacore/fits/FITS/blockio.h>
# include <casacore/fits/FITS/hdu.h>
//# include <casacore/casa/stdvector.h>
# include <casacore/casa/Arrays/Vector.h>

namespace casacore { //# NAMESPACE CASACORE - BEGIN

//<summary> sequential FITS I/O </summary>
// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
// </reviewed>
//<synopsis>
// FitsIO is a base class that handles all the sequential blocked
// FITS I/O. Special derived classes do the input and output.
// No interpretation of the data is attempted here, there are 
// special FITS classes that handle syntax and interpretation.
//</synopsis>
//<example>
//<srcblock>
// FitsInput fin("myfile.fits",FITS::Disk);	// open disk file for FITS input
// if (fin.err() == FitsIO::IOERR) {            // check if open succeeded
//     cout << "Could not open FITS input\n";
//     exit(0);
// }
// if (fin.rectype() == FITS::HDURecord &&      // test for primary array
//     fin.hdutype() == FITS::PrimaryArrayHDU) {
// }
//</srcblock>
//</example>

class FitsIO {
    public:
	virtual ~FitsIO();

	// error return code. Should be one of an 
	// enumerated type:
	//
	//#  until cxx2html can handle enum() we duplicate it here
	//
	//<srcblock>
	//  enum FitsErrs { OK, IOERR, MISSKEY, BADBEGIN, EMPTYFILE,
	//	NOPRIMARY, BADOPER, BADEOF, MEMERR, BADBITPIX, NOAXISN,
	//	NOPCOUNT, NOGCOUNT, BADPCOUNT, BADGCOUNT, NOGROUPS,
	//	BADNAXIS, BADPRIMARY, BADSIZE, HDUERR };
	//</srcblock>
	//<group>
	enum FitsErrs { OK, IOERR, MISSKEY, BADBEGIN, EMPTYFILE,
		NOPRIMARY, BADOPER, BADEOF, MEMERR, BADBITPIX, NOAXISN,
		NOPCOUNT, NOGCOUNT, BADPCOUNT, BADGCOUNT, NOGROUPS,
		BADNAXIS, BADPRIMARY, BADSIZE, HDUERR };
	int err() const 			{ return m_err_status; }
	//</group>
	//
	// record size, in bytes, of a FITS block. 
	// Normally set at 2880, unless some form of blocking was used.
	int fitsrecsize() const 		{ return m_recsize; }
	// is it a valid fits file (SIMPLE==T). If not, the only
	// safest operation is to skip the data portion of the
	// current HeaderDataUnit
	Bool isafits() const 			{ return m_valid_fits; }
	// see if there may be FITS extensions present (EXTENT==T)
	Bool isextend() const 			{ return m_extend; }
	// test if end of file has been reached
	Bool eof() const 	 { return Bool(m_rec_type == FITS::EndOfFile); }
	// the FITS record type
	FITS::FitsRecType rectype() const 	{ return m_rec_type;  }
	// Header Data Unit type (e.g. 
	FITS::HDUType hdutype() const 		{ return m_hdu_type; }
	FITS::ValueType datatype() const 	{ return m_data_type; }
	// return the datasize of the current HDU. This excludes
	// the trailing end of the blocked data portion.
	OFF_T datasize() const 			{ return m_data_size; }
	// data characteristics
	Int itemsize() const 			{ return m_item_size; }
	// for input, size of remaining data
	// for output, size of data written
	OFF_T currsize() const 			{ return m_curr_size; }
	// get FitsKeyCardTranslator
	FitsKeyCardTranslator& getkc(){  return m_kc;  }
	// get the fitsfile pointer
	fitsfile *getfptr() const { return m_fptr; }

	// get the size of the last skipped HDU
	OFF_T getskipsize() const {return m_skipHDU_size;}


   protected:
	FitsIO(FITSErrorHandler);

	fitsfile *m_fptr;
	const int m_recsize;
	Bool m_valid_fits;		// True if SIMPLE == T
	Bool m_extend;			   // True if EXTEND == T
	Bool m_isaprimary;		// True if there is a primary HDU
   Bool m_header_done;		// True if header has been processed
	FITS::FitsRecType m_rec_type; 	// always set
	FITS::HDUType m_hdu_type;		// always set

	FITSErrorHandler m_errfn;	        // error handler function
	FitsErrs m_err_status;
	FitsKeyCardTranslator m_kc;
	FitsKeywordList m_kw;

	char *m_curr;			// pointer to current record
	int m_bytepos;			// current byte position within record
	Int m_item_size;			// data characteristics
	FITS::ValueType m_data_type;
	//uInt m_data_size;
	OFF_T m_data_size;		
	// for input, size of remaining data
	// for output, size of data written
	//uInt m_curr_size;
	OFF_T m_curr_size;			

	// for size of the last HDU skipped
	OFF_T m_skipHDU_size;

	// set error message that belongs to one of the enumerated types
	virtual void errmsg(FitsErrs, const char *) = 0;
					
};

//<summary> fixed-length sequential blocked FITS input </summary>

class FitsInput : public FitsIO {
	friend int HeaderDataUnit::get_hdr(FITS::HDUType, FitsKeywordList &);
	friend OFF_T HeaderDataUnit::read_all_data(char *);
	friend int HeaderDataUnit::read_data(char *, Int);
	friend int HeaderDataUnit::skip(uInt);
	friend int HeaderDataUnit::skip();

    public:
	//<group>
	FitsInput(const char *, const FITS::FitsDevice &, int = 10, 
		  FITSErrorHandler errhandler = FITSError::defaultHandler);
	FitsInput(FITSErrorHandler errhandler = FITSError::defaultHandler); 
	~FitsInput();
	//</group>

	int skip_hdu();

	// skip all remaining data
	void skip_all(FITS::HDUType);

	//int skip_hdu2();
	// read special or unrecognizable records
	char *read_sp();

   // get hdu header image cards as strings. By default the strings will be of
   // variable length. You can optionally ask for them to be length 80 (padded
   // with spaces).
	Vector<String> kwlist_str(Bool length80=False);

   //  number of physical blocks read/written
   int blockno() const {return m_fin.blockno();}

   //  number of logical records read/written
   int recno() const {return m_fin.recno();}
   BlockInput & getfin(){ return m_fin; } // for test use only

   // the number of hdu in this fits file
   int getnumhdu() const {return m_thdunum;}

    private:
	BlockInput &m_fin;
	BlockInput &make_input(const char *, const FITS::FitsDevice &, int, 
			       FITSErrorHandler errhandler = FITSError::defaultHandler);

	// flag used for read control in errors
	Bool m_got_rec;
	// total number of hdu in this fits file
	int m_thdunum;		

	virtual void errmsg(FitsErrs, const char *);
	void init();
	void read_header_rec();
	bool current_hdu_type( FITS::HDUType &);
	bool get_data_type( FITS::ValueType &);

	//# check if this comes out ok in cxx2html
        // Special interface to class HeaderDataUnit
	//<group>
        // special way to process header
	int process_header(FITS::HDUType, FitsKeywordList &);
	// read all data into a given address - all responsibility is given
	// to the user
	OFF_T read_all(FITS::HDUType, char *);
	// read N bytes into address
	int read(FITS::HDUType, char *, int );
	// skip N bytes
	int skip(FITS::HDUType, OFF_T);
        //</group>
};

//<summary> fixed-length sequential blocked FITS output </summary>

class FitsOutput : public FitsIO {
	friend int HeaderDataUnit::write_hdr(FitsOutput &);
	friend int HeaderDataUnit::write_all_data(FitsOutput &, char *);
	friend int HeaderDataUnit::write_data(FitsOutput &, char *, Int);

    public:
	//<group>
	FitsOutput(const char *, const FITS::FitsDevice &, int = 10, 
		   FITSErrorHandler errhandler = FITSError::defaultHandler);
	FitsOutput(FITSErrorHandler errhandler = FITSError::defaultHandler);
	~FitsOutput();
	//</group>
   // used by PrimaryArray, BinaryTabelExtention etc to work with the constructor without keyword list.
	void set_data_info( FitsKeywordList &kwl, FITS::HDUType t, FITS::ValueType dt, OFF_T ds, Int is);
	// write a special record. For this the record type must also
	// be to set to FITS::SpecialRecord
	int write_sp(char *rec);
	// check if the current hdu is done. It was private.
	int hdu_complete() { 
	    return (m_rec_type == FITS::HDURecord && m_data_size == 0);
   }
   BlockOutput & getfout(){ return m_fout; }
	void setfptr( fitsfile* ffp ); 
	Bool required_keys_only(){ return m_required_keys_only; }

    private:
	BlockOutput &m_fout;
	Bool m_required_keys_only;
	BlockOutput &make_output(const char *, const FITS::FitsDevice &, int, 
				 FITSErrorHandler errhandler = FITSError::defaultHandler);

	virtual void errmsg(FitsErrs, const char *);

	int hdu_inprogress() { 
	    return (m_rec_type == FITS::HDURecord && m_data_size > 0 && m_curr_size < m_data_size);
	 }

	// Special interface to class HeaderDataUnit
	//<group>
	int write_hdr(FitsKeywordList &, FITS::HDUType, FITS::ValueType, OFF_T, Int);
	// write all data from address
	int write_all(FITS::HDUType, char *, char);
	// write N bytes from address
	int write(FITS::HDUType, char *, Int, char); 
	//</group>
};

//<summary> FITS input from disk </summary>

class FitsDiskInput : public BlockInput {
    public:
	FitsDiskInput(const char *, int, int = 1, 
		      FITSErrorHandler errhandler = FITSError::defaultHandler);
	~FitsDiskInput();
        // implements skip in terms of lseek
	char *skip(int); 
};

//<summary> FITS output to disk </summary>

class FitsDiskOutput : public BlockOutput {
    public:
	FitsDiskOutput(const char *, int, int = 1, 
		       FITSErrorHandler errhandler = FITSError::defaultHandler);
	~FitsDiskOutput();
};

//<summary> FITS input from standard input </summary>

class FitsStdInput : public BlockInput {
    public:
	FitsStdInput(int, 
		     FITSErrorHandler errhandler = FITSError::defaultHandler);
	~FitsStdInput();
};

//<summary> FITS output to standard output </summary>

class FitsStdOutput : public BlockOutput {
    public:
	FitsStdOutput(int, 
		      FITSErrorHandler errhandler = FITSError::defaultHandler);
	~FitsStdOutput();
};

//<summary> FITS input from 9-track tape </summary>

class FitsTape9Input : public BlockInput {
    public:
	FitsTape9Input(const char *, int, int = 10, 
		       FITSErrorHandler errhandler = FITSError::defaultHandler);
	~FitsTape9Input();
};

//<summary> FITS output to 9-track tape </summary>

class FitsTape9Output : public BlockOutput {
    public:
	FitsTape9Output(const char *, int, int = 10, 
			FITSErrorHandler errhandler = FITSError::defaultHandler);
	~FitsTape9Output();
};


} //# NAMESPACE CASACORE - END

# endif