casacore
Loading...
Searching...
No Matches
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
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40//# Forward Declarations
41class TiledFileHelper;
42class 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{
94public:
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?
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);
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.
186 { itsCube->emptyCache(); }
187
188 // Show the cache statistics.
189 void showCacheStatistics (ostream& os) const
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).
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
241private:
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< Complex > getComplex(const Slicer &section)
void setCacheSize(uInt nbuckets, Bool forceSmaller=True)
Set the cache size for accessing the data.
const IPosition & tileShape() const
Get the shape of the tiles.
uInt cacheSize() const
Get the current cache size (in buckets).
Array< Short > getShort(const Slicer &section)
void get(Array< Complex > &, const Slicer &section)
void put(const Array< Short > &, const Slicer &section)
void get(Array< Bool > &, const Slicer &section)
void put(const Array< DComplex > &, const Slicer &section)
Array< DComplex > getDComplex(const Slicer &section)
Array< Bool > getBool(const Slicer &section)
Get part of the array.
void put(const Array< Int > &, const Slicer &section)
void get(Array< DComplex > &, const Slicer &section)
void get(Array< Short > &, const Slicer &section)
Array< uChar > getUChar(const Slicer &section)
void clearCache()
Empty the cache.
Array< Float > getFloat(const Slicer &section, Float scale, Float offset, Int deleteValue, Bool examineForDeleteValues=True)
void get(Array< Double > &, const Slicer &section)
const IPosition & shape() const
Get the shape of the array.
void setCacheSize(const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath, Bool forceSmaller=True)
Array< Float > getFloat(const Slicer &section)
void put(const Array< uChar > &, const Slicer &section)
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 get(Array< Int > &, const Slicer &section)
void put(const Array< Complex > &, const Slicer &section)
TiledFileAccess & operator=(const TiledFileAccess &)
Bool isWritable() const
Is the file writable?
Array< Float > getFloat(const Slicer &section, Float scale, Float offset, Short deleteValue, Bool examineForDeleteValues=True)
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.
void setMaximumCacheSize(uInt64 nbytes)
Set the maximum cache size (in bytes).
Array< Int > getInt(const Slicer &section)
void put(const Array< Double > &, const Slicer &section)
Array< Double > getDouble(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.
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