casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Private Member Functions | Private Attributes | List of all members
casacore::HDF5Lattice< T > Class Template Reference

A Lattice that is read from or written to an HDF5 dataset. More...

#include <HDF5Lattice.h>

Inheritance diagram for casacore::HDF5Lattice< T >:
casacore::Lattice< T > casacore::LatticeBase

Public Member Functions

 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. More...
 
 HDF5Lattice (const TiledShape &shape, const String &filename, const String &arrayName="array", const String &groupName=String())
 Construct a new HDF5Lattice with the specified shape. More...
 
 HDF5Lattice (const TiledShape &shape)
 Construct a temporary HDF5Lattice with the specified shape. More...
 
 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. More...
 
 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. More...
 
 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. More...
 
 HDF5Lattice (const HDF5Lattice< T > &other)
 The copy constructor which uses reference semantics. More...
 
 ~HDF5Lattice ()
 The destructor flushes the HDF5Lattice's contents to disk. More...
 
HDF5Lattice< T > & operator= (const HDF5Lattice< T > &other)
 The assignment operator with reference semantics. More...
 
virtual Lattice< T > * clone () const
 Make a copy of the object (reference semantics). More...
 
virtual Bool isPersistent () const
 A HDF5Lattice is always persistent. More...
 
virtual Bool isPaged () const
 A HDF5Lattice is always paged to disk. More...
 
virtual Bool isWritable () const
 Is the HDF5Lattice writable? More...
 
virtual IPosition shape () const
 Returns the shape of the HDF5Lattice. More...
 
virtual String name (Bool stripPath=False) const
 Return the current HDF5 file name. More...
 
const CountedPtr< HDF5File > & file () const
 Return the current HDF5File object. More...
 
const CountedPtr< HDF5Group > & group () const
 Return the current HDF5Group object. More...
 
const CountedPtr< HDF5DataSet > & array () const
 Returns the current HDF5DataSet object. More...
 
const StringarrayName () const
 Returns the name of this HDF5Lattice. More...
 
IPosition tileShape () const
 Returns the current tile shape for this HDF5Lattice. More...
 
virtual void setCacheSizeInTiles (uInt howManyTiles)
 Set the actual cache size for this Array to be big enough for the indicated number of tiles. More...
 
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. More...
 
virtual T getAt (const IPosition &where) const
 Return the value of the single element located at the argument IPosition. More...
 
virtual void putAt (const T &value, const IPosition &where)
 Put the value of a single element. More...
 
virtual Bool ok () const
 A function which checks for internal consistency. More...
 
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 specified Lattice. More...
 
virtual Bool doGetSlice (Array< T > &buffer, const Slicer &section)
 Do the actual getting of an array of values. More...
 
