casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
MIRIADImage.h
Go to the documentation of this file.
00001 //# MIRIADImage.h: Class providing native access to MIRIAD images
00002 //# Copyright (C) 2001
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: MIRIADImage.h 20299 2008-04-03 05:56:44Z gervandiepen $
00027 
00028 #ifndef IMAGES_MIRIADIMAGE_H
00029 #define IMAGES_MIRIADIMAGE_H
00030 
00031 
00032 //# Includes
00033 #include <images/Images/ImageInterface.h>
00034 #include <images/Images/MaskSpecifier.h>
00035 #include <tables/Tables/TiledFileAccess.h>
00036 #include <lattices/Lattices/TiledShape.h>
00037 #include <casa/Containers/Record.h>
00038 #include <casa/BasicSL/String.h>
00039 #include <casa/Utilities/DataType.h>
00040 
00041 
00042 namespace casa { //# NAMESPACE CASA - BEGIN
00043 
00044 //# Forward Declarations
00045 template <class T> class Array;
00046 template <class T> class Lattice;
00047 //
00048 class MaskSpecifier;
00049 class IPosition;
00050 class Slicer;
00051 class CoordinateSystem;
00052 class FITSMask;
00053 class FitsInput;
00054 
00055 
00056 // <summary>
00057 // Class providing native access to MIRIAD images.
00058 // </summary>
00059 
00060 // <use visibility=export>
00061 
00062 // <reviewed reviewer="" date="" tests="tMIRIADImage.cc">
00063 // </reviewed>
00064 
00065 // <prerequisite>
00066 //   <li> <linkto class=ImageInterface>ImageInterface</linkto>
00067 //   <li> <linkto class=FITSMask>FITSMask</linkto>
00068 // </prerequisite>
00069 
00070 // <etymology>
00071 //  This class provides native access to MIRIAD images. 
00072 // </etymology>
00073 
00074 // <synopsis> 
00075 //  A MIRIADImage provides native access to MIRIAD images by accessing them
00076 //  with the TiledFileAccess class.  -- or -- the native miriad I/O routines.
00077 //  The MIRIADImage is read only. -- really -- ??
00078 //
00079 // </synopsis> 
00080 
00081 // <example>
00082 // <srcblock>
00083 //    MIRIADImage im("cube1"); 
00084 //    LogIO logger(or);
00085 //    ImageStatistics<Float> stats(im, logger);
00086 //    Bool ok = stats.display();                              // Display statistics
00087 // </srcblock>
00088 // </example>
00089 
00090 // <motivation>
00091 // This provides native access to MIRIAD images.
00092 // </motivation>
00093 
00094 //# <todo asof="2001/09/10">
00095 //# </todo>
00096 
00097 
00098 class MIRIADImage: public ImageInterface<Float>
00099 {
00100 public: 
00101   // Construct a MIRIADImage from the disk MIRIAD dataset name and apply mask.
00102   explicit MIRIADImage(const String& name);
00103 
00104   // Construct a MIRIADImage from the disk MIRIAD file name and apply mask or not.
00105   MIRIADImage(const String& name, const MaskSpecifier&);
00106 
00107   // Copy constructor (reference semantics)
00108   MIRIADImage(const MIRIADImage& other);
00109 
00110   // Destructor does nothing
00111   ~MIRIADImage();
00112 
00113   // Assignment (reference semantics)
00114   MIRIADImage& operator=(const MIRIADImage& other);
00115 
00116   // Function to open a MIRIAD image.
00117   static LatticeBase* openMIRIADImage (const String& name,
00118                                        const MaskSpecifier&);
00119 
00120   // Register the open function.
00121   static void registerOpenFunction();
00122 
00123   //# ImageInterface virtual functions
00124   
00125   // Make a copy of the object with new (reference semantics).
00126   virtual ImageInterface<Float>* cloneII() const;
00127 
00128   // Get the image type (returns MIRIADImage).
00129   virtual String imageType() const;
00130 
00131   // Function which changes the shape of the MIRIADImage.
00132   // Throws an exception as MIRIADImage is not writable.
00133   virtual void resize(const TiledShape& newShape);
00134 
00135   // Functions which get and set the units associated with the image
00136   // pixels (i.e. the "brightness" unit). Initially the unit is empty.
00137   // Although the MIRIADimage is not writable, you can change the
00138   // unit in the MIRIADImage object, but it will not be changed 
00139   // in the MIRIAD disk file.
00140   // <group>   
00141 #if 0
00142   virtual Bool setUnits(const Unit& newUnits);
00143   virtual Unit units() const;
00144 #endif
00145   // </group>
00146 
00147   // Often we have miscellaneous information we want to attach to an image.
00148   // Although MIRIADImage is not writable, you can set a new
00149   // MiscInfo record, but it will not be stored with the MIRIAD file
00150   // <group>
00151   virtual const RecordInterface &miscInfo() const;
00152   virtual Bool setMiscInfo(const RecordInterface &newInfo);
00153   // </group>
00154 
00155   //# MaskedLattice virtual functions
00156 
00157   // Has the object really a mask?  The MIRIADImage always
00158   // has a pixel mask and never has a region mask so this
00159   // should always return True
00160   virtual Bool isMasked() const;
00161 
00162   // MIRIADimage always has a pixel mask so should return True
00163   virtual Bool hasPixelMask() const;
00164 
00165   // Get access to the pixelmask.  MIRIADImage always has a pixel mask.
00166   // <group>
00167   virtual const Lattice<Bool>& pixelMask() const;
00168   virtual Lattice<Bool>& pixelMask();
00169   // </group>
00170 
00171   // Do the actual get of the mask data.   The return value is always 
00172   // False, thus the buffer does not reference another array.
00173   virtual Bool doGetMaskSlice (Array<Bool>& buffer, const Slicer& section);
00174 
00175   // Get the region used.  There is no region. 
00176   // Always returns 0.
00177   virtual const LatticeRegion* getRegionPtr() const;
00178 
00179  
00180   //# Lattice virtual functions
00181 
00182   // Do the actual get of the data.
00183   // Returns False as the data do not reference another Array
00184   virtual Bool doGetSlice (Array<Float>& buffer, const Slicer& theSlice);
00185 
00186   // The MIRIADImage is not writable, so this throws an exception.
00187   virtual void doPutSlice (const Array<Float>& sourceBuffer,
00188                            const IPosition& where,
00189                            const IPosition& stride);
00190 
00191   //# LatticeBase virtual functions
00192 
00193   // The lattice is paged to disk.
00194   virtual Bool isPaged() const;
00195 
00196   // The lattice is persistent.
00197   virtual Bool isPersistent() const;
00198 
00199   // The MIRIADImage is not writable.
00200   virtual Bool isWritable() const;
00201 
00202   // Returns the name of the disk file.
00203   virtual String name (Bool stripPath=False) const;
00204   
00205   // return the shape of the MIRIADImage
00206   virtual IPosition shape() const;
00207 
00208   // Returns the maximum recommended number of pixels for a cursor. This is
00209   // the number of pixels in a tile. 
00210   virtual uInt advisedMaxPixels() const;
00211 
00212   // Help the user pick a cursor for most efficient access if they only want
00213   // pixel values and don't care about the order or dimension of the
00214   // cursor. 
00215   virtual IPosition doNiceCursorShape (uInt maxPixels) const;
00216 
00217   // Temporarily close the image.
00218   virtual void tempClose();
00219 
00220   // Reopen a temporarily closed image.
00221   virtual void reopen();
00222 
00223   // Check class invariants.
00224   virtual Bool ok() const;
00225 
00226   // Return the (internal) data type (TpFloat or TpShort).
00227   DataType dataType () const
00228     { return dataType_p; }
00229 
00230   // Maximum size - not necessarily all used. In pixels.
00231   virtual uInt maximumCacheSize() const;
00232 
00233   // Set the maximum (allowed) cache size as indicated.
00234   virtual void setMaximumCacheSize (uInt howManyPixels);
00235 
00236   // Set the cache size as to "fit" the indicated path.
00237   virtual void setCacheSizeFromPath (const IPosition& sliceShape,
00238                                      const IPosition& windowStart,
00239                                      const IPosition& windowLength,
00240                                      const IPosition& axisPath);
00241     
00242   // Set the actual cache size for this Array to be be big enough for the
00243   // indicated number of tiles. This cache is not shared with PagedArrays
00244   // in other rows and is always clipped to be less than the maximum value
00245   // set using the setMaximumCacheSize member function.
00246   // tiles. Tiles are cached using a first in first out algorithm. 
00247   virtual void setCacheSizeInTiles (uInt howManyTiles);
00248 
00249   // Clears and frees up the caches, but the maximum allowed cache size is 
00250   // unchanged from when setCacheSize was called
00251   virtual void clearCache();
00252 
00253   // Report on cache success.
00254   virtual void showCacheStatistics (ostream& os) const;
00255 
00256 private:  
00257   String         name_p;                          // filename, as given
00258   Int            tno_p;                           // miriad file handle
00259   MaskSpecifier  maskSpec_p;
00260   Unit           unit_p;
00261   Record         rec_p;
00262   CountedPtr<TiledFileAccess> pTiledFile_p;
00263   Lattice<Bool>* pPixelMask_p;
00264   //  Float          scale_p;
00265   //  Float          offset_p;
00266   //  Short          magic_p;
00267   TiledShape     shape_p;
00268   Bool           hasBlanks_p;
00269   DataType       dataType_p;                      // always float's for miriad
00270   Int64          fileOffset_p;                    // always 4 for direct (tiled) access
00271   Bool           isClosed_p;
00272 
00273 // Reopen the image if needed.
00274    void reopenIfNeeded() const
00275      { if (isClosed_p) const_cast<MIRIADImage*>(this)->reopen(); }
00276 
00277 // Setup the object (used by constructors).
00278    void setup();
00279 
00280 // Open the image (used by setup and reopen).
00281    void open();
00282 
00283 // Fish things out of the MIRIAD file
00284    void getImageAttributes (CoordinateSystem& cSys,
00285                             IPosition& shape, ImageInfo& info,
00286                             Unit& brightnessUnit, Record& miscInfo, 
00287                             Bool& hasBlanks, const String& name);
00288 
00289 // <group>
00290    void crackHeader (CoordinateSystem& cSys,
00291                      IPosition& shape, ImageInfo& imageInfo,
00292                      Unit& brightnessUnit, Record& miscInfo,
00293                      LogIO&os);
00294 
00295 // </group>
00296 };
00297 
00298 
00299 
00300 } //# NAMESPACE CASA - END
00301 
00302 #endif