hdu.h

Go to the documentation of this file.

//# hdu.h:
//# Copyright (C) 1993,1994,1995,1996,1997,1999,2000,2002,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_HDU_H
#define FITS_HDU_H

# include <casacore/casa/aips.h>
# include <casacore/fits/FITS/fits.h>
# include <casacore/fits/FITS/blockio.h>
# include <casacore/casa/BasicSL/String.h>
# include <casacore/casa/Arrays/Vector.h>

//# # include <stdarg.h> // If we ever wan to put varargs support back

namespace casacore { //# NAMESPACE CASACORE - BEGIN

class FitsInput;
class FitsOutput;

//<summary> base class that defines a HDU </summary>
//<synopsis>
// The class HeaderDataUnit contains what is common to all 
// header-data-units, including the collection of keywords.
// From this class a number of FITS header-data-units are 
// derived, each of them with their own rich assortment of 
// functions for accessing and manipulating data of specific types.
//
// The following inheritence hierarchy illustrates the current
// derived classes:
//<srcblock>
//
//                              HeaderDataUnit
//                              /          | 
//                             /           | 
//                   PrimaryArray       ExtensionHeaderDataUnit
//                    /  |  \                              | 
//                   /   |   \                             | 
//        PrimaryGroup   |   ImageExtension                | 
//                       |                                 | 
//                  PrimaryTable                        BinaryTableExtension
//                                                         /
//                                                        /
//                                      AsciiTableExtension
//</srcblock>
//</synopsis>

class HeaderDataUnit {
        friend std::ostream & operator << (std::ostream &, HeaderDataUnit &);
    public:
        virtual ~HeaderDataUnit();

        Int dims() const                        { return no_dims; }
        Int dim(int n) const                    { return (0<no_dims && n<no_dims ? dimn[n] : 0); }
        OFF_T fitsdatasize() const              { return fits_data_size; }
        FITS::ValueType datatype() const        { return data_type; }
        Int fitsitemsize() const                { return fits_item_size; }
        Int localitemsize() const               { return local_item_size; }
        FITS::HDUType hdutype() const           { return hdu_type; }

        // error handling and error codes that can be returned
        //<group>
        enum HDUErrs { OK, NOMEM, MISSKEY, BADBITPIX, NOAXISN,
                NOPCOUNT, NOGCOUNT, BADPCOUNT, BADGCOUNT, NOGROUPS,
                BADNAXIS, BADREC, BADTYPE, BADRULES, BADSIZE, BADOPER,
                BADCONV,  BADIO };
        int err() const { return err_status; }
        //</group>

        // skipping one or more HDU's
        //<group>
        int skip(uInt n);
        int skip();
        //</group>

        // write the current header
        int write_hdr(FitsOutput &);

        // Determines the HDU type and the data type 
        // Parameterss: keyword list, hdu type, data type, error handler and 
        // error status.
        // Returns False if a serious error was detected, otherwise True
        static Bool determine_type(FitsKeywordList &, FITS::HDUType &, 
                FITS::ValueType &, FITSErrorHandler, HDUErrs &);

 
        // Compute the total size of the data associated with an HDU.  
        // The number of dimensions is also determined.  This routine 
        // assumes that hdu type has been appropriately set, but it may 
        // be changed in the process.  Data type is also determined.
        // Returns False if a serious error was detected, otherwise True
        static Bool compute_size(FitsKeywordList &, OFF_T &, Int &,
                FITS::HDUType &, FITS::ValueType &, FITSErrorHandler, HDUErrs &);

        // Operations on the HDU's keyword list
        //<group>
        ConstFitsKeywordList &kwlist(){  return constkwlist_;}
        // return the header of the chdu as a vector of String. You can
        // force the strings to be length 80 (padded with spaces)
        Vector<String> kwlist_str(Bool length80=False);
        void firstkw() { kwlist_.first(); }
        void lastkw() { kwlist_.last(); }
        const FitsKeyword *nextkw() { return kwlist_.next(); }
        const FitsKeyword *prevkw() { return kwlist_.prev(); }
        const FitsKeyword *currkw() { return kwlist_.curr(); }  
        const FitsKeyword *kw(int n) { return kwlist_(n); }
        //# 07/21/98 AKH Added const to quite Apogee warnings:
        const FitsKeyword *kw(const FITS::ReservedName &n) { 
                return kwlist_(n); }
        const FitsKeyword *nextkw(FITS::ReservedName &n) { 
                return kwlist_.next(n); }
        const FitsKeyword *kw(FITS::ReservedName &n, int i) { 
                return kwlist_(n,i); }
        const FitsKeyword *nextkw(FITS::ReservedName &n, int i) { 
                return kwlist_.next(n,i); }
        const FitsKeyword *kw(const char *n) { return kwlist_(n); }
        const FitsKeyword *nextkw(const char *n) { return kwlist_.next(n); }
        void mk(FITS::ReservedName k, Bool v, const char *c = 0);
        void mk(FITS::ReservedName k, const char *v = 0, const char *c = 0);
        void mk(FITS::ReservedName k, Int v, const char *c = 0);
        void mk(FITS::ReservedName k, double v, const char *c = 0);
        void mk(int n, FITS::ReservedName k, Bool v, const char *c = 0);
        void mk(int n, FITS::ReservedName k, const char *v, const char *c = 0);
        void mk(int n, FITS::ReservedName k, Int v, const char *c = 0);
        void mk(int n, FITS::ReservedName k, double v, const char *c = 0);
        void mk(const char *n, Bool v, const char *c = 0);
        void mk(const char *n, const char *v = 0, const char *c = 0);
        void mk(const char *n, Int v, const char *c = 0);
        void mk(const char *n, float v, const char *c = 0);
        void mk(const char *n, double v, const char *c = 0);
        void mk(const char *n, Int r, Int i, const char *c = 0);
        void mk(const char *n, float r, float i, const char *c = 0);
        void mk(const char *n, double r, double i, const char *c = 0);
        void spaces(const char *n = 0, const char *c = 0);
        void comment(const char *n = 0, const char *c = 0);
        void history(const char *c = 0);
        //</group>

