FITSImage.h

Go to the documentation of this file.
00001 //# FITSImage.h: Class providing native access to FITS images
00002 //# Copyright (C) 2001,2002
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id$
00027 
00028 #ifndef IMAGES_FITSIMAGE_H
00029 #define IMAGES_FITSIMAGE_H
00030 
00031 
00032 //# Includes
00033 #include <casacore/casa/aips.h>
00034 #include <casacore/images/Images/ImageInterface.h>
00035 #include <casacore/images/Images/MaskSpecifier.h>
00036 #include <casacore/tables/DataMan/TiledFileAccess.h>
00037 #include <casacore/lattices/Lattices/TiledShape.h>
00038 #include <casacore/fits/FITS/fits.h>
00039 #include <casacore/casa/BasicSL/String.h>
00040 #include <casacore/casa/Utilities/DataType.h>
00041 
00042 #ifndef WCSLIB_GETWCSTAB
00043  #define WCSLIB_GETWCSTAB
00044 #endif
00045 
00046 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00047 
00048 //# Forward Declarations
00049 template <class T> class Array;
00050 template <class T> class Lattice;
00051 //
00052 class MaskSpecifier;
00053 class IPosition;
00054 class Slicer;
00055 class CoordinateSystem;
00056 class FITSMask;
00057 class FitsInput;
00058 
00059 
00060 // <summary>
00061 // Class providing native access to FITS images.
00062 // </summary>
00063 
00064 // <use visibility=export>
00065 
00066 // <reviewed reviewer="" date="" tests="tFITSImage.cc">
00067 // </reviewed>
00068 
00069 // <prerequisite>
00070 //   <li> <linkto class=ImageInterface>ImageInterface</linkto>
00071 //   <li> <linkto class=FITSMask>FITSMask</linkto>
00072 // </prerequisite>
00073 
00074 // <etymology>
00075 //  This class provides native access to FITS images. 
00076 //  64bit, 32bit floating point, 32 bit and 16bit integer FITS images are 
00077 //  presently supported.
00078 // </etymology>
00079 
00080 // <synopsis> 
00081 //  A FITSImage provides native access to FITS images by accessing them
00082 //  with the TiledFileAccess class.  The FITSImage is read only.
00083 //  We could implement a writable FITSImage but putting the mask
00084 //  would lose data values (uses magic blanking) and FITS is really
00085 //  meant as an interchange medium, not an internal format.
00086 //
00087 //  Because FITS uses magic value blanking, the mask is generated
00088 //  on the fly as needed.
00089 // </synopsis> 
00090 
00091 // <example>
00092 // <srcblock>
00093 //    FITSImage im("in.fits"); 
00094 //    LogIO logger(or);
00095 //    ImageStatistics<Float> stats(im, logger);
00096 //    Bool ok = stats.display();                              // Display statistics
00097 // </srcblock>
00098 // </example>
00099 
00100 // <motivation>
00101 // This provides native access to FITS images.
00102 // </motivation>
00103 
00104 //# <todo asof="2001/02/09">
00105 //# </todo>
00106 
00107 
00108 class FITSImage: public ImageInterface<Float>
00109 {
00110 public: 
00111   // Construct a FITSImage from the disk FITS file name  and extension and apply mask.
00112   explicit FITSImage(const String& name, uInt whichRep=0, uInt whichHDU=0);
00113 
00114   // Construct a FITSImage from the disk FITS file name and extension and apply mask or not.
00115   FITSImage(const String& name, const MaskSpecifier& mask, uInt whichRep=0, uInt whichHDU=0);
00116 
00117   // Copy constructor (reference semantics)
00118   FITSImage(const FITSImage& other);
00119 
00120   // Destructor does nothing
00121   virtual ~FITSImage();
00122 
00123   // Assignment (reference semantics)
00124   FITSImage& operator=(const FITSImage& other);
00125 
00126   // Function to open a FITS image (new parser)
00127   static LatticeBase* openFITSImage (const String& name,
00128                                      const MaskSpecifier&);
00129 
00130   // Register the open function.
00131   static void registerOpenFunction();
00132 
00133   // Separate any extension specification and return the pure fitsname
00134   static String get_fitsname(const String &fullname);
00135 
00136   // Get the extension index for any extension specification given in the full name
00137   static uInt get_hdunum(const String &fullname);
00138 
00139   //# ImageInterface virtual functions
00140   
00141   // Make a copy of the object with new (reference semantics).
00142   virtual ImageInterface<Float>* cloneII() const;
00143 
00144   // Get the image type (returns FITSImage).
00145   virtual String imageType() const;
00146 
00147   // Function which changes the shape of the FITSImage.
00148   // Throws an exception as FITSImage is not writable.
00149   virtual void resize(const TiledShape& newShape);
00150 
00151   //# MaskedLattice virtual functions
00152 
00153   // Has the object really a mask?  The FITSImage always
00154   // has a pixel mask and never has a region mask so this
00155   // always returns True
00156   virtual Bool isMasked() const;
00157 
00158   // FITSimage always has a pixel mask so returns True
00159   virtual Bool hasPixelMask() const;
00160 
00161   // Get access to the pixelmask.  FITSImage always has a pixel mask.
00162   // <group>
00163   virtual const Lattice<Bool>& pixelMask() const;
00164   virtual Lattice<Bool>& pixelMask();
00165   // </group>
00166 
00167   // Do the actual get of the mask data.   The return value is always 
00168   // False, thus the buffer does not reference another array.
00169   virtual Bool doGetMaskSlice (Array<Bool>& buffer, const Slicer& section);
00170 
00171   // Get the region used.  There is no region. 
00172   // Always returns 0.
00173   virtual const LatticeRegion* getRegionPtr() const;
00174 
00175  
00176   //# Lattice virtual functions
00177 
00178   // Do the actual get of the data.
00179   // Returns False as the data do not reference another Array
00180   virtual Bool doGetSlice (Array<Float>& buffer, const Slicer& theSlice);
00181 
00182   // The FITSImage is not writable, so this throws an exception.
00183   virtual void doPutSlice (const Array<Float>& sourceBuffer,
00184                            const IPosition& where,
00185                            const IPosition& stride);
00186 
00187   //# LatticeBase virtual functions
00188 
00189   // The lattice is paged to disk.
00190   virtual Bool isPaged() const;
00191 
00192   // The lattice is persistent.
00193   virtual Bool isPersistent() const;
00194 
00195   // The FITSImage is not writable.
00196   virtual Bool isWritable() const;
00197 
00198   // Returns the name of the disk file.
00199   virtual String name (Bool stripPath=False) const;
00200   
00201   // return the shape of the FITSImage
00202   virtual IPosition shape() const;
00203 
00204   // Returns the maximum recommended number of pixels for a cursor. This is
00205   // the number of pixels in a tile. 
00206   virtual uInt advisedMaxPixels() const;
00207 
00208   // Help the user pick a cursor for most efficient access if they only want
00209   // pixel values and don't care about the order or dimension of the
00210   // cursor. 
00211   virtual IPosition doNiceCursorShape (uInt maxPixels) const;
00212 
00213   // Temporarily close the image.
00214   virtual void tempClose();
00215 
00216   // Reopen a temporarily closed image.
00217   virtual void reopen();
00218 
00219   // Check class invariants.
00220   virtual Bool ok() const;
00221 
00222   // Return the data type (TpFloat).
00223   virtual DataType dataType() const;
00224 
00225   // Return the (internal) data type.
00226   DataType internalDataType() const
00227     { return dataType_p; }
00228 
00229   // Return the HDU number
00230   uInt whichHDU () const
00231     { return whichHDU_p; }
00232 
00233   // Maximum size - not necessarily all used. In pixels.
00234   virtual uInt maximumCacheSize() const;
00235 
00236   // Set the maximum (allowed) cache size as indicated.
00237   virtual void setMaximumCacheSize (uInt howManyPixels);
00238 
00239   // Set the cache size as to "fit" the indicated path.
00240   virtual void setCacheSizeFromPath (const IPosition& sliceShape,
00241                                      const IPosition& windowStart,
00242                                      const IPosition& windowLength,
00243                                      const IPosition& axisPath);
00244     
00245   // Set the actual cache size for this Array to be be big enough for the
00246   // indicated number of tiles. This cache is not shared with PagedArrays
00247   // in other rows and is always clipped to be less than the maximum value
00248   // set using the setMaximumCacheSize member function.
00249   // tiles. Tiles are cached using a first in first out algorithm. 
00250   virtual void setCacheSizeInTiles (uInt howManyTiles);
00251 
00252   // Clears and frees up the caches, but the maximum allowed cache size is 
00253   // unchanged from when setCacheSize was called
00254   virtual void clearCache();
00255 
00256   // Report on cache success.
00257   virtual void showCacheStatistics (ostream& os) const;
00258 
00259 protected:
00260   // Set the masking of values 0.0
00261   void setMaskZero(Bool filterZero);
00262 
00263 private:  
00264   String         name_p;
00265   String         fullname_p;
00266   MaskSpecifier  maskSpec_p;
00267   CountedPtr<TiledFileAccess> pTiledFile_p;
00268   Lattice<Bool>* pPixelMask_p;
00269   TiledShape     shape_p;
00270   Float          scale_p;
00271   Float          offset_p;
00272   Short          shortMagic_p;
00273   uChar          uCharMagic_p;
00274   Int            longMagic_p;
00275   Bool           hasBlanks_p;
00276   DataType       dataType_p;
00277   Int64          fileOffset_p;
00278   Bool           isClosed_p;
00279   Bool           filterZeroMask_p;
00280   uInt           whichRep_p;
00281   uInt           whichHDU_p;
00282   Bool           _hasBeamsTable;
00283 
00284 // Reopen the image if needed.
00285    void reopenIfNeeded() const
00286      { if (isClosed_p) const_cast<FITSImage*>(this)->reopen(); }
00287 
00288 // Setup the object (used by constructors).
00289    void setup();
00290 
00291 // Open the image (used by setup and reopen).
00292    void open();
00293 
00294 // Fish things out of the FITS file
00295    void getImageAttributes (CoordinateSystem& cSys,
00296                             IPosition& shape, ImageInfo& info,
00297                             Unit& brightnessUnit, RecordInterface& miscInfo, 
00298                             Int& recsize, Int& recno,
00299                             FITS::ValueType& dataType,
00300                             Float& scale, Float& offset, 
00301                             uChar& uCharMagic, Short& shortMagic, 
00302                             Int& longMagic, Bool& hasBlanks, const String& name,
00303                             uInt whichRep, uInt whichHDU);
00304 
00305 // Crack a primary header
00306    template <typename T>
00307    void crackHeader (CoordinateSystem& cSys, IPosition& shape, ImageInfo& imageInfo,
00308                      Unit& brightnessUnit, RecordInterface& miscInfo,
00309                      Float& scale, Float& offset, uChar& magicUChar, Short& magicShort,
00310                      Int& magicLong, Bool& hasBlanks, LogIO& os, FitsInput& infile,
00311                      uInt whichRep);
00312 
00313 // Crack an image extension header
00314    template <typename T>
00315    void crackExtHeader (CoordinateSystem& cSys, IPosition& shape, ImageInfo& imageInfo,
00316                         Unit& brightnessUnit, RecordInterface& miscInfo,
00317                         Float& scale, Float& offset, uChar& uCharMagic,
00318                         Short& magicShort,
00319                         Int& magicLong, Bool& hasBlanks, LogIO& os, FitsInput& infile,
00320                         uInt whichRep);
00321                      
00322 };
00323 
00324 
00325 
00326 } //# NAMESPACE CASACORE - END
00327 
00328 #ifndef CASACORE_NO_AUTO_TEMPLATES
00329 #include <casacore/images/Images/FITS2Image.tcc>
00330 #endif //# CASACORE_NO_AUTO_TEMPLATES
00331 
00332 #endif
00333 
00334 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1