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

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1