casacore
TiledFileAccess.h
Go to the documentation of this file.
1 //# TiledFileAccess.h: Tiled access to an array in a file
2 //# Copyright (C) 2001,2002
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 #ifndef TABLES_TILEDFILEACCESS_H
29 #define TABLES_TILEDFILEACCESS_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/tables/DataMan/TSMCube.h>
35 #include <casacore/tables/DataMan/TSMOption.h>
36 #include <casacore/casa/Utilities/DataType.h>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 //# Forward Declarations
41 class TiledFileHelper;
42 class Slicer;
43 
44 
45 // <summary>
46 // Tiled access to an array in a file.
47 // </summary>
48 
49 // <use visibility=export>
50 
51 // <reviewed reviewer="" date="" tests="tTiledFileAccess.cc">
52 // </reviewed>
53 
54 // <prerequisite>
55 //# Classes you should understand before using this one.
56 // <li> Description of Tiled Storage Manager in module file
57 // <linkto module=Tables:TiledStMan>Tables.h</linkto>
58 // <li> <linkto class=ROTiledStManAccessor>ROTiledStManAccessor</linkto>
59 // for a discussion of the maximum cache size
60 // </prerequisite>
61 
62 // <synopsis>
63 // TiledFileAccess is a class that makes it possible to access
64 // an arbitrary array in a file using the tiled storage manager classes.
65 // It can handle arrays of any type supported by the tiled storage
66 // managers. The array can be in big or little endian canonical format.
67 // <p>
68 // See <linkto class=ROTiledStManAccessor>ROTiledStManAccessor</linkto>
69 // for a more detailed discussion.
70 // </synopsis>
71 
72 // <motivation>
73 // This class makes it possible to access an image in a FITS file.
74 // </motivation>
75 
76 // <example>
77 // <srcblock>
78 // // Define the object which also opens the file.
79 // // The (float) array starts at offset 2880.
80 // TiledFileAccess tfa ("fits.file", 2880, IPosition(2,512,512),
81 // IPosition(2,512,1), TpFloat);
82 // // Get all the data.
83 // Array<Float> data = tfa.getFloat (Slicer(IPosition(2,0,0), tfa.shape()));
84 // </srcblock>
85 // </example>
86 
87 //# <todo asof="$DATE:$">
88 //# A List of bugs, limitations, extensions or planned refinements.
89 //# </todo>
90 
91 
93 {
94 public:
95  // Create a TiledFileAccess object.
96  // The data is assumed to be in local canonical format
97  // (thus big endian on e.g. SUN and little endian on e.g. PC).
98  // The TSMOption determines how the file is accessed.
99  TiledFileAccess (const String& fileName, Int64 fileOffset,
100  const IPosition& shape, const IPosition& tileShape,
101  DataType dataType,
102  const TSMOption& = TSMOption(),
103  Bool writable=False);
104 
105  // Create a TiledFileAccess object.
106  // The endian format of the data is explicitly given.
107  TiledFileAccess (const String& fileName, Int64 fileOffset,
108  const IPosition& shape, const IPosition& tileShape,
109  DataType dataType,
110  const TSMOption&,
111  Bool writable, Bool bigEndian);
112 
114 
115  // Is the file writable?
116  Bool isWritable() const
117  { return itsWritable; }
118 
119  DataType dataType() const
120  { return itsDataType; }
121 
122  // Get part of the array.
123  // The Array object is resized if needed.
124  // <group>
125  Array<Bool> getBool (const Slicer& section);
126  Array<uChar> getUChar (const Slicer& section);
127  Array<Short> getShort (const Slicer& section);
128  Array<Int> getInt (const Slicer& section);
129  Array<Float> getFloat (const Slicer& section);
130  Array<Double> getDouble (const Slicer& section);
131  Array<Complex> getComplex (const Slicer& section);
133  void get (Array<Bool>&, const Slicer& section);
134  void get (Array<uChar>&, const Slicer& section);
135  void get (Array<Short>&, const Slicer& section);
136  void get (Array<Int>&, const Slicer& section);
137  void get (Array<Float>&, const Slicer& section);
138  void get (Array<Double>&, const Slicer& section);
139  void get (Array<Complex>&, const Slicer& section);
140  void get (Array<DComplex>&, const Slicer& section);
141  // </group>
142 
143  // Get the array and scale/offset the data using the given values.
144  // It is meant for FITS, so for now they can only be used for TpUChar, TpShort
145  // or TpInt TiledFileAccess objects.
146  // A deleteValue is set to a NaN without being scaled.
147  // <group>
148  Array<Float> getFloat (const Slicer& section, Float scale, Float offset,
149  uChar deleteValue, Bool examineForDeleteValues=True);
150  Array<Float> getFloat (const Slicer& section, Float scale, Float offset,
151  Short deleteValue, Bool examineForDeleteValues=True);
152  Array<Float> getFloat (const Slicer& section, Float scale, Float offset,
153  Int deleteValue, Bool examineForDeleteValues=True);
154  void get (Array<Float>&, const Slicer& section,
155  Float scale, Float offset, uChar deleteValue,
156  Bool examineForDeleteValues=True);
157  void get (Array<Float>&, const Slicer& section,
158  Float scale, Float offset, Short deleteValue,
159  Bool examineForDeleteValues=True);
160  void get (Array<Float>&, const Slicer& section,
161  Float scale, Float offset, Int deleteValue,
162  Bool examineForDeleteValues=True);
163  // </group>
164 
165  // Put part of the array.
166  // <group>
167  void put (const Array<Bool>&, const Slicer& section);
168  void put (const Array<uChar>&, const Slicer& section);
169  void put (const Array<Short>&, const Slicer& section);
170  void put (const Array<Int>&, const Slicer& section);
171  void put (const Array<Float>&, const Slicer& section);
172  void put (const Array<Double>&, const Slicer& section);
173  void put (const Array<Complex>&, const Slicer& section);
174  void put (const Array<DComplex>&, const Slicer& section);
175  // </group>
176 
177  // Flush the cache.
178  void flush()
179  { itsCube->flushCache(); }
180 
181  // Empty the cache.
182  // It will flush the cache as needed and remove all buckets from it
183  // resulting in a possibly large drop in memory used.
184  // It'll also clear the <src>userSetCache_p</src> flag.
185  void clearCache()
186  { itsCube->emptyCache(); }
187 
188  // Show the cache statistics.
189  void showCacheStatistics (ostream& os) const
190  { itsCube->showCacheStatistics (os); }
191 
192  // Get the shape of the array.
193  const IPosition& shape() const
194  { return itsCube->cubeShape(); }
195 
196  // Get the shape of the tiles.
197  const IPosition& tileShape() const
198  { return itsCube->tileShape(); }
199 
200  // Set the maximum cache size (in bytes).
201  // 0 means no maximum.
203 
204  // Get the maximum cache size (in bytes).
206 
207  // Get the current cache size (in buckets).
208  uInt cacheSize() const
209  { return itsCube->cacheSize(); }
210 
211  // Set the cache size using the given access pattern.
212  // <group>
213  void setCacheSize (const IPosition& sliceShape,
214  const IPosition& axisPath,
215  Bool forceSmaller=True)
216  { itsCube->setCacheSize (sliceShape, IPosition(), IPosition(),
217  axisPath, forceSmaller, True); }
218  void setCacheSize (const IPosition& sliceShape,
219  const IPosition& windowStart,
220  const IPosition& windowLength,
221  const IPosition& axisPath,
222  Bool forceSmaller=True)
223  { itsCube->setCacheSize (sliceShape, windowStart, windowLength,
224  axisPath, forceSmaller, True); }
225  // </group>
226 
227  // Set the cache size for accessing the data.
228  // When the give cache size exceeds the maximum cache size with more
229  // than 10%, the maximum cache size is used instead.
230  // <br>When forceSmaller is False, the cache is not resized when the
231  // new size is smaller.
232  void setCacheSize (uInt nbuckets, Bool forceSmaller=True)
233  { itsCube->setCacheSize (nbuckets, forceSmaller, True); }
234 
235  // Make a tile shape from the array shape to fit as closely as possible
236  // the number of pixels in the tile.
237  static IPosition makeTileShape (const IPosition& arrayShape,
238  uInt nrPixelsPerTile = 32768);
239 
240 
241 private:
242  // Forbid copy constructor and assignment.
243  // <group>
246  // </group>
247 
248 
253  DataType itsDataType;
254 };
255 
256 
257 
258 } //# NAMESPACE CASACORE - END
259 
260 #endif
String: the storage and methods of handling collections of characters.
Definition: String.h:225
uInt cacheSize() const
Get the current cache size (in buckets).
void emptyCache()
Empty the cache.
virtual void showCacheStatistics(ostream &os) const
Show the cache statistics.
virtual void setCacheSize(const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath, Bool forceSmaller, Bool userSet)
Set the cache size for the given slice and access path.
const IPosition & tileShape() const
Get the shape of the tiles.
Definition: TSMCube.h:442
const IPosition & cubeShape() const
Get the shape of the hypercube.
Definition: TSMCube.h:438
virtual void flushCache()
Flush the data in the cache.
Array< Float > getFloat(const Slicer &section, Float scale, Float offset, uChar deleteValue, Bool examineForDeleteValues=True)
Get the array and scale/offset the data using the given values.
void setCacheSize(uInt nbuckets, Bool forceSmaller=True)
Set the cache size for accessing the data.
uInt cacheSize() const
Get the current cache size (in buckets).
Array< uChar > getUChar(const Slicer &section)
void get(Array< Complex > &, const Slicer &section)
Array< Float > getFloat(const Slicer &section, Float scale, Float offset, Int deleteValue, Bool examineForDeleteValues=True)
void put(const Array< Short > &, const Slicer &section)
Array< Double > getDouble(const Slicer &section)
void get(Array< Bool > &, const Slicer &section)
void put(const Array< DComplex > &, const Slicer &section)
Array< Bool > getBool(const Slicer &section)
Get part of the array.
Array< DComplex > getDComplex(const Slicer &section)
const IPosition & shape() const
Get the shape of the array.
TiledFileAccess & operator=(const TiledFileAccess &)
void put(const Array< Int > &, const Slicer &section)
void get(Array< DComplex > &, const Slicer &section)
void get(Array< Short > &, const Slicer &section)
const IPosition & tileShape() const
Get the shape of the tiles.
void clearCache()
Empty the cache.
void get(Array< Double > &, const Slicer &section)
void setCacheSize(const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath, Bool forceSmaller=True)
void put(const Array< uChar > &, const Slicer &section)
Array< Complex > getComplex(const Slicer &section)
void get(Array< Int > &, const Slicer &section)
Array< Float > getFloat(const Slicer &section)
void put(const Array< Complex > &, const Slicer &section)
Array< Int > getInt(const Slicer &section)
Bool isWritable() const
Is the file writable?
void get(Array< uChar > &, const Slicer &section)
uInt64 maximumCacheSize() const
Get the maximum cache size (in bytes).
void put(const Array< Bool > &, const Slicer &section)
Put part of the array.
void get(Array< Float > &, const Slicer &section)
void flush()
Flush the cache.
TiledFileAccess(const String &fileName, Int64 fileOffset, const IPosition &shape, const IPosition &tileShape, DataType dataType, const TSMOption &=TSMOption(), Bool writable=False)
Create a TiledFileAccess object.
Array< Float > getFloat(const Slicer &section, Float scale, Float offset, Short deleteValue, Bool examineForDeleteValues=True)
TiledFileHelper * itsTSM
void setMaximumCacheSize(uInt64 nbytes)
Set the maximum cache size (in bytes).
void put(const Array< Double > &, const Slicer &section)
void put(const Array< Float > &, const Slicer &section)
TiledFileAccess(const String &fileName, Int64 fileOffset, const IPosition &shape, const IPosition &tileShape, DataType dataType, const TSMOption &, Bool writable, Bool bigEndian)
Create a TiledFileAccess object.
void get(Array< Float > &, const Slicer &section, Float scale, Float offset, Short deleteValue, Bool examineForDeleteValues=True)
TiledFileAccess(const TiledFileAccess &)
Forbid copy constructor and assignment.
void setCacheSize(const IPosition &sliceShape, const IPosition &axisPath, Bool forceSmaller=True)
Set the cache size using the given access pattern.
Array< Short > getShort(const Slicer &section)
void showCacheStatistics(ostream &os) const
Show the cache statistics.
static IPosition makeTileShape(const IPosition &arrayShape, uInt nrPixelsPerTile=32768)
Make a tile shape from the array shape to fit as closely as possible the number of pixels in the tile...
void get(Array< Float > &, const Slicer &section, Float scale, Float offset, uChar deleteValue, Bool examineForDeleteValues=True)
void get(Array< Float > &, const Slicer &section, Float scale, Float offset, Int deleteValue, Bool examineForDeleteValues=True)
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned char uChar
Definition: aipstype.h:47
const Bool False
Definition: aipstype.h:44
short Short
Definition: aipstype.h:48
unsigned int uInt
Definition: aipstype.h:51
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
float Float
Definition: aipstype.h:54
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43
unsigned long long uInt64
Definition: aipsxtype.h:39