        Bool notnull(double x) const { return double_null < x ? True : False; }
        Bool notnull(char *s) const { return ! s ? False : (s[0] != '\0' ? True : False); }
        Bool notnull(Int l) const { return Int_null < l ? True : False; }

    protected:
        //      For input -- ~ should delete the keyword list: kwflag = 1
        HeaderDataUnit(FitsInput &, FITS::HDUType, 
                       FITSErrorHandler errhandler = FITSError::defaultHandler);
        //      For output -- ~ should not delete keyword list: kwflag = 0
        // 07/21/98 AKH Clarification: HeaderDataUnit has a copy of the
        //              FitsKeywordList, and should delete it.  The kwflag
        //              comments above are not important now.
        HeaderDataUnit(FitsKeywordList &, FITS::HDUType, 
                       FITSErrorHandler errhandler = FITSError::defaultHandler,
                       FitsInput * = 0);
        // constructor for objects that write only required keyword to fits file.
        // the write method to call by these object should be those for the specific
        // hdu, such as write_bintbl_hdr().
        HeaderDataUnit(FITS::HDUType, 
                       FITSErrorHandler errhandler = FITSError::defaultHandler,
                       FitsInput * = 0);
        // for write required keywords only to use.
        bool init_data_unit( FITS::HDUType t );

        FitsKeywordList &kwlist_;
        ConstFitsKeywordList constkwlist_;
        void posEnd();

        FitsInput *fin;
        FITSErrorHandler errfn;
        HDUErrs err_status;
        void errmsg(HDUErrs, const char *);

        Int no_dims;            // number of dimensions
        Int *dimn;              // size of dimension N
        //uInt fits_data_size;  // size in bytes of total amount of data
        OFF_T fits_data_size;   // size in bytes of total amount of data
        FITS::ValueType data_type;      // type of data - derived from BITPIX
        Int fits_item_size;     // size in bytes of an item of FITS data
        Int local_item_size;    // size in bytes of an item of local data
        FITS::HDUType hdu_type; // type of header/data unit
        char pad_char;          // char to pad FITS data block

        //<group>
        char * assign(FITS::ReservedName);
        char * assign(FITS::ReservedName, int);
        double asgdbl(FITS::ReservedName, double);
        double asgdbl(FITS::ReservedName, int, double);
        //</group>
        double double_null;
        char char_null;
        Int Int_null;

    public:
        int get_hdr(FITS::HDUType, FitsKeywordList &);
        int read_data(char *, Int);
        int write_data(FitsOutput &, char *, Int);
        OFF_T read_all_data(char *);
        int write_all_data(FitsOutput &, char *);
};

inline std::ostream & operator << (std::ostream &o, HeaderDataUnit &h) {
        return o << h.kwlist_; }
inline void HeaderDataUnit::mk(FITS::ReservedName k, Bool v, const char *c) {
        posEnd(); kwlist_.mk(k,v,c); }
inline void HeaderDataUnit::mk(FITS::ReservedName k, const char *v, 
        const char *c) { posEnd(); kwlist_.mk(k,v,c); }
inline void HeaderDataUnit::mk(FITS::ReservedName k, Int v, const char *c) {
        posEnd(); kwlist_.mk(k,v,c); }
inline void HeaderDataUnit::mk(FITS::ReservedName k, double v, const char *c) {
        posEnd(); kwlist_.mk(k,v,c); }
inline void HeaderDataUnit::mk(int n, FITS::ReservedName k, Bool v, 
        const char *c) { posEnd(); kwlist_.mk(n,k,v,c); }
inline void HeaderDataUnit::mk(int n, FITS::ReservedName k, const char *v, 
        const char *c) { posEnd(); kwlist_.mk(n,k,v,c); }
inline void HeaderDataUnit::mk(int n, FITS::ReservedName k, Int v, 
        const char *c) { posEnd(); kwlist_.mk(n,k,v,c); }
inline void HeaderDataUnit::mk(int n, FITS::ReservedName k, double v, 
        const char *c) { posEnd(); kwlist_.mk(n,k,v,c); }
inline void HeaderDataUnit::mk(const char *n, Bool v, const char *c) {
        posEnd(); kwlist_.mk(n,v,c); }
inline void HeaderDataUnit::mk(const char *n, const char *v, const char *c) {
        posEnd(); kwlist_.mk(n,v,c); }
inline void HeaderDataUnit::mk(const char *n, Int v, const char *c) {
        posEnd(); kwlist_.mk(n,v,c); }
inline void HeaderDataUnit::mk(const char *n, float v, const char *c) {
        posEnd(); kwlist_.mk(n,v,c); }
inline void HeaderDataUnit::mk(const char *n, double v, const char *c) {
        posEnd(); kwlist_.mk(n,v,c); }
inline void HeaderDataUnit::mk(const char *n, Int r, Int i, const char *c) {
        posEnd(); kwlist_.mk(n,r,i,c); }
inline void HeaderDataUnit::mk(const char *n, float r, float i, const char *c) {
        posEnd(); kwlist_.mk(n,r,i,c); }
inline void HeaderDataUnit::mk(const char *n, double r, double i, 
        const char *c) { posEnd(); kwlist_.mk(n,r,i,c); }
inline void HeaderDataUnit::spaces(const char *n, const char *c) { 
        posEnd(); kwlist_.spaces(n,c); }
inline void HeaderDataUnit::comment(const char *n, const char *c) { 
        posEnd(); kwlist_.comment(n,c); }
inline void HeaderDataUnit::history(const char *c) { 
        posEnd(); kwlist_.history(c); }

//<summary> templated primary array base class of given type </summary>
//<synopsis>
// A Primary Data Array is represented by the following:
//<srcblock>
//      <Type> data_array [NAXIS1][NAXIS2]...[NAXISN]
//</srcblock>
//
// For a PrimaryArray, dims() gives the number of dimensions
// and dim(i) gives the value of the i-th dimension
//
// WARNING!  Multi-dimensional arrays are stored in FORTRAN order, 
// NOT in C order.  Options on the store, copy, and move functions exist 
// to convert from one order to the other, if that is necessary.
//
// 
// It is important to understand the proper sequence of operations with
// respect to I/O and data access.  For input, the `read()' functions
// allocate an internal buffer of the appropriate size, if not already
// allocated, as well as reading and converting data; a `read()' function
// must be performed prior to accessing the data, i. e. before executing
// any `()', `data()', `copy()', or `move()' function.  For output, the
// `store()' function similarly allocates an internal buffer before
// transfering data, and must be executed prior to any data access or
// `write()' function. Note: If you call any version of store(), do not
// call set_next().
// 
// Writing portions of an array at a time, rather than the entire array,
// is a special case.  The `set_next()' function is provided for this
// purpose. It declares the intention to write out the next N elements and
// must be executed prior to any `data()' function.  It allocates a buffer
// of appropriate size, if not already allocated.  Again, via the `data()'
// functions, one accesses the array as if the entire array were in
// memory.  The `write()' function always writes the number of current
// elements in the internal buffer.  The sequence of operations for each
// portion of the array written would be: 
// <ul>
// <li> `set_next(N)', 
// <li> fill the array using `data(N)' or other `data()' functions
// <li> `write(fout)'.  
// </ul>
// The `set_next()' function must NOT be used with
// `read()' or `store()' functions; unpredictable results will occur.  
//<example>
// The following example illustrates the output cases.
// 
// Suppose we have an image array with 512 rows and 1024 columns
// stored in C-order.  The C declaration would be:
//<srcblock>
//      int source[1024][512];
//</srcblock>
// To write out the entire array:
//<srcblock>
//      FitsOutput fout; // some properly constructed FitsOutput
//      PrimaryArray<FitsLong> pa; // some properly constructed PrimaryArray
//      pa.store(source,CtoF);
//      pa.write(fout);
//</srcblock>
//
// Suppose we wanted to write out the two-dimensional image array a column
// at a time, rather than write out the entire array.  For FITS, dim(0)
// is 512, dim(1) is 1024.  The following code fragment writes one column 
// at a time in the proper FITS Fortran-order.
//
//<srcblock> 
//      for (i = 0; i < dim(1); ++i) {
//              pa.set_next(dim(0));
//              for (j = 0; j < dim(0); ++j)
//                      data(j,i) = source[i][j];
//              pa.write(fout);
//      }
//</srcblock>
//</example>
//
//</synopsis>

template <class TYPE>
class PrimaryArray : public HeaderDataUnit {
    public:
        typedef TYPE ElementType;

