casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
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&lt;T&gt; objects.
Definition: IPosition.h:118
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
const CountedPtr< HDF5File > & file() const
Return the current HDF5File object.
Definition: HDF5Lattice.h:189
virtual void flush()
Flush the data (but do not unlock).
const CountedPtr< HDF5DataSet > & array() const
Returns the current HDF5DataSet object.
Definition: HDF5Lattice.h:197
virtual String name(Bool stripPath=False) const
Return the current HDF5 file name.
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.
void checkWritable() const
Check if the file is writable.
A base class for Lattice iterators.
Definition: ImageExpr.h:47
Define the shape and tile shape.
Definition: TiledShape.h:96
~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 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 ...
const String & arrayName() const
Returns the name of this HDF5Lattice.
Definition: HDF5Lattice.h:201
virtual void setCacheSizeFromPath(const IPosition &sliceShape, const IPosition &windowStart, const IPosition &windowLength, const IPosition &axisPath)
Set the cache size as to &quot;fit&quot; the indicated access pattern.
CountedPtr< HDF5Group > itsGroup
Definition: HDF5Lattice.h:267
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Get the best cursor shape.
virtual Bool isPersistent() const
A HDF5Lattice is always persistent.
const Bool False
Definition: aipstype.h:44
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:288
virtual Bool isPaged() const
A HDF5Lattice is always paged to disk.
virtual uInt advisedMaxPixels() const
Returns the maximum recommended number of pixels for a cursor.
IPosition tileShape() const
Returns the current tile shape for this HDF5Lattice.
virtual Bool isWritable() const
Is the HDF5Lattice writable?
virtual Bool ok() const
A function which checks for internal consistency.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
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 Lattice< T > * clone() const
Make a copy of the object (reference semantics).
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Do the actual getting of an array of values.
virtual T getAt(const IPosition &where) const
Return the value of the single element located at the argument IPosition.
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
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
const CountedPtr< HDF5Group > & group() const
Return the current HDF5Group object.
Definition: HDF5Lattice.h:193
unsigned int uInt
Definition: aipstype.h:51
Abstract base class to steer lattice iterators.
virtual IPosition shape() const
Returns the shape of the HDF5Lattice.