virtual void doPutSlice (const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
 Do the actual getting of an array of values. More...
 
virtual uInt advisedMaxPixels () const
 Returns the maximum recommended number of pixels for a cursor. More...
 
virtual IPosition doNiceCursorShape (uInt maxPixels) const
 Get the best cursor shape. More...
 
virtual void flush ()
 Flush the data (but do not unlock). More...
 
- Public Member Functions inherited from casacore::Lattice< T >
virtual ~Lattice ()
 a virtual destructor is needed so that it will use the actual destructor in the derived class More...
 
virtual DataType dataType () const
 Get the data type of the lattice. More...
 
operator() (const IPosition &where) const
 Return the value of the single element located at the argument IPosition. More...
 
Bool get (COWPtr< Array< T > > &buffer, Bool removeDegenerateAxes=False) const
 Functions which extract an Array of values from a Lattice. More...
 
Bool getSlice (COWPtr< Array< T > > &buffer, const Slicer &section, Bool removeDegenerateAxes=False) const
 
Bool getSlice (COWPtr< Array< T > > &buffer, const IPosition &start, const IPosition &shape, Bool removeDegenerateAxes=False) const
 
Bool getSlice (COWPtr< Array< T > > &buffer, const IPosition &start, const IPosition &shape, const IPosition &stride, Bool removeDegenerateAxes=False) const
 
Bool get (Array< T > &buffer, Bool removeDegenerateAxes=False)
 
Bool getSlice (Array< T > &buffer, const Slicer &section, Bool removeDegenerateAxes=False)
 
Bool getSlice (Array< T > &buffer, const IPosition &start, const IPosition &shape, Bool removeDegenerateAxes=False)
 
Bool getSlice (Array< T > &buffer, const IPosition &start, const IPosition &shape, const IPosition &stride, Bool removeDegenerateAxes=False)
 
Array< T > get (Bool removeDegenerateAxes=False) const
 
Array< T > getSlice (const Slicer &section, Bool removeDegenerateAxes=False) const
 
Array< T > getSlice (const IPosition &start, const IPosition &shape, Bool removeDegenerateAxes=False) const
 
Array< T > getSlice (const IPosition &start, const IPosition &shape, const IPosition &stride, Bool removeDegenerateAxes=False) const
 
void putSlice (const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
 A function which places an Array of values within this instance of the Lattice at the location specified by the IPosition "where", incrementing by "stride". More...
 
void putSlice (const Array< T > &sourceBuffer, const IPosition &where)
 
void put (const Array< T > &sourceBuffer)
 
virtual void set (const T &value)
 Set all elements in the Lattice to the given value. More...
 
virtual void apply (T(*function)(T))
 Replace every element, x, of the Lattice with the result of f(x). More...
 
virtual void apply (T(*function)(const T &))
 
virtual void apply (const Functional< T, T > &function)
 
void operator+= (const Lattice< T > &other)
 Add, subtract, multiple, or divide by another Lattice. More...
 
void operator-= (const Lattice< T > &other)
 
void operator*= (const Lattice< T > &other)
 
void operator/= (const Lattice< T > &other)
 
virtual void copyData (const Lattice< T > &from)
 Copy the data from the given lattice to this one. More...
 
virtual void copyDataTo (Lattice< T > &to) const
 Copy the data from this lattice to the given lattice. More...
 
- Public Member Functions inherited from casacore::LatticeBase
virtual ~LatticeBase ()
 A virtual destructor is needed so that it will use the actual destructor in the derived class. More...
 
virtual String imageType () const
 Get the image type (returns name of derived class). More...
 
virtual Bool canReferenceArray () const
 Can the lattice data be referenced as an array section? That is the case for an ArrayLattice or a Temp/SubLattice using it. More...
 
virtual void save (const String &fileName) const
 Save the image in an AipsIO file with the given name. More...
 
virtual Bool lock (FileLocker::LockType, uInt nattempts)
 It is strongly recommended to use class LatticeLocker to handle lattice locking. More...
 
virtual void unlock ()
 
virtual Bool hasLock (FileLocker::LockType) const
 
virtual void resync ()
 Resynchronize the Lattice object with the lattice file. More...
 
virtual void tempClose ()
 Temporarily close the lattice. More...
 
virtual void reopen ()
 Explicitly reopen the temporarily closed lattice. More...
 
virtual uInt ndim () const
 Return the number of axes in this Lattice. More...
 
virtual size_t nelements () const
 Return the total number of elements in this Lattice. More...
 
size_t size () const
 
Bool conform (const LatticeBase &other) const
 Return a value of "True" if this instance of Lattice and 'other' have the same shape, otherwise returns a value of "False". More...
 
virtual LELCoordinates lelCoordinates () const
 Return the coordinates of the lattice. More...
 
IPosition niceCursorShape (uInt maxPixels) const
 Returns a recommended cursor shape for iterating through all the pixels in the Lattice. More...
 
IPosition niceCursorShape () const
 
virtual uInt maximumCacheSize () const
 Maximum cache size - not necessarily all used. More...
 
virtual void setMaximumCacheSize (uInt howManyPixels)
 Set the maximum (allowed) cache size as indicated. More...
 
virtual void clearCache ()
 Clears and frees up the caches, but the maximum allowed cache size is unchanged from when setCacheSize was called. More...
 
virtual void showCacheStatistics (ostream &os) const
 Report on cache success. More...
 

Private Member Functions

void makeArray (const TiledShape &shape, const String &arrayName, const String &groupName)
 Make the Array in the HDF5 file and group. More...
 
void openArray (const String &arrayName, const String &groupName)
 Open the Array in the HDF5 file and group. More...
 
void checkWritable () const
 Check if the file is writable. More...
 

Private Attributes

CountedPtr< HDF5FileitsFile
 
CountedPtr< HDF5GroupitsGroup
 
CountedPtr< HDF5DataSetitsDataSet
 
IPosition itsTileShape
 

Additional Inherited Members

- Protected Member Functions inherited from casacore::Lattice< T >
 Lattice ()
 Define default constructor to satisfy compiler. More...
 
virtual void handleMath (const Lattice< T > &from, int oper)
 Handle the Math operators (+=, -=, *=, /=). More...
 
virtual void handleMathTo (Lattice< T > &to, int oper) const
 
 Lattice (const Lattice< T > &)
 Copy constructor and assignment can only be used by derived classes. More...
 
Lattice< T > & operator= (const Lattice< T > &)
 
template<>
void handleMathTo (Lattice< Bool > &, int) const
 
- Protected Member Functions inherited from casacore::LatticeBase
 LatticeBase ()
 Define default constructor to be used by derived classes. More...
 
 LatticeBase (const LatticeBase &)
 Copy constructor and assignment can only be used by derived classes. More...
 
LatticeBaseoperator= (const LatticeBase &)
 
void throwBoolMath () const
 Throw an exception for arithmetic on a Bool Lattice. More...
 

Detailed Description

template<typename T>
class casacore::HDF5Lattice< T >

A Lattice that is read from or written to an HDF5 dataset.

Intended use:

Public interface

Review Status

Test programs:
tHDF5Lattice

Prerequisite

Synopsis

Astronomical data arrays (like images) have to be persistent. A Lattice is a templated abstract base class to hold any Casacore array. The PagedArray class is a Lattice specialization which stores the data in a Casacore table.
HDF5Lattice ia another Lattice specialization making it possible to store an array as a dataset in a group in an HDF5 file.

When you construct an HDF5Lattice you do not read any data into memory. Instead an HDF5 disk file is created, in a place you specify, to hold the data. This means you need to have enough disk space to hold the array. Constructing a new HDF5Lattice is equivalent to creating a data set in an HDF5 file.

To access the data in a HDF5Lattice you can (in order of preference):

  1. Use a LatticeIterator
  2. Use the getSlice and putSlice member functions
  3. Use the parenthesis operator or getAt and putAt functions

Class PagedArray contains some more info and examples.

Example

Create a HDF5Lattice of Floats of shape [1024,1024,4,256] in a file called "myData_tmp.array" and initialize it to zero.

const IPosition arrayShape(4,1024,1024,4,256);
const String filename("myData_tmp.array");
HDF5Lattice<Float> diskArray(arrayShape, filename);
cout << "Created a HDF5Lattice of shape " << diskArray.shape()
<< " (" << diskArray.shape().product()/1024/1024*sizeof(Float)
<< " MBytes)" << endl
<< "in the table called " << diskArray.tableName() << endl;
diskArray.set(0.0f);
// Using the set function is an efficient way to initialize the HDF5Lattice
// as it uses a LatticeIterator internally. Note that the set function is
// defined in the Lattice class that HDF5Lattice is derived from.

Motivation

There was a need to be able to use HDF5 files to hold image data.

Template Type Argument Requirements (T)

Definition at line 109 of file HDF5Lattice.h.

Constructor & Destructor Documentation

template<typename T>
casacore::HDF5Lattice< T >::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.

template<typename T>
casacore::HDF5Lattice< T >::HDF5Lattice ( const TiledShape shape,
const String filename,
const String arrayName = "array",
const String groupName = String() 
)

Construct a new HDF5Lattice with the specified shape.

A new HDF5 file with the specified filename is constructed to hold the array. The file will remain on disk after the HDF5Lattice goes out of scope or is deleted. Optionally the name of an HDF5 group can be given to create the array in. The group is created if not existing yet.

template<typename T>
casacore::HDF5Lattice< T >::HDF5Lattice ( const TiledShape shape)
explicit

Construct a temporary HDF5Lattice with the specified shape.

A scratch file is created in the current working directory to hold the array. This file will be deleted automatically when the HDF5Lattice goes out of scope or is deleted.

template<typename T>
casacore::HDF5Lattice< T >::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.

The array gets the given name. Optionally the name of an HDF5 group can be given to create the array in. The group is created if not existing yet.

template<typename T>
casacore::HDF5Lattice< T >::HDF5Lattice ( const String fileName,
const String arrayName = "array",
const String groupName = String() 
)
explicit

Reconstruct from a pre-existing HDF5Lattice in the HDF5 file and group with the given names.

template<typename T>
casacore::HDF5Lattice< T >::HDF5Lattice ( const CountedPtr< HDF5File > &  file,
const String arrayName,
const String groupName = String() 
)
explicit

Reconstruct from a pre-existing HDF5Lattice in the HDF5 file and group with the given name.

template<typename T>
casacore::HDF5Lattice< T >::HDF5Lattice ( const HDF5Lattice< T > &  other)

The copy constructor which uses reference semantics.

Copying by value doesn't make sense, because it would require the creation of a temporary (but possibly huge) file on disk.

template<typename T>
casacore::HDF5Lattice< T >::~HDF5Lattice ( )

The destructor flushes the HDF5Lattice's contents to disk.

Member Function Documentation

template<typename T>
virtual uInt casacore::HDF5Lattice< T >::advisedMaxPixels ( ) const
virtual

Returns the maximum recommended number of pixels for a cursor.

This is the number of pixels in a tile.

Reimplemented from casacore::Lattice< T >.

template<typename T>
const CountedPtr<HDF5DataSet>& casacore::HDF5Lattice< T >::array ( ) const
inline

Returns the current HDF5DataSet object.

Definition at line 197 of file HDF5Lattice.h.

template<typename T>
const String& casacore::HDF5Lattice< T >::arrayName ( ) const
inline

Returns the name of this HDF5Lattice.

Definition at line 201 of file HDF5Lattice.h.

template<typename T>
void casacore::HDF5Lattice< T >::checkWritable ( ) const
private

Check if the file is writable.

template<typename T>
virtual Lattice<T>* casacore::HDF5Lattice< T >::clone ( ) const
virtual

Make a copy of the object (reference semantics).

Implements casacore::Lattice< T >.

template<typename T>
virtual Bool casacore::HDF5Lattice< T >::doGetSlice ( Array< T > &  buffer,
const Slicer section 
)
virtual

Do the actual getting of an array of values.

Implements casacore::Lattice< T >.

template<typename T>
virtual IPosition casacore::HDF5Lattice< T >::doNiceCursorShape ( uInt  maxPixels) const
virtual

Get the best cursor shape.

Reimplemented from casacore::LatticeBase.

template<typename T>
virtual void casacore::HDF5Lattice< T >::doPutSlice ( const Array< T > &  sourceBuffer,
const IPosition where,
const IPosition stride 
)
virtual

Do the actual getting of an array of values.

Implements casacore::Lattice< T >.

template<typename T>
const CountedPtr<HDF5File>& casacore::HDF5Lattice< T >::file ( ) const
inline

Return the current HDF5File object.

Definition at line 189 of file HDF5Lattice.h.

template<typename T>
virtual void casacore::HDF5Lattice< T >::flush ( )
virtual

Flush the data (but do not unlock).

Reimplemented from casacore::LatticeBase.

template<typename T>
virtual T casacore::HDF5Lattice< T >::getAt ( const IPosition where) const
virtual

Return the value of the single element located at the argument IPosition.

Note that Lattice::operator() can also be used.

Reimplemented from casacore::Lattice< T >.

template<typename T>
const CountedPtr<HDF5Group>& casacore::HDF5Lattice< T >::group ( ) const
inline

Return the current HDF5Group object.

Definition at line 193 of file HDF5Lattice.h.

template<typename T>
virtual Bool casacore::HDF5Lattice< T >::isPaged ( ) const
virtual

A HDF5Lattice is always paged to disk.

Reimplemented from casacore::LatticeBase.

template<typename T>
virtual Bool casacore::HDF5Lattice< T >::isPersistent ( ) const
virtual

A HDF5Lattice is always persistent.

Reimplemented from casacore::LatticeBase.

template<typename T>
virtual Bool casacore::HDF5Lattice< T >::isWritable ( ) const
virtual

Is the HDF5Lattice writable?

Reimplemented from casacore::LatticeBase.

template<typename T>
void casacore::HDF5Lattice< T >::makeArray ( const TiledShape shape,
const String arrayName,
const String groupName 
)
private

Make the Array in the HDF5 file and group.

template<typename T>
virtual LatticeIterInterface<T>* casacore::HDF5Lattice< T >::makeIter ( const LatticeNavigator navigator,
Bool  useRef 
) const
virtual

This function is used by the LatticeIterator class to generate an iterator of the correct type for a specified Lattice.

Not recommended for general use.

Reimplemented from casacore::Lattice< T >.

template<typename T>
virtual String casacore::HDF5Lattice< T >::name ( Bool  stripPath = False) const
virtual

Return the current HDF5 file name.

By default this includes the full path. The path preceeding the file name can be stripped off on request.

Reimplemented from casacore::LatticeBase.

template<typename T>
virtual Bool casacore::HDF5Lattice< T >::ok ( ) const
virtual

A function which checks for internal consistency.

Returns False if something nasty has happened to the HDF5Lattice. In that case it also throws an exception.

Reimplemented from casacore::LatticeBase.

template<typename T>
void casacore::HDF5Lattice< T >::openArray ( const String arrayName,
const String groupName 
)
private

Open the Array in the HDF5 file and group.

template<typename T>
HDF5Lattice<T>& casacore::HDF5Lattice< T >::operator= ( const HDF5Lattice< T > &  other)

The assignment operator with reference semantics.

As with the copy constructor assigning by value does not make sense.

template<typename T>
virtual void casacore::HDF5Lattice< T >::putAt ( const T &  value,
const IPosition where 
)
virtual

Put the value of a single element.

Reimplemented from casacore::Lattice< T >.

template<typename T>
virtual void casacore::HDF5Lattice< T >::setCacheSizeFromPath ( const IPosition sliceShape,
const IPosition windowStart,
const IPosition windowLength,
const IPosition axisPath 
)
virtual

Set the cache size as to "fit" the indicated access pattern.

Reimplemented from casacore::LatticeBase.

template<typename T>
virtual void casacore::HDF5Lattice< T >::setCacheSizeInTiles ( uInt  howManyTiles)
virtual

Set the actual cache size for this Array to be big enough for the indicated number of tiles.

This cache is not shared with other HDF5Lattices, Tiles are cached using an LRU algorithm.

Reimplemented from casacore::LatticeBase.

template<typename T>
virtual IPosition casacore::HDF5Lattice< T >::shape ( ) const
virtual

Returns the shape of the HDF5Lattice.

Implements casacore::LatticeBase.

template<typename T>
IPosition casacore::HDF5Lattice< T >::tileShape ( ) const

Returns the current tile shape for this HDF5Lattice.

Member Data Documentation

template<typename T>
CountedPtr<HDF5DataSet> casacore::HDF5Lattice< T >::itsDataSet
private
template<typename T>
CountedPtr<HDF5File> casacore::HDF5Lattice< T >::itsFile
private

Definition at line 266 of file HDF5Lattice.h.

Referenced by casacore::HDF5Lattice< Bool >::file().

template<typename T>
CountedPtr<HDF5Group> casacore::HDF5Lattice< T >::itsGroup
private

Definition at line 267 of file HDF5Lattice.h.

Referenced by casacore::HDF5Lattice< Bool >::group().

template<typename T>
IPosition casacore::HDF5Lattice< T >::itsTileShape
private

Definition at line 269 of file HDF5Lattice.h.


The documentation for this class was generated from the following file: