fitshandle.h

Go to the documentation of this file.
00001 /*
00002  *  This file is part of libcxxsupport.
00003  *
00004  *  libcxxsupport is free software; you can redistribute it and/or modify
00005  *  it under the terms of the GNU General Public License as published by
00006  *  the Free Software Foundation; either version 2 of the License, or
00007  *  (at your option) any later version.
00008  *
00009  *  libcxxsupport is distributed in the hope that it will be useful,
00010  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00011  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00012  *  GNU General Public License for more details.
00013  *
00014  *  You should have received a copy of the GNU General Public License
00015  *  along with libcxxsupport; if not, write to the Free Software
00016  *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
00017  */
00018 
00019 /*
00020  *  libcxxsupport is being developed at the Max-Planck-Institut fuer Astrophysik
00021  *  and financially supported by the Deutsches Zentrum fuer Luft- und Raumfahrt
00022  *  (DLR).
00023  */
00024 
00025 /*! \file fitshandle.h
00026  *  Declaration of the FITS I/O helper class used by LevelS
00027  *
00028  *  Copyright (C) 2002-2014 Max-Planck-Society
00029  *  \author Martin Reinecke
00030  */
00031 
00032 #ifndef PLANCK_FITSHANDLE_H
00033 #define PLANCK_FITSHANDLE_H
00034 
00035 #include <string>
00036 #include <vector>
00037 #include "arr.h"
00038 #include "datatypes.h"
00039 #include "safe_cast.h"
00040 
00041 /*! \defgroup fitsgroup FITS-related functionality */
00042 /*! \{ */
00043 
00044 /*! Class containing information about a single column in a FITS table. */
00045 class fitscolumn
00046   {
00047   private:
00048     std::string name_, unit_;
00049     int64 repcount_;
00050     PDT type_;
00051 
00052   public:
00053     fitscolumn();
00054     /*! Creates a \a fitscolumn with name \a nm, unit \a un, a repetition
00055         count of \a rc, and a Planck type of \a tp. */
00056     fitscolumn (const std::string &nm, const std::string &un, int64 rc, PDT tp);
00057     ~fitscolumn();
00058 
00059     /*! Returns the column name. */
00060     const std::string &name() const {return name_;}
00061     /*! Returns the column unit string. */
00062     const std::string &unit() const {return unit_;}
00063     /*! Returns the repetition count of the column. */
00064     int64 repcount() const {return repcount_;}
00065     /*! Returns the Planck type of the column. */
00066     PDT type() const {return type_;}
00067   };
00068 
00069 /*! Class for performing I/O from/to FITS files. */
00070 class fitshandle
00071   {
00072   private:
00073     enum { INVALID = -4711 };
00074 
00075     mutable int status;
00076     void *fptr;
00077     int hdutype_, bitpix_;
00078     std::vector<int64> axes_;
00079     std::vector<fitscolumn> columns_;
00080     int64 nrows_;
00081 
00082     void check_errors() const;
00083 
00084     void clean_data();
00085     void clean_all();
00086 
00087     bool connected() const { return (hdutype_!=INVALID); }
00088     bool table_hdu (tsize col) const;
00089     bool image_hdu () const;
00090 
00091     void init_image();
00092     void init_asciitab();
00093     void init_bintab();
00094     void init_data();
00095 
00096     void read_col (int colnum, void *data, int64 ndata, PDT type,
00097                    int64 offset) const;
00098     void write_col (int colnum, const void *data, int64 ndata, PDT type,
00099                    int64 offset);
00100 
00101     void getKeyHelper(const std::string &name) const;
00102 
00103   public:
00104     /*! the list of modes in which a \a fitshandle can be opened. */
00105     enum openmethod { CREATE, /*!< the file must not yet exist */
00106                       OPEN    /*!< the file must already exist */
00107                     };
00108 
00109     /*! \name File-level access and manipulation. */
00110     /*! \{ */
00111 
00112     /*! Creates an unconnected \a fitshandle. */
00113     fitshandle ();
00114     /*! Performs all necessary cleanups. */
00115     ~fitshandle();
00116 
00117     /*! Connects to the file \a fname. */
00118     void open (const std::string &fname);
00119     /*! Creates the file \a fname and connects to it. */
00120     void create (const std::string &fname);
00121     /*! Closes the current file. */
00122     void close () { clean_all(); }
00123     /*! Deletes the file with name \a name. */
00124     static void delete_file (const std::string &name);
00125     /*! Returns the name of the connected file. */
00126     std::string fileName() const;
00127     /*! Jumps to the HDU with the absolute number \a hdu. */
00128     void goto_hdu (int hdu);
00129     /*! Returns the number of HDUs in the file. */
00130     int num_hdus () const;
00131     /*! Asserts that the PDMTYPE of the current HDU is \a pdmtype. */
00132     void assert_pdmtype (const std::string &pdmtype) const;
00133     /*! Inserts a binary table described by \a cols.
00134         The HDU has the name \a extname. */
00135     void insert_bintab (const std::vector<fitscolumn> &cols,
00136       const std::string &extname="xtension");
00137     /*! Inserts an ASCII table described by \a cols. The width of the
00138         columns is chosen automatically, in a way that avoids truncation.
00139         The HDU has the name \a extname. */
00140     void insert_asctab (const std::vector<fitscolumn> &cols,
00141       const std::string &extname="xtension");
00142     /*! Inserts a FITS image with the type given by \a type and dimensions
00143         given by \a Axes. */
00144     void insert_image (PDT type, const std::vector<int64> &Axes);
00145     /*! Inserts a 2D FITS image with the type given by \a type, whose
00146         contents are given in \a data. */
00147     template<typename T>
00148       void insert_image (PDT type, const arr2<T> &data);
00149 
00150     /*! Computes the checksum for the current HDU and writes it into the
00151         header. */
00152     void write_checksum();
00153 
00154     /*! \} */
00155 
00156     /*! \name Information about the current HDU */
00157     /*! \{ */
00158 
00159     /*! Returns the dimensions of the current image. */
00160     const std::vector<int64> &axes() const;
00161     /*! Returns the name of column \a #i. */
00162     const std::string &colname(int i) const;
00163     /*! Returns the unit of column \a #i. */
00164     const std::string &colunit(int i) const;
00165     /*! Returns repetition count of column \a #i. */
00166     int64 repcount(int i) const;
00167     /*! Returns the Planck type for column \a #i. */
00168     PDT coltype(int i) const;
00169     /*! Returns the number of columns in the current table. */
00170     int ncols() const;
00171     /*! Returns the number of rows in the current table. */
00172     int64 nrows() const;
00173     /*! Returns the total number of elements (nrows*repcount)
00174         in column \a #i. */
00175     int64 nelems(int i) const;
00176     /*! Returns the number of elements that should be read/written in a single
00177         call for optimum performance. This depends on the current HDU. */
00178     int64 efficientChunkSize(int i) const;
00179 
00180     /*! \} */
00181 
00182     /*! \name Keyword-handling methods */
00183     /*! \{ */
00184 
00185     /*! Returns a list of all user-defined keys in the current HDU
00186         in \a keys. */
00187     void get_all_keys (std::vector<std::string> &keys) const;
00188 
00189     void set_key_void (const std::string &key, const void *value, PDT type,
00190       const std::string &comment="");
00191     /*! Updates \a key with \a value and \a comment. */
00192     template<typename T> void set_key (const std::string &name,
00193       const T &value, const std::string &comment="")
00194       { set_key_void (name, &value, planckType<T>(), comment); }
00195     /*! Deletes \a key from the header. */
00196     void delete_key (const std::string &name);
00197     /*! Adds \a comment as a comment line. */
00198     void add_comment (const std::string &comment);
00199     void get_key_void (const std::string &key, void *value, PDT type) const;
00200     /*! Reads the value belonging to \a key and returns it in \a value. */
00201     template<typename T> void get_key (const std::string &name, T &value) const
00202       { get_key_void (name,&value,planckType<T>()); }
00203     /*! Returms the value belonging to \a key. */
00204     template<typename T> T get_key (const std::string &name) const
00205       { T tmp; get_key(name, tmp); return tmp; }
00206     /*! Returns \a true if \a key is present, else \a false. */
00207     bool key_present (const std::string &name) const;
00208 
00209     /*! \} */
00210 
00211     /*! \name Methods for table data I/O */
00212     /*! \{ */
00213 
00214     void read_column_raw_void
00215       (int colnum, void *data, PDT type, int64 num, int64 offset=0) const;
00216     /*! Copies \a num elements from column \a colnum to the memory pointed
00217         to by \a data, starting at offset \a offset in the column. */
00218     template<typename T> void read_column_raw
00219       (int colnum, T *data, int64 num, int64 offset=0) const
00220       { read_column_raw_void (colnum, data, planckType<T>(), num, offset); }
00221     /*! Fills \a data with elements from column \a colnum,
00222         starting at offset \a offset in the column. */
00223     template<typename T> void read_column
00224       (int colnum, arr<T> &data, int64 offset=0) const
00225       { read_column_raw (colnum, &(data[0]), data.size(), offset); }
00226     /*! Fills \a data with elements from column \a colnum,
00227         starting at offset \a offset in the column. */
00228     template<typename T> void read_column
00229       (int colnum, std::vector<T> &data, int64 offset=0) const
00230       { read_column_raw (colnum, &(data[0]), data.size(), offset); }
00231     /*! Reads the element \a #offset from column \a colnum into \a data. */
00232     template<typename T> void read_column
00233       (int colnum, T &data, int64 offset=0) const
00234       { read_column_raw (colnum, &data, 1, offset); }
00235     /*! Reads the whole column \a colnum into \a data (which is resized
00236        accordingly). */
00237     template<typename T> void read_entire_column
00238       (int colnum, arr<T> &data) const
00239       {
00240       data.alloc(safe_cast<tsize>(nelems(colnum)));
00241       read_column (colnum, data);
00242       }
00243     /*! Reads the whole column \a colnum into \a data (which is resized
00244        accordingly). */
00245     template<typename T> void read_entire_column
00246       (int colnum, std::vector<T> &data) const
00247       {
00248       data.resize(safe_cast<tsize>(nelems(colnum)));
00249       read_column (colnum, data);
00250       }
00251 
00252     void write_column_raw_void
00253       (int colnum, const void *data, PDT type, int64 num, int64 offset=0);
00254     /*! Copies \a num elements from the memory pointed to by \a data to the
00255         column \a colnum, starting at offset \a offset in the column. */
00256     template<typename T> void write_column_raw
00257       (int colnum, const T *data, int64 num, int64 offset=0)
00258       { write_column_raw_void (colnum, data, planckType<T>(), num, offset); }
00259     /*! Copies all elements from \a data to the
00260         column \a colnum, starting at offset \a offset in the column. */
00261     template<typename T> void write_column
00262       (int colnum, const arr<T> &data, int64 offset=0)
00263       { write_column_raw (colnum, &(data[0]), data.size(), offset); }
00264     /*! Copies all elements from \a data to the
00265         column \a colnum, starting at offset \a offset in the column. */
00266     template<typename T> void write_column
00267       (int colnum, const std::vector<T> &data, int64 offset=0)
00268       { write_column_raw (colnum, &(data[0]), data.size(), offset); }
00269     /*! Copies \a data to the column \a colnum, at the position \a offset. */
00270     template<typename T> void write_column
00271       (int colnum, const T &data, int64 offset=0)
00272       { write_column_raw (colnum, &data, 1, offset); }
00273 
00274     /*! \} */
00275 
00276     /*! \name Methods for image data I/O */
00277     /*! \{ */
00278 
00279     /*! Reads the current image into \a data, which is resized accordingly. */
00280     template<typename T> void read_image (arr2<T> &data) const;
00281     /*! Reads the current image into \a data, which is resized accordingly. */
00282     template<typename T> void read_image (arr3<T> &data) const;
00283     /*! Reads a partial image, whose dimensions are given by the dimensions
00284         of \a data, into data. The starting pixel indices are given by
00285         \a xl and \a yl. */
00286     template<typename T> void read_subimage
00287       (arr2<T> &data, int xl, int yl) const;
00288     void read_subimage_void (void *data, PDT type, tsize ndata, int64 offset=0)
00289       const;
00290     /*! Fills \a data with values from the image, starting at the offset
00291         \a offset in the image. The image is treated as a one-dimensional
00292         array. */
00293     template<typename T> void read_subimage (arr<T> &data, int64 offset=0)
00294       const
00295       { read_subimage_void (&data[0],planckType<T>(),data.size(),offset); }
00296 
00297     void write_image2D_void (const void *data, PDT type, tsize s1,
00298       tsize s2);
00299     /*! Writes \a data into the current image. \a data must have the same
00300         dimensions as specified in the HDU. */
00301     template<typename T> void write_image (const arr2<T> &data)
00302       {
00303       write_image2D_void (&data[0][0],planckType<T>(),data.size1(),
00304                           data.size2());
00305       }
00306 
00307     void write_subimage_void (const void *data, PDT type, tsize sz,
00308       int64 offset);
00309     /*! Copies \a data to the image, starting at the offset
00310         \a offset in the image. The image is treated as a one-dimensional
00311         array. */
00312     template<typename T> void write_subimage (const arr<T> &data,
00313       int64 offset=0)
00314       { write_subimage_void(&data[0],planckType<T>(),data.size(),offset); }
00315 
00316     /*! \} */
00317   };
00318 
00319 /*! \} */
00320 
00321 #endif

Generated on Thu Oct 8 14:48:51 2015 for LevelS C++ support library