fitsio.h

Go to the documentation of this file.

//# 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