        // constructor from a FitsInput
        PrimaryArray(FitsInput &, FITSErrorHandler= FITSError::defaultHandler);
        // constructor from a FitsKeywordList
        PrimaryArray(FitsKeywordList &, 
                     FITSErrorHandler= FITSError::defaultHandler);
        // constructor does not require a FitsKeywordList. call write_priArr_hdr() after construction.
        PrimaryArray(FITSErrorHandler= FITSError::defaultHandler);

        // destructor
        virtual ~PrimaryArray();

        // General access routines for a primary array
        //<group>
        double bscale() const           { return bscale_x; }
        double bzero() const            { return bzero_x; }
        char *bunit() const             { return bunit_x; }
        Bool isablank() const           { return isablank_x; }
        Int blank() const               { return blank_x; }
        char *ctype(int n) const        { return ctype_x[n]; }
        double crpix(int n) const       { return crpix_x[n]; }
        double crota(int n) const       { return crota_x[n]; }
        double crval(int n) const       { return crval_x[n]; }
        double cdelt(int n) const       { return cdelt_x[n]; }
        double datamax() const          { return datamax_x; }
        double datamin() const          { return datamin_x; }
        OFF_T nelements() const         { return totsize; }
        //</group>

        // The overloaded operator functions `()' all return physical data, i. e.,
        // data to which bscale() and bzero() have been applied, via the formula
        //<srcblock>
        //      physical_data[i] = bscale() * raw_data[i] + bzero().
        //</srcblock>
        //<group>
        double operator () (int, int, int, int, int) const; 
        double operator () (int, int, int, int) const; 
        double operator () (int, int, int) const; 
        double operator () (int, int) const;
        double operator () (int) const;
        //</group>

        // The various `data()' functions allow one to access and set the raw data 
        // itself.  
        //<group>
        TYPE & data(int, int, int, int, int); 
        TYPE & data(int, int, int, int); 
        TYPE & data(int, int, int); 
        TYPE & data(int, int);
        TYPE & data(int);
        //</group>

        // The `store()', `move()' and `copy()' functions allow bulk data
        // transfer between the internal FITS array and an external data
        // storage area.  The external storage must have already been allocated
        // and it is assumed that the entire data array is in memory.
        // `store()' transfers raw data at `source' into the FITS array; an
        // allowable option is CtoF, which specifies to convert the array from
        // C-order to Fortran-order.  `move()' is the opposite of `store()'.
        // `move()' transfers raw data from the FITS array to `target'; an
        // allowable option is FtoC, which specifies to convert the array from
        // Fortran-order to C-order.  `copy()' is similar to `move()' except
        // that what is copied is physical data and not raw data; the physical
        // data can be either double or float. copy() also turns blanks into
        // NaN's.
        //<group>
        int store(const TYPE *source, FITS::FitsArrayOption = FITS::NoOpt);
        void copy(double *target, FITS::FitsArrayOption = FITS::NoOpt) const;
        void copy(float *target, FITS::FitsArrayOption = FITS::NoOpt) const;
        void move(TYPE *target, FITS::FitsArrayOption = FITS::NoOpt) const;
        //     <group>
        // Use these versions if you are reading/writing "chunk by
        // chunk." No FtoC option is available. You are responsible for
        // ensuring that npixels corresponds to he number actually read or
        // written. Note that copy() turns blanks into NaN's.
        int store(const TYPE *source, int npixels);
        void copy(double *target, int npixels) const;
        void copy(float *target, int npixels) const;
        void move(TYPE *target, int npixels) const;
        //     </group>
        // </group>
        //<group>
        int write_priArr_hdr( FitsOutput &fout, int simple, int bitpix,     
                              int naxis, long naxes[], int extend );            
        //</group>
        // The `read()' and `write()' functions control reading and writing data
        // from the external FITS I/O medium into the FITS array.  Appropriate
        // conversions are made between FITS and local data representations.  One
        // can read the entire array into memory, or one can only read portions of
        // the array.  In the latter case, one must specify that the next N
        // elements are to be read or written.  Note that the number of elements
        // must be specified, NOT the number of bytes.  If one reads portions of
        // the array, as opposed to the entire array, only that portion is in
        // memory at a given time.  One can still access the elements of the array
        // via the `()' and `data()' functions, as if the entire array was in
        // memory; obviously care must be taken in this case to access only those
        // portions that are actually in memory.
        //<group>
        virtual int read(); 
        virtual int read( int ); 
        virtual int write(FitsOutput &); 
        virtual OFF_T set_next(OFF_T);
        //</group>
        //### if these, even as interspersed comments, cxx2html repeats the global
        //# group info..
        //# read: read entire array into memory
        //# read() read next N elements into memory
        //# write; write current data
        //# set_next(): prepare to write next N elements

    protected:
        // construct from a FitsInput with given HDU type
        PrimaryArray(FitsInput &, FITS::HDUType, 
                     FITSErrorHandler errhandler = FITSError::defaultHandler);
        // construct from a FitsKeywordList with given HDU type
        PrimaryArray(FitsKeywordList &, FITS::HDUType, 
                     FITSErrorHandler errhandler = FITSError::defaultHandler);
                          
        // construct witout FitsKeywordList for given HDU type( for ImageExtension and PrimaryGroup)
        PrimaryArray(FITS::HDUType, 
                     FITSErrorHandler errhandler = FITSError::defaultHandler);


        double bscale_x;
        double bzero_x;
        char *bunit_x;
        Bool isablank_x;
        Int blank_x;
        char **ctype_x;
        double *crpix_x;
        double *crota_x;
        double *crval_x;
        double *cdelt_x;
        double datamax_x;
        double datamin_x;
        OFF_T totsize;

        int *factor; // factors needed to compute array position offsets

        // compute a linear offset from array indicies
        //<group>
        int offset(int, int) const; 
        int offset(int, int, int) const; 
        int offset(int, int, int, int) const; 
        int offset(int, int, int, int, int) const; 
        //</group>
        OFF_T alloc_elems; // current number of allocated elements
        OFF_T beg_elem; // offset of first element in the buffer
        OFF_T end_elem; // offset of last element in the buffer
        // the allocated array
        TYPE *array;

        void pa_assign();
};

typedef PrimaryArray<unsigned char> BytePrimaryArray;
typedef PrimaryArray<short> ShortPrimaryArray;
typedef PrimaryArray<FitsLong> LongPrimaryArray;
typedef PrimaryArray<float> FloatPrimaryArray;
typedef PrimaryArray<double> DoublePrimaryArray;


//<summary> IMAGE extension of given type </summary>
//<templating>
// <li> typedef ImageExtension<unsigned char> ByteImageExtension;
// <li> typedef ImageExtension<short> ShortImageExtension;
// <li> typedef ImageExtension<FitsLong> LongImageExtension;
// <li> typedef ImageExtension<float> FloatImageExtension;
// <li> typedef ImageExtension<double> DoubleImageExtension;
//</templating>

template <class TYPE>
class ImageExtension : public PrimaryArray<TYPE> {
    public:
        typedef TYPE ElementType;

        ImageExtension(FitsInput &, 
                       FITSErrorHandler errhandler = FITSError::defaultHandler);
        ImageExtension(FitsKeywordList &, 
                       FITSErrorHandler errhandler = FITSError::defaultHandler);
        // constructor for header consisted required keywords only                       
        ImageExtension(FITSErrorHandler errhandler = FITSError::defaultHandler);

        ~ImageExtension();
        char *xtension()        { return xtension_x; }
        char *extname()         { return extname_x; }
        Int extver()            { return extver_x; }
        Int extlevel()  { return extlevel_x; }
        Int pcount()            { return pcount_x; }
        Int gcount()            { return gcount_x; }
        // write required keywords for ImageExtension
        int write_imgExt_hdr( FitsOutput &fout,
            int bitpix, int naxis, long *naxes);     
    protected:
        char *xtension_x;
        char *extname_x;
        Int extver_x;
        Int extlevel_x;
        Int pcount_x;
        Int gcount_x;

    private:
        void ie_assign();

        //# Make members in parent known
    protected:
        using PrimaryArray<TYPE>::assign;
        using PrimaryArray<TYPE>::errmsg;
        using PrimaryArray<TYPE>::init_data_unit;
        using PrimaryArray<TYPE>::pa_assign;
        using PrimaryArray<TYPE>::char_null;
        using PrimaryArray<TYPE>::kwlist_;
        using PrimaryArray<TYPE>::errfn;
        using PrimaryArray<TYPE>::hdu_type;
        using PrimaryArray<TYPE>::data_type;
        using PrimaryArray<TYPE>::fits_data_size;
        using PrimaryArray<TYPE>::fits_item_size;
        using PrimaryArray<TYPE>::array;
        using PrimaryArray<TYPE>::BADOPER;
};

typedef ImageExtension<unsigned char> ByteImageExtension;
typedef ImageExtension<short> ShortImageExtension;
typedef ImageExtension<FitsLong> LongImageExtension;
typedef ImageExtension<float> FloatImageExtension;
typedef ImageExtension<double> DoubleImageExtension;

//<summary> Random Group datastructure </summary>
//<synopsis>
// A Random Group Structure is represented by the following:
//<srcblock>
//      struct GroupData {
//              <Type> group_parms [PCOUNT];
//              <Type> data_array [NAXIS2][NAXIS3]...[NAXISN];
//      } group_data[GCOUNT];
//</srcblock>
//</synopsis>
//<templating>
//#until cxx2html can handle this, duplicate
// <li>typedef PrimaryGroup<unsigned char> BytePrimaryGroup;
// <li> typedef PrimaryGroup<short> ShortPrimaryGroup;
// <li> typedef PrimaryGroup<FitsLong> LongPrimaryGroup;
// <li> typedef PrimaryGroup<float> FloatPrimaryGroup;
// <li> typedef PrimaryGroup<double> DoublePrimaryGroup;
//</templating>
//<note role=warning>
// Please note that the NOST has deprecated the Random Group 
// datastructure, it has been replaced by the much more powerfull
// BINTABLE extension.
//</note>
template <class TYPE>
class PrimaryGroup : public PrimaryArray<TYPE> {
    public:
        PrimaryGroup(FitsInput &, 
                     FITSErrorHandler errhandler = FITSError::defaultHandler);
        PrimaryGroup(FitsKeywordList &, 
                     FITSErrorHandler errhandler = FITSError::defaultHandler);
        // constructor for header consisted required keywords only
        PrimaryGroup(FITSErrorHandler errhandler = FITSError::defaultHandler);
                         
        ~PrimaryGroup();

        // Return basic parameters of a random group
        //<group>
        Int gcount() const         { return gcount_x; }
        Int pcount()  const        { return pcount_x; }
        char *ptype(int n)  const  { return ptype_x[n]; }
        double pscal(int n)  const { return pscal_x[n]; }
        double pzero(int n)  const { return pzero_x[n]; }
        //</group>

        Int currgroup() const      { return current_group; }

        double parm(int); // return physical parms
        TYPE & rawparm(int); // access raw parms

        void storeparm(const TYPE *source);
        void copyparm(double *target) const;
        void copyparm(float *target) const;
        void moveparm(TYPE *target) const;

        // read, or write the next group
        //<group>
        int read();
        int write(FitsOutput &);
        //</group>
        // write the required keywords for PrimaryGroup
        //<group>
        int write_priGrp_hdr( FitsOutput &fout, int simple, int bitpix,   
            int naxis, long naxes[], long pcount, long gcount ); 
   //</group>
        
        // disable these functions, since they
        // are inherited from PrimaryArray
        //<group>
        OFF_T set_next(OFF_T) { return 0; }
        int read(int) { return -1; }
        //</group>

    protected:
        Int pcount_x;
        Int gcount_x;
        char **ptype_x;
        double *pscal_x;
        double *pzero_x;
        TYPE *group_parm;
        Int current_group;      

    private:
        void pg_assign();

        //# Make members in parent known
    protected:
        using PrimaryArray<TYPE>::assign;
        using PrimaryArray<TYPE>::errmsg;
        using PrimaryArray<TYPE>::init_data_unit;
        using PrimaryArray<TYPE>::pa_assign;
        using PrimaryArray<TYPE>::asgdbl;
        using PrimaryArray<TYPE>::nelements;
        using PrimaryArray<TYPE>::localitemsize;
        using PrimaryArray<TYPE>::fitsitemsize;
        using PrimaryArray<TYPE>::read_data;
        using PrimaryArray<TYPE>::write_data;
        using PrimaryArray<TYPE>::char_null;
        using PrimaryArray<TYPE>::kwlist_;
        using PrimaryArray<TYPE>::errfn;
        using PrimaryArray<TYPE>::err_status;
        using PrimaryArray<TYPE>::hdu_type;
        using PrimaryArray<TYPE>::data_type;
        using PrimaryArray<TYPE>::fits_data_size;
        using PrimaryArray<TYPE>::fits_item_size;
        using PrimaryArray<TYPE>::array;
        using PrimaryArray<TYPE>::totsize;
        using PrimaryArray<TYPE>::dimn;
        using PrimaryArray<TYPE>::no_dims;
        using PrimaryArray<TYPE>::factor;
        using PrimaryArray<TYPE>::ctype_x;
        using PrimaryArray<TYPE>::crpix_x;
        using PrimaryArray<TYPE>::crota_x;
        using PrimaryArray<TYPE>::crval_x;
        using PrimaryArray<TYPE>::cdelt_x;
        using PrimaryArray<TYPE>::BADOPER;
        using PrimaryArray<TYPE>::OK;
        using PrimaryArray<TYPE>::NOMEM;
        using PrimaryArray<TYPE>::BADIO;
};

typedef PrimaryGroup<unsigned char> BytePrimaryGroup;
typedef PrimaryGroup<short> ShortPrimaryGroup;
typedef PrimaryGroup<FitsLong> LongPrimaryGroup;
typedef PrimaryGroup<float> FloatPrimaryGroup;
typedef PrimaryGroup<double> DoublePrimaryGroup;

//<summary> Primary Table structure </summary>
//<templating>
// <li> typedef PrimaryTable<unsigned char> BytePrimaryTable;
// <li> typedef PrimaryTable<short> ShortPrimaryTable;
// <li> typedef PrimaryTable<FitsLong> LongPrimaryTable;
// <li> typedef PrimaryTable<float> FloatPrimaryTable;
// <li> typedef PrimaryTable<double> DoublePrimaryTable;
//</templating>

template <class TYPE>
class PrimaryTable : public PrimaryArray<TYPE> {
    public:
        typedef TYPE ElementType;

        PrimaryTable(FitsInput &, 
                       FITSErrorHandler errhandler = FITSError::defaultHandler);
        PrimaryTable(FitsKeywordList &, 
                       FITSErrorHandler errhandler = FITSError::defaultHandler);
        // constructor for header consisted required keywords only                       
        PrimaryTable(FITSErrorHandler errhandler = FITSError::defaultHandler);

