casacore
Loading...
Searching...
No Matches
HDF5Lattice.h
Go to the documentation of this file.
1//# HDF5Lattice.h: Templated paged array in an HDF5 file
2//# Copyright (C) 2008
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 LATTICES_HDF5LATTICE_H
29#define LATTICES_HDF5LATTICE_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/lattices/Lattices/Lattice.h>
34#include <casacore/lattices/Lattices/TiledShape.h>
35#include <casacore/casa/HDF5/HDF5File.h>
36#include <casacore/casa/HDF5/HDF5Group.h>
37#include <casacore/casa/HDF5/HDF5DataSet.h>
38#include <casacore/casa/BasicSL/String.h>
39
40namespace casacore { //# NAMESPACE CASACORE - BEGIN
41
42 // <summary>
43 // A Lattice that is read from or written to an HDF5 dataset.
44 // </summary>
45
46 // <use visibility=export>
47
48 // <reviewed reviewer="" date="" tests="tHDF5Lattice.cc">
49 // </reviewed>
50
51 // <prerequisite>
52 // <li> <linkto class="PagedArray">PagedArray</linkto>
53 // <li> <linkto class="TiledShape">TiledShape</linkto>
54 // <li> <linkto class="HDF5File">HDF5File</linkto>
55 // </prerequisite>
56
57 // <synopsis>
58 // Astronomical data arrays (like images) have to be persistent.
59 // A Lattice is a templated abstract base class to hold any Casacore array.
60 // The PagedArray class is a Lattice specialization which stores the data
61 // in a Casacore table.
62 // <br>
63 // HDF5Lattice ia another Lattice specialization making it possible to store
64 // an array as a dataset in a group in an HDF5 file.
65 // <p>
66 // When you construct an HDF5Lattice you do not read any data into
67 // memory. Instead an HDF5 disk file is created, in a place you
68 // specify, to hold the data. This means you need to have enough disk space
69 // to hold the array. Constructing a new HDF5Lattice is equivalent to
70 // creating a data set in an HDF5 file.
71 // <p>
72 // To access the data in a HDF5Lattice you can (in order of preference):
73 // <ol>
74 // <li> Use a <linkto class=LatticeIterator>LatticeIterator</linkto>
75 // <li> Use the getSlice and putSlice member functions
76 // <li> Use the parenthesis operator or getAt and putAt functions
77 // </ol>
78 // Class PagedArray contains some more info and examples.
79 // </synopsis>
80
81 // <example>
82 // Create a HDF5Lattice of Floats of shape [1024,1024,4,256] in a file
83 // called "myData_tmp.array" and initialize it to zero.
84 // <srcblock>
85 // const IPosition arrayShape(4,1024,1024,4,256);
86 // const String filename("myData_tmp.array");
87 // HDF5Lattice<Float> diskArray(arrayShape, filename);
88 // cout << "Created a HDF5Lattice of shape " << diskArray.shape()
89 // << " (" << diskArray.shape().product()/1024/1024*sizeof(Float)
90 // << " MBytes)" << endl
91 // << "in the table called " << diskArray.tableName() << endl;
92 // diskArray.set(0.0f);
93 // // Using the set function is an efficient way to initialize the HDF5Lattice
94 // // as it uses a LatticeIterator internally. Note that the set function is
95 // // defined in the Lattice class that HDF5Lattice is derived from.
96 // </srcblock>
97 // </example>
98
99 // <motivation>
100 // There was a need to be able to use HDF5 files to hold image data.
101 // </motivation>
102
103 // <templating arg=T>
104 // <li> HDF5DataSet supports only a limited amount of types.
105 // This restricts the template argument to
106 // the types Bool, Int Float, Double, Complex, and DComplex.
107 // </templating>
108
109 template<typename T> class HDF5Lattice : public Lattice<T>
110 {
111 //# Make members of parent class known.
112 public:
113 using Lattice<T>::ndim;
114
115 public:
116 // The default constructor creates an HDF5Lattice that is useless for just
117 // about everything, except that it can be assigned to with the assignment
118 // operator.
120
121 // Construct a new HDF5Lattice with the specified shape.
122 // A new HDF5 file with the specified filename is constructed to hold
123 // the array. The file will remain on disk after the HDF5Lattice goes
124 // out of scope or is deleted.
125 // Optionally the name of an HDF5 group can be given to create the array in.
126 // The group is created if not existing yet.
127 HDF5Lattice (const TiledShape& shape, const String& filename,
128 const String& arrayName = "array",
129 const String& groupName = String());
130
131 // Construct a temporary HDF5Lattice with the specified shape.
132 // A scratch file is created in the current working directory to hold
133 // the array. This file will be deleted automatically when the HDF5Lattice
134 // goes out of scope or is deleted.
135 explicit HDF5Lattice (const TiledShape& shape);
136
137 // Construct a new HDF5Lattice, with the specified shape, in the given
138 // HDF5 file. The array gets the given name.
139 // Optionally the name of an HDF5 group can be given to create the array in.
140 // The group is created if not existing yet.
142 const String& arrayName, const String& groupName = String());
143
144 // Reconstruct from a pre-existing HDF5Lattice in the HDF5 file and group
145 // with the given names.
146 explicit HDF5Lattice (const String& fileName,
147 const String& arrayName = "array",
148 const String& groupName = String());
149
150 // Reconstruct from a pre-existing HDF5Lattice in the HDF5 file and group
151 // with the given name.
153 const String& arrayName,
154 const String& groupName = String());
155
156 // The copy constructor which uses reference semantics. Copying by value
157 // doesn't make sense, because it would require the creation of a
158 // temporary (but possibly huge) file on disk.
160
161 // The destructor flushes the HDF5Lattice's contents to disk.
163
164 // The assignment operator with reference semantics. As with the copy
165 // constructor assigning by value does not make sense.
167
168 // Make a copy of the object (reference semantics).
169 virtual Lattice<T>* clone() const;
170
171 // A HDF5Lattice is always persistent.
172 virtual Bool isPersistent() const;
173
174 // A HDF5Lattice is always paged to disk.
175 virtual Bool isPaged() const;
176
177 // Is the HDF5Lattice writable?
178 virtual Bool isWritable() const;
179
180 // Returns the shape of the HDF5Lattice.
181 virtual IPosition shape() const;
182
183 // Return the current HDF5 file name.
184 // By default this includes the full path.
185 // The path preceeding the file name can be stripped off on request.
186 virtual String name (Bool stripPath=False) const;
187
188 // Return the current HDF5File object.
190 { return itsFile; }
191
192 // Return the current HDF5Group object.
194 { return itsGroup; }
195
196 // Returns the current HDF5DataSet object
198 { return itsDataSet; }
199
200 // Returns the name of this HDF5Lattice.
201 const String& arrayName() const
202 { return itsDataSet->getName(); }
203
204 // Returns the current tile shape for this HDF5Lattice.
206
207 // Set the actual cache size for this Array to be big enough for the
208 // indicated number of tiles. This cache is not shared with other
209 // HDF5Lattices,
210 // Tiles are cached using an LRU algorithm.
211 virtual void setCacheSizeInTiles (uInt howManyTiles);
212
213 // Set the cache size as to "fit" the indicated access pattern.
214 virtual void setCacheSizeFromPath (const IPosition& sliceShape,
215 const IPosition& windowStart,
216 const IPosition& windowLength,
217 const IPosition& axisPath);
218
219 // Return the value of the single element located at the argument
220 // IPosition.
221 // Note that <src>Lattice::operator()</src> can also be used.
222 virtual T getAt (const IPosition& where) const;
223
224 // Put the value of a single element.
225 virtual void putAt (const T& value, const IPosition& where);
226
227 // A function which checks for internal consistency. Returns False if
228 // something nasty has happened to the HDF5Lattice. In that case
229 // it also throws an exception.
230 virtual Bool ok() const;
231
232 // This function is used by the LatticeIterator class to generate an
233 // iterator of the correct type for a specified Lattice. Not recommended
234 // for general use.
236 Bool useRef) const;
237
238 // Do the actual getting of an array of values.
239 virtual Bool doGetSlice (Array<T>& buffer, const Slicer& section);
240
241 // Do the actual getting of an array of values.
242 virtual void doPutSlice (const Array<T>& sourceBuffer,
243 const IPosition& where,
244 const IPosition& stride);
245
246 // Returns the maximum recommended number of pixels for a cursor. This is
247 // the number of pixels in a tile.
248 virtual uInt advisedMaxPixels() const;
249
250 // Get the best cursor shape.
251 virtual IPosition doNiceCursorShape (uInt maxPixels) const;
252
253 // Flush the data (but do not unlock).
254 virtual void flush();
255
256 private:
257 // Make the Array in the HDF5 file and group.
259 const String& groupName);
260 // Open the Array in the HDF5 file and group.
261 void openArray (const String& arrayName, const String& groupName);
262 // Check if the file is writable.
263 void checkWritable() const;
264
265
270 };
271
272
273} //# NAMESPACE CASACORE - END
274
275#ifndef CASACORE_NO_AUTO_TEMPLATES
276#include <casacore/lattices/Lattices/HDF5Lattice.tcc>
277#endif //# CASACORE_NO_AUTO_TEMPLATES
278
279#endif
Referenced counted pointer for constant data.
Definition CountedPtr.h:81
~HDF5Lattice()
The destructor flushes the HDF5Lattice's contents to disk.
IPosition tileShape() const
Returns the current tile shape for this HDF5Lattice.
HDF5Lattice(const TiledShape &shape, const CountedPtr< HDF5File > &file, const String &arrayName, const String &groupName=String())
Construct a new HDF5Lattice, with the specified shape, in the given HDF5 file.
virtual IPosition shape() const
Returns the shape of the HDF5Lattice.
virtual void setCacheSizeFromPath(const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath)
Set the cache size as to "fit" the indicated access pattern.
virtual void putAt(const T &value, const IPosition &where)
Put the value of a single element.
virtual Bool ok() const
A function which checks for internal consistency.
HDF5Lattice(const CountedPtr< HDF5File > &file, const String &arrayName, const String &groupName=String())
Reconstruct from a pre-existing HDF5Lattice in the HDF5 file and group with the given name.
CountedPtr< HDF5Group > itsGroup
HDF5Lattice()
The default constructor creates an HDF5Lattice that is useless for just about everything,...
virtual LatticeIterInterface< T > * makeIter(const LatticeNavigator &navigator, Bool useRef) const
This function is used by the LatticeIterator class to generate an iterator of the correct type for a ...
HDF5Lattice(const String &fileName, const String &arrayName="array", const String &groupName=String())
Reconstruct from a pre-existing HDF5Lattice in the HDF5 file and group with the given names.
virtual void flush()
Flush the data (but do not unlock).
virtual T getAt(const IPosition &where) const
Return the value of the single element located at the argument IPosition.
virtual Bool doGetSlice(Array< T > &buffer, const Slicer &section)
Do the actual getting of an array of values.
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Do the actual getting of an array of values.
HDF5Lattice< T > & operator=(const HDF5Lattice< T > &other)
The assignment operator with reference semantics.
virtual Bool isPersistent() const
A HDF5Lattice is always persistent.
const CountedPtr< HDF5File > & file() const
Return the current HDF5File object.
void checkWritable() const
Check if the file is writable.
const CountedPtr< HDF5Group > & group() const
Return the current HDF5Group object.
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Get the best cursor shape.
CountedPtr< HDF5File > itsFile
HDF5Lattice(const HDF5Lattice< T > &other)
The copy constructor which uses reference semantics.
CountedPtr< HDF5DataSet > itsDataSet
const CountedPtr< HDF5DataSet > & array() const
Returns the current HDF5DataSet object.
HDF5Lattice(const TiledShape &shape, const String &filename, const String &arrayName="array", const String &groupName=String())
Construct a new HDF5Lattice with the specified shape.
void makeArray(const TiledShape &shape, const String &arrayName, const String &groupName)
Make the Array in the HDF5 file and group.
virtual String name(Bool stripPath=False) const
Return the current HDF5 file name.
const String & arrayName() const
Returns the name of this HDF5Lattice.
void openArray(const String &arrayName, const String &groupName)
Open the Array in the HDF5 file and group.
HDF5Lattice(const TiledShape &shape)
Construct a temporary HDF5Lattice with the specified shape.
virtual Bool isPaged() const
A HDF5Lattice is always paged to disk.
virtual Bool isWritable() const
Is the HDF5Lattice writable?
virtual uInt advisedMaxPixels() const
Returns the maximum recommended number of pixels for a cursor.
virtual void setCacheSizeInTiles(uInt howManyTiles)
Set the actual cache size for this Array to be big enough for the indicated number of tiles.
virtual Lattice< T > * clone() const
Make a copy of the object (reference semantics).
virtual uInt ndim() const
Return the number of axes in this Lattice.
String: the storage and methods of handling collections of characters.
Definition String.h:225
this file contains all the compiler specific defines
Definition mainpage.dox:28
const Bool False
Definition aipstype.h:44
unsigned int uInt
Definition aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.