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 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.
205  IPosition tileShape() const;
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.
235  virtual LatticeIterInterface<T>* makeIter (const LatticeNavigator& navigator,
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.
258  void makeArray (const TiledShape& shape, const String& arrayName,
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
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:268
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:266
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:267
const CountedPtr< HDF5DataSet > & array() const
Returns the current HDF5DataSet object.
Definition: HDF5Lattice.h:197
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:166
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:201
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