        ~PrimaryTable();
        // write required keywords for PrimaryTable
        int write_priTable_hdr( FitsOutput &fout,
            int bitpix, int naxis, long *naxes);     

        int read();
        int read(int) { return -1; }
        int write(FitsOutput &){ return -1; }

        char* object() const       { return object_x; }
        char* telescop()  const    { return telescop_x; }
        char* instrume()  const    { return instrume_x; }
        char* dateobs()  const { return dateobs_x; }
        char* datemap()  const { return datemap_x; }
        char* bunit()  const       { return bunit_x; }
        float bscal()  const { return bscale_x; }
        float bzero()  const { return bzero_x; }
        float equinox()  const { return equinox_x; }
        float altrpix()  const { return altrpix_x; }

    protected:
        char* object_x;      //OBJECT
        char* telescop_x;    //TELESCOP
        char* instrume_x;    //INSTRUME
        char* dateobs_x;    //DATE-OBS
        char* datemap_x;    //DATE-MAP
        Float bscale_x;      //BSCALE
        Float bzero_x;       //BZERO
        char* bunit_x;       //BUNIT
        Float equinox_x;     //EQUINOX
        Float altrpix_x;     //ALTRPIX


    private:
        void pt_assign();

        //# Make members in parent known
    protected:
        using PrimaryArray<TYPE>::assign;
        using PrimaryArray<TYPE>::errmsg;
        using PrimaryArray<TYPE>::init_data_unit;
        using PrimaryArray<TYPE>::pa_assign;
        using PrimaryArray<TYPE>::asgdbl;
        using PrimaryArray<TYPE>::nelements;
        using PrimaryArray<TYPE>::localitemsize;
        using PrimaryArray<TYPE>::fitsitemsize;
        using PrimaryArray<TYPE>::read_data;
        using PrimaryArray<TYPE>::write_data;
        using PrimaryArray<TYPE>::char_null;
        using PrimaryArray<TYPE>::kwlist_;
        using PrimaryArray<TYPE>::errfn;
        using PrimaryArray<TYPE>::err_status;
        using PrimaryArray<TYPE>::hdu_type;
        using PrimaryArray<TYPE>::data_type;
        using PrimaryArray<TYPE>::fits_data_size;
        using PrimaryArray<TYPE>::fits_item_size;
        using PrimaryArray<TYPE>::array;
        using PrimaryArray<TYPE>::totsize;
        using PrimaryArray<TYPE>::dimn;
        using PrimaryArray<TYPE>::no_dims;
        using PrimaryArray<TYPE>::factor;
        using PrimaryArray<TYPE>::ctype_x;
        using PrimaryArray<TYPE>::crpix_x;
        using PrimaryArray<TYPE>::crota_x;
        using PrimaryArray<TYPE>::crval_x;
        using PrimaryArray<TYPE>::cdelt_x;
        using PrimaryArray<TYPE>::BADOPER;
        using PrimaryArray<TYPE>::OK;
        using PrimaryArray<TYPE>::NOMEM;
        using PrimaryArray<TYPE>::BADIO;
};

typedef PrimaryTable<unsigned char> BytePrimaryTable;
typedef PrimaryTable<short> ShortPrimaryTable;
typedef PrimaryTable<FitsLong> LongPrimaryTable;
typedef PrimaryTable<float> FloatPrimaryTable;
typedef PrimaryTable<double> DoublePrimaryTable;

//<summary>  base class for generalized exentensions HDU </summary>

class ExtensionHeaderDataUnit : public HeaderDataUnit {
    public:
        ExtensionHeaderDataUnit(FitsInput &, 
                                FITSErrorHandler errhandler = FITSError::defaultHandler);
        ExtensionHeaderDataUnit(FitsKeywordList &, 
                                FITSErrorHandler errhandler = FITSError::defaultHandler);
        ~ExtensionHeaderDataUnit();
        char *xtension()        { return xtension_x; }
        char *extname()         { return extname_x; }
        Int extver()            { return extver_x; }
        Int extlevel()  { return extlevel_x; }
        Int pcount()            { return pcount_x; }
        Int gcount()            { return gcount_x; }

        // read next N bytes into addr
        int read(char *addr, int nbytes) {
            return read_data(addr, Int(nbytes)); }
        // write next N bytes from addr to the FITS output fout
        int write(FitsOutput &fout, char *addr, int nbytes) {
            return write_data(fout,addr,nbytes); }

    protected:
        ExtensionHeaderDataUnit(FitsInput &, FITS::HDUType, 
                                FITSErrorHandler errhandler = FITSError::defaultHandler);
        ExtensionHeaderDataUnit(FitsKeywordList &, FITS::HDUType, 
                                FITSErrorHandler errhandler = FITSError::defaultHandler);
        // This constructor is used for writing only required keywords.
        ExtensionHeaderDataUnit(FITS::HDUType, 
                                FITSErrorHandler errhandler = FITSError::defaultHandler);

        char *xtension_x;
        char *extname_x;
        Int extver_x;
        Int extlevel_x;
        Int pcount_x;
        Int gcount_x;

    private:
        void ex_assign();
};

//<summary> helper class </summary>

class FitsBase {
        friend class BinaryTableExtension;
        friend class AsciiTableExtension;
    public:
        FitsBase(const FITS::ValueType &t, int n) : no_elements(n), 
                data_type(t) { }
        virtual ~FitsBase();

        unsigned int nelements() const    { return (unsigned int)no_elements; }
        virtual int fitsfieldsize() const = 0;
        virtual int localfieldsize() const = 0;
        virtual void *data() = 0;
        virtual int dims() const;
        virtual int dim(int n) const;
        virtual int *vdim();
        FITS::ValueType fieldtype() const { return data_type; }

        static FitsBase *make(const FITS::ValueType &, int = 1);
        static FitsBase *make(const FITS::ValueType &, int, int *);
        static FitsBase *make(FitsBase &);

        FitsBase & operator = (FitsBase &);
        virtual void show(std::ostream &) = 0;

    protected:
        int no_elements; // the number of elements in the field
        FITS::ValueType data_type;
        virtual void setaddr(void **) = 0;
};

inline std::ostream & operator << (std::ostream &o, FitsBase &x) {
        x.show(o); return o;
}

//<summary> helper class </summary>
//<note>
// Note that FitsField does not allocate space for the data.
// Space is external to FitsField and its address is set via the
// setaddr function.
//</note>

template <class TYPE>
class FitsField : public FitsBase {
    public:
        FitsField(int n = 1) :
            FitsBase(FITS::getfitstype(NoConvert<TYPE>()),n), field(0) { }
        ~FitsField();

        TYPE & operator () () { return (*field)[0]; }
        TYPE & operator () (int i) { return (*field)[i]; }
        FitsField<TYPE> & operator = (const TYPE &x) {
                                        (*field)[0] = x; return *this; }

        int fitsfieldsize() const;
        int localfieldsize() const;

        void *data();

        void show(std::ostream &);

    protected:
        TYPE **field;
        void setaddr(void **addr);
};

//<summary> helper class </summary>
//<templating>
//#until cxx2html can handle this, duplicate
// <li> typedef FitsField<FitsLogical> LogicalFitsField;
// <li> typedef FitsField<FitsBit> BitFitsField;
// <li> typedef FitsField<char> CharFitsField;
// <li> typedef FitsField<unsigned char> ByteFitsField;
// <li> typedef FitsField<short> ShortFitsField;
// <li> typedef FitsField<FitsLong> LongFitsField;
// <li> typedef FitsField<float> FloatFitsField;
// <li> typedef FitsField<double> DoubleFitsField;
// <li> typedef FitsField<Complex> ComplexFitsField;
// <li> typedef FitsField<IComplex> IComplexFitsField;
// <li> typedef FitsField<DComplex> DComplexFitsField;
// <li> typedef FitsField<FitsVADesc> VADescFitsField;
//</templating>
//<note role=caution> 
// Bit fields require special treatment
//</note>

template <> class FitsField<FitsBit> : public FitsBase {
    public:
        FitsField(int n = 1);
        ~FitsField();

        FitsField<FitsBit> & operator () () { byte_offset = 0; mask = 0200;
                return *this; }

        FitsField<FitsBit> & operator () (unsigned i) {
            byte_offset = i / 8; mask = 0200 >> (i % 8); return *this; }

        FitsField<FitsBit> & operator = (unsigned i) {
            (*field)[byte_offset] =
                (i == 0 ? ((*field)[byte_offset] & ~mask) :
                          ((*field)[byte_offset] | mask)); return *this; }

        int fitsfieldsize() const;
        int localfieldsize() const;

        operator int() { return (((*field)[byte_offset] & mask) != 0); }

        void *data();

        void show(std::ostream &);

    protected:
        FitsBit **field;
        unsigned char mask;
        int byte_offset;
        void setaddr(void **addr);
};

typedef FitsField<FitsLogical> LogicalFitsField;
typedef FitsField<FitsBit> BitFitsField;
typedef FitsField<char> CharFitsField;
typedef FitsField<unsigned char> ByteFitsField;
typedef FitsField<short> ShortFitsField;
typedef FitsField<FitsLong> LongFitsField;
typedef FitsField<float> FloatFitsField;
typedef FitsField<double> DoubleFitsField;
typedef FitsField<Complex> ComplexFitsField;
typedef FitsField<IComplex> IComplexFitsField;
typedef FitsField<DComplex> DComplexFitsField;
typedef FitsField<FitsVADesc> VADescFitsField;

//<summary> FITS array of given type </summary>
template <class TYPE>
class FitsArray : public FitsField<TYPE> {
    public:
        FitsArray(int, const int *);
        ~FitsArray();
        TYPE & operator () (int d0, int d1);
        TYPE & operator () (int, int, int);
        TYPE & operator () (int, int, int, int);
        TYPE & operator () (int, int, int, int, int);
        int dims() const;
        int dim(int n) const;
        int *vdim();
    protected:
        int no_dims;
        int *dimn;
        int *factor;

        //# Make members in parent known
    protected:
        using FitsField<TYPE>::no_elements;
        using FitsField<TYPE>::field;
};

//<summary> FITS array of FitsBit type </summary>

//<note>
// We must specify a FitsArray<FitsBit> as a specialization.
//</note>

template <> class FitsArray<FitsBit> : public FitsField<FitsBit> {
    public:
        FitsArray(int, const int *);
        ~FitsArray();
        FitsField<FitsBit> & operator () (int d0, int d1);
        FitsField<FitsBit> & operator () (int, int, int);
        FitsField<FitsBit> & operator () (int, int, int, int);
        FitsField<FitsBit> & operator () (int, int, int, int, int);
//# Disabled for now - we might eventually want to put varargs support back
//#     FitsField<FitsBit> & operator () (int, int, int, int, int, int ...);

        int dims() const;
        int dim(int n) const;
        int *vdim();
    protected:
        int no_dims;
        int *dimn;
        int *factor;
};

typedef FitsArray<FitsLogical> LogicalFitsArray;
typedef FitsArray<FitsBit> BitFitsArray;
typedef FitsArray<char> CharFitsArray;
typedef FitsArray<unsigned char> ByteFitsArray;
typedef FitsArray<short> ShortFitsArray;
typedef FitsArray<FitsLong> LongFitsArray;
typedef FitsArray<float> FloatFitsArray;
typedef FitsArray<double> DoubleFitsArray;
typedef FitsArray<Complex> ComplexFitsArray;
typedef FitsArray<IComplex> IComplexFitsArray;
typedef FitsArray<DComplex> DComplexFitsArray;
typedef FitsArray<FitsVADesc> VADescFitsArray;

//<summary> BINTABLE extension </summary>

class BinaryTableExtension : public ExtensionHeaderDataUnit {
    public:
        BinaryTableExtension(FitsInput &, 
                             FITSErrorHandler errhandler = FITSError::defaultHandler);
                                  
        BinaryTableExtension(FitsKeywordList &, 
                             FITSErrorHandler errhandler = FITSError::defaultHandler);
        // constructor to match write_bintbl_hdr()                        
        BinaryTableExtension( FITSErrorHandler errhandler = FITSError::defaultHandler);

        virtual ~BinaryTableExtension();

        // return basic elements of a table
        //<group>
        Int nrows() const               { return dim(1); }
        Int ncols() const               { return tfields_x; }
        uInt rowsize() const            { return fitsrowsize; }
        Int tfields() const             { return tfields_x; }
        const char *tform(int n) const  { return tform_x[n]; }
        double tscal(int n) const       { return tscal_x[n]; }
        double tzero(int n) const       { return tzero_x[n]; }
        Bool isatnull(int n) const      { return isatnull_x[n]; }
        Int  tnull(int n) const         { return tnull_x[n]; }
        const char *ttype(int n) const  { return ttype_x[n]; }  
        const char *tunit(int n) const  { return tunit_x[n]; }
        const char *tdisp(int n) const  { return tdisp_x[n]; }
        const char *tdim(int n) const   { return tdim_x[n]; }
        const char *ctype(int n) const  { return ctype_x[n]; }
        double crpix(int n) const       { return crpix_x[n]; }
        double crota(int n) const       { return crota_x[n]; }
        double crval(int n) const       { return crval_x[n]; }
        double cdelt(int n) const       { return cdelt_x[n]; }
        Int theap() const               { return theap_x; }
        const char *author() const      { return author_x; }
        const char *referenc() const    { return referenc_x; }
        //</group>

        // binds a FitsField to a column
        int bind(int, FitsBase &); 

        // row selector functions
        //<group>
        BinaryTableExtension & operator ++ ();  
        BinaryTableExtension & operator -- ();
        BinaryTableExtension & operator () (int);
        //</group>

        // read entire table into memory
        int read();
        // read next N rows into memory
        int read(int);
        // prepare to write the next N rows
        int set_next(int);       
        // write current rows
        int write(FitsOutput &);
        // create a binary table header without using FitsKeywordList objet.
        int write_binTbl_hdr(FitsOutput &, long, int, const char**,
                             const char**, const char**, const char*, long );

        // select a field
        FitsBase &field(int i) const    { return *fld[i]; }
        // get current row
        Int currrow() const             { return curr_row; }
        // sets field addresses in the current row
        //void set_fitsrow(Int);

    protected:
        BinaryTableExtension(FitsInput &, FITS::HDUType, 
                             FITSErrorHandler errhandler = FITSError::defaultHandler);
        BinaryTableExtension(FitsKeywordList &, FITS::HDUType, 
                             FITSErrorHandler errhandler = FITSError::defaultHandler);
        BinaryTableExtension(FITS::HDUType, 
                             FITSErrorHandler errhandler = FITSError::defaultHandler);

        Int tfields_x;
        char **tform_x;
        double *tscal_x;
        double *tzero_x;
        Bool *isatnull_x;
        Int *tnull_x;
        char **ttype_x; 
        char **tunit_x;
        char **tdisp_x;
        char **tdim_x;
        char **ctype_x;
        double *crpix_x;
        double *crota_x;
        double *crval_x;
        double *cdelt_x;
        Int nAxis;
        Int theap_x;
        char *author_x;
        char *referenc_x;

        // read and write the next FITS data row
        //<group>
        virtual int readrow();  
        virtual int writerow(FitsOutput &);
        //</group>
        unsigned char *fitsrow; // the FITS data row buffer
        uInt *fits_offset;      // Offsets to the fields within a FITS row
        uInt fitsrowsize;       // size in bytes of a FITS data row
        Bool isoptimum;         // tells whether optimum case exists or not

        // sets field addresses in the current row
        void set_fitsrow(Int);

        unsigned char *table;   // the table in local format
        uInt tablerowsize;      // size in bytes of a table row
        uInt alloc_row;         // number of currently allocated rows
        Int beg_row;            // range of rows currently in memory
        Int end_row;
        Int curr_row;
        FitsBase **fld;         // The array of fields
        uInt *table_offset;     // Offsets to the fields within a table row
        // data addresses of fields of current row
        void **data_addr;       

    private:
        void bt_assign();
};


//<summary> (ascii) TABLE extension </summary>

class AsciiTableExtension : public BinaryTableExtension {
    public:
        AsciiTableExtension(FitsInput &, 
                            FITSErrorHandler errhandler = FITSError::defaultHandler);
        AsciiTableExtension(FitsKeywordList &, 
                            FITSErrorHandler errhandler = FITSError::defaultHandler);
        AsciiTableExtension(FITSErrorHandler errhandler = FITSError::defaultHandler);

        ~AsciiTableExtension();

        //# special overriden functions for ascii TABLE only
        // position in which column starts
        Int tbcol(int n)        { return tbcol_x[n]; }
        // ascii string that represents the NULL value
        char *tnull(int n)      { return tnulla_x[n]; }
        // write the required keywords for ASCIITableExtension
        int write_ascTbl_hdr( FitsOutput &, long,
                              long, int, const char **, long *,
                              const char **, const char **, const char *e);   

    protected:
        Int *tbcol_x;
        char **tnulla_x;
        uInt *fits_width;       // widths of the fields within a FITS row
        char **format;          // converted formats of the fields

        // read and write the next FITS data row
        //<group>
        int readrow();          
        int writerow(FitsOutput &);
        //</group>  

    private:
        void at_assign();
};


} //# NAMESPACE CASACORE - END

#ifndef CASACORE_NO_AUTO_TEMPLATES
#include <casacore/fits/FITS/hdu.tcc>
#endif //# CASACORE_NO_AUTO_TEMPLATES
# endif