casacore
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 
40 namespace 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.
119  HDF5Lattice();
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.
141  HDF5Lattice (const TiledShape& shape, const CountedPtr<HDF5File>& file,
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.
152  explicit HDF5Lattice (const CountedPtr<HDF5File>& file,
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.
159  HDF5Lattice (const HDF5Lattice<T>& other);
160 
161  // The destructor flushes the HDF5Lattice's contents to disk.
162  ~HDF5Lattice();
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.
189  const CountedPtr<HDF5File>& file() const
190  { return itsFile; }
191 
192  // Return the current HDF5Group object.
194  { return itsGroup; }
195 
196  // Returns the name of this HDF5Lattice.
197  const String& arrayName() const
198  { return itsDataSet->getName(); }
199 
200  // Returns the current tile shape for this HDF5Lattice.
201  IPosition tileShape() const;
202 
203  // Set the actual cache size for this Array to be big enough for the
204  // indicated number of tiles. This cache is not shared with other
205  // HDF5Lattices,
206  // Tiles are cached using an LRU algorithm.
207  virtual void setCacheSizeInTiles (uInt howManyTiles);
208 
209  // Set the cache size as to "fit" the indicated access pattern.
210  virtual void setCacheSizeFromPath (const IPosition& sliceShape,
211  const IPosition& windowStart,
212  const IPosition& windowLength,
213  const IPosition& axisPath);
214 
215  // Return the value of the single element located at the argument
216  // IPosition.
217  // Note that <src>Lattice::operator()</src> can also be used.
218  virtual T getAt (const IPosition& where) const;
219 
220  // Put the value of a single element.
221  virtual void putAt (const T& value, const IPosition& where);
222 
223  // A function which checks for internal consistency. Returns False if
224  // something nasty has happened to the HDF5Lattice. In that case
225  // it also throws an exception.
226  virtual Bool ok() const;
227 
228  // This function is used by the LatticeIterator class to generate an
229  // iterator of the correct type for a specified Lattice. Not recommended
230  // for general use.
231  virtual LatticeIterInterface<T>* makeIter (const LatticeNavigator& navigator,
232  Bool useRef) const;
233 
234  // Do the actual getting of an array of values.
235  virtual Bool doGetSlice (Array<T>& buffer, const Slicer& section);
236 
237  // Do the actual getting of an array of values.
238  virtual void doPutSlice (const Array<T>& sourceBuffer,
239  const IPosition& where,
240  const IPosition& stride);
241 
242  // Returns the maximum recommended number of pixels for a cursor. This is
243  // the number of pixels in a tile.
244  virtual uInt advisedMaxPixels() const;
245 
246  // Get the best cursor shape.
247  virtual IPosition doNiceCursorShape (uInt maxPixels) const;
248 
249  // Flush the data (but do not unlock).
250  virtual void flush();
251 
252  private:
253  // Make the Array in the HDF5 file and group.
254  void makeArray (const TiledShape& shape, const String& arrayName,
255  const String& groupName);
256  // Open the Array in the HDF5 file and group.
257  void openArray (const String& arrayName, const String& groupName);
258  // Check if the file is writable.
259  void checkWritable() const;
260 
261 
265  };
266 
267 
268 } //# NAMESPACE CASACORE - END
269 
270 #ifndef CASACORE_NO_AUTO_TEMPLATES
271 #include <casacore/lattices/Lattices/HDF5Lattice.tcc>
272 #endif //# CASACORE_NO_AUTO_TEMPLATES
273 
274 #endif
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
HDF5Lattice()
The default constructor creates an HDF5Lattice that is useless for just about everything, except that it can be assigned to with the assignment operator.
CountedPtr< HDF5DataSet > itsDataSet
Definition: HDF5Lattice.h:264
virtual T getAt(const IPosition &where) const
Return the value of the single element located at the argument IPosition.
virtual void flush()
Flush the data (but do not unlock).
const CountedPtr< HDF5Group > & group() const
Return the current HDF5Group object.
Definition: HDF5Lattice.h:193
IPosition tileShape() const
Returns the current tile shape for this HDF5Lattice.
virtual void setCacheSizeInTiles(uInt howManyTiles)
Set the actual cache size for this Array to be big enough for the indicated number of tiles...
CountedPtr< HDF5File > itsFile
Definition: HDF5Lattice.h:262
void makeArray(const TiledShape &shape, const String &arrayName, const String &groupName)
Make the Array in the HDF5 file and group.
void openArray(const String &arrayName, const String &groupName)
Open the Array in the HDF5 file and group.
A base class for Lattice iterators.
Definition: ImageExpr.h:47
Define the shape and tile shape.
Definition: TiledShape.h:99
virtual uInt advisedMaxPixels() const
Returns the maximum recommended number of pixels for a cursor.
~HDF5Lattice()
The destructor flushes the HDF5Lattice&#39;s contents to disk.
A templated, abstract base class for array-like objects.
Definition: Functional.h:37
Referenced counted pointer for constant data.
Definition: CountedPtr.h:80
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 String name(Bool stripPath=False) const
Return the current HDF5 file name.
CountedPtr< HDF5Group > itsGroup
Definition: HDF5Lattice.h:263
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Get the best cursor shape.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual Bool isWritable() const
Is the HDF5Lattice writable?
const Bool False
Definition: aipstype.h:44
template <class T, class U> class vector;
Definition: Array.h:169
virtual Lattice< T > * clone() const
Make a copy of the object (reference semantics).
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:289
virtual Bool isPersistent() const
A HDF5Lattice is always persistent.
virtual Bool isPaged() const
A HDF5Lattice is always paged to disk.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
virtual IPosition shape() const
Returns the shape of the HDF5Lattice.
virtual Bool doGetSlice(Array< T > &buffer, const Slicer &section)
Do the actual getting of an array of values.
HDF5Lattice< T > & operator=(const HDF5Lattice< T > &other)
The assignment operator with reference semantics.
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 ...
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Do the actual getting of an array of values.
virtual void putAt(const T &value, const IPosition &where)
Put the value of a single element.
A Lattice that is read from or written to an HDF5 dataset.
Definition: HDF5Lattice.h:109
void checkWritable() const
Check if the file is writable.
const String & arrayName() const
Returns the name of this HDF5Lattice.
Definition: HDF5Lattice.h:197
this file contains all the compiler specific defines
Definition: mainpage.dox:28
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
unsigned int uInt
Definition: aipstype.h:51
Abstract base class to steer lattice iterators.
virtual Bool ok() const
A function which checks for internal consistency.
const CountedPtr< HDF5File > & file() const
Return the current HDF5File object.
Definition: HDF5Lattice.h:189