casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
TiledFileAccess.h
Go to the documentation of this file.
00001 //# TiledFileAccess.h: Tiled access to an array in a file
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: TiledFileAccess.h 21249 2012-05-18 01:38:49Z Malte.Marquarding $
00027 
00028 #ifndef TABLES_TILEDFILEACCESS_H
00029 #define TABLES_TILEDFILEACCESS_H
00030 
00031 
00032 //# Includes
00033 #include <tables/Tables/TSMCube.h>
00034 #include <tables/Tables/TSMOption.h>
00035 #include <casa/Utilities/DataType.h>
00036 
00037 namespace casa { //# NAMESPACE CASA - BEGIN
00038 
00039 //# Forward Declarations
00040 class TiledFileHelper;
00041 class Slicer;
00042 
00043 
00044 // <summary>
00045 // Tiled access to an array in a file.
00046 // </summary>
00047 
00048 // <use visibility=export>
00049 
00050 // <reviewed reviewer="" date="" tests="tTiledFileAccess.cc">
00051 // </reviewed>
00052 
00053 // <prerequisite>
00054 //# Classes you should understand before using this one.
00055 //   <li> Description of Tiled Storage Manager in module file
00056 //        <linkto module=Tables:TiledStMan>Tables.h</linkto>
00057 //   <li> <linkto class=ROTiledStManAccessor>ROTiledStManAccessor</linkto>
00058 //        for a discussion of the maximum cache size
00059 // </prerequisite>
00060 
00061 // <synopsis> 
00062 // TiledFileAccess is a class that makes it possible to access
00063 // an arbitrary array in a file using the tiled storage manager classes.
00064 // It can handle arrays of any type supported by the tiled storage
00065 // managers. The array can be in big or little endian canonical format.
00066 // <p>
00067 // See <linkto class=ROTiledStManAccessor>ROTiledStManAccessor</linkto>
00068 // for a more detailed discussion.
00069 // </synopsis> 
00070 
00071 // <motivation>
00072 // This class makes it possible to access an image in a FITS file.
00073 // </motivation>
00074 
00075 // <example>
00076 // <srcblock>
00077 //  // Define the object which also opens the file.
00078 //  // The (float) array starts at offset 2880.
00079 //  TiledFileAccess tfa ("fits.file", 2880, IPosition(2,512,512),
00080 //                       IPosition(2,512,1), TpFloat);
00081 //  // Get all the data.
00082 //  Array<Float> data = tfa.getFloat (Slicer(IPosition(2,0,0), tfa.shape()));
00083 // </srcblock>
00084 // </example>
00085 
00086 //# <todo asof="$DATE:$">
00087 //# A List of bugs, limitations, extensions or planned refinements.
00088 //# </todo>
00089 
00090 
00091 class TiledFileAccess
00092 {
00093 public:
00094   // Create a TiledFileAccess object.
00095   // The data is assumed to be in local canonical format
00096   // (thus big endian on e.g. SUN and little endian on e.g. PC).
00097   // The TSMOption determines how the file is accessed.
00098   TiledFileAccess (const String& fileName, Int64 fileOffset,
00099                    const IPosition& shape, const IPosition& tileShape,
00100                    DataType dataType, 
00101                    const TSMOption& = TSMOption(),
00102                    Bool writable=False);
00103 
00104   // Create a TiledFileAccess object.
00105   // The endian format of the data is explicitly given.
00106   TiledFileAccess (const String& fileName, Int64 fileOffset,
00107                    const IPosition& shape, const IPosition& tileShape,
00108                    DataType dataType,
00109                    const TSMOption&,
00110                    Bool writable, Bool bigEndian);
00111 
00112   ~TiledFileAccess();
00113 
00114   // Is the file writable?
00115   Bool isWritable() const
00116     { return itsWritable; }
00117 
00118   DataType dataType() const
00119     { return itsDataType; }
00120 
00121   // Get part of the array.
00122   // The Array object is resized if needed.
00123   // <group>
00124   Array<Bool>     getBool     (const Slicer& section);
00125   Array<uChar>    getUChar    (const Slicer& section);
00126   Array<Short>    getShort    (const Slicer& section);
00127   Array<Int>      getInt      (const Slicer& section);
00128   Array<Float>    getFloat    (const Slicer& section);
00129   Array<Double>   getDouble   (const Slicer& section);
00130   Array<Complex>  getComplex  (const Slicer& section);
00131   Array<DComplex> getDComplex (const Slicer& section);
00132   void get (Array<Bool>&, const Slicer& section);
00133   void get (Array<uChar>&, const Slicer& section);
00134   void get (Array<Short>&, const Slicer& section);
00135   void get (Array<Int>&, const Slicer& section);
00136   void get (Array<Float>&, const Slicer& section);
00137   void get (Array<Double>&, const Slicer& section);
00138   void get (Array<Complex>&, const Slicer& section);
00139   void get (Array<DComplex>&, const Slicer& section);
00140   // </group>
00141 
00142   // Get the array and scale/offset the data using the given values.
00143   // It is meant for FITS, so for now they can only be used for TpUChar, TpShort
00144   // or TpInt TiledFileAccess objects.
00145   // A deleteValue is set to a NaN without being scaled.
00146   // <group>
00147   Array<Float> getFloat (const Slicer& section, Float scale, Float offset,
00148                          uChar deleteValue, Bool examineForDeleteValues=True);
00149   Array<Float> getFloat (const Slicer& section, Float scale, Float offset,
00150                          Short deleteValue, Bool examineForDeleteValues=True);
00151   Array<Float> getFloat (const Slicer& section, Float scale, Float offset,
00152                          Int deleteValue, Bool examineForDeleteValues=True);
00153   void get (Array<Float>&, const Slicer& section,
00154             Float scale, Float offset, uChar deleteValue,
00155             Bool examineForDeleteValues=True);
00156   void get (Array<Float>&, const Slicer& section,
00157             Float scale, Float offset, Short deleteValue,
00158             Bool examineForDeleteValues=True);
00159   void get (Array<Float>&, const Slicer& section,
00160             Float scale, Float offset, Int deleteValue,
00161             Bool examineForDeleteValues=True);
00162   // </group>
00163 
00164   // Put part of the array.
00165   // <group>
00166   void put (const Array<Bool>&, const Slicer& section);
00167   void put (const Array<uChar>&, const Slicer& section);
00168   void put (const Array<Short>&, const Slicer& section);
00169   void put (const Array<Int>&, const Slicer& section);
00170   void put (const Array<Float>&, const Slicer& section);
00171   void put (const Array<Double>&, const Slicer& section);
00172   void put (const Array<Complex>&, const Slicer& section);
00173   void put (const Array<DComplex>&, const Slicer& section);
00174   // </group>
00175 
00176   // Flush the cache.
00177   void flush()
00178     { itsCube->flushCache(); }
00179 
00180   // Empty the cache.
00181   // It will flush the cache as needed and remove all buckets from it
00182   // resulting in a possibly large drop in memory used.
00183   // It'll also clear the <src>userSetCache_p</src> flag.
00184   void clearCache()
00185     { itsCube->emptyCache(); }
00186 
00187   // Show the cache statistics.
00188   void showCacheStatistics (ostream& os) const
00189     { itsCube->showCacheStatistics (os); }
00190 
00191   // Get the shape of the array.
00192   const IPosition& shape() const
00193     { return itsCube->cubeShape(); }
00194 
00195   // Get the shape of the tiles.
00196   const IPosition& tileShape() const
00197     { return itsCube->tileShape(); }
00198 
00199   // Set the maximum cache size (in bytes).
00200   // 0 means no maximum.
00201   void setMaximumCacheSize (uInt nbytes);
00202 
00203   // Get the maximum cache size (in bytes).
00204   uInt maximumCacheSize() const;
00205 
00206   // Get the current cache size (in buckets).
00207   uInt cacheSize() const
00208     { return itsCube->cacheSize(); }
00209 
00210   // Set the cache size using the given access pattern.
00211   // <group>
00212   void setCacheSize (const IPosition& sliceShape,
00213                      const IPosition& axisPath,
00214                      Bool forceSmaller=True)
00215     { itsCube->setCacheSize (sliceShape, IPosition(), IPosition(),
00216                              axisPath, forceSmaller, True); }
00217   void setCacheSize (const IPosition& sliceShape,
00218                      const IPosition& windowStart,
00219                      const IPosition& windowLength,
00220                      const IPosition& axisPath,
00221                      Bool forceSmaller=True)
00222     { itsCube->setCacheSize (sliceShape, windowStart, windowLength,
00223                              axisPath, forceSmaller, True); }
00224   // </group>
00225 
00226   // Set the cache size for accessing the data.
00227   // When the give cache size exceeds the maximum cache size with more
00228   // than 10%, the maximum cache size is used instead.
00229   // <br>When forceSmaller is False, the cache is not resized when the
00230   // new size is smaller.
00231   void setCacheSize (uInt nbuckets, Bool forceSmaller=True)
00232     { itsCube->setCacheSize (nbuckets, forceSmaller, True); }
00233 
00234   // Make a tile shape from the array shape to fit as closely as possible
00235   // the number of pixels in the tile.
00236   static IPosition makeTileShape (const IPosition& arrayShape,
00237                                   uInt nrPixelsPerTile = 32768);
00238 
00239 
00240 private:
00241   // Forbid copy constructor and assignment.
00242   // <group>
00243   TiledFileAccess (const TiledFileAccess&);
00244   TiledFileAccess& operator= (const TiledFileAccess&);
00245   // </group>
00246 
00247 
00248   TSMCube*         itsCube;
00249   TiledFileHelper* itsTSM;
00250   uInt             itsLocalPixelSize;
00251   Bool             itsWritable;
00252   DataType         itsDataType;
00253 };
00254 
00255 
00256 
00257 } //# NAMESPACE CASA - END
00258 
00259 #endif