casacore
HDF5DataSet.h
Go to the documentation of this file.
1 //# HDF5DataSet.h: An class representing an HDF5 data set
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 CASA_HDF5DATASET_H
29 #define CASA_HDF5DATASET_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/HDF5/HDF5Object.h>
34 #include <casacore/casa/HDF5/HDF5HidMeta.h>
35 #include <casacore/casa/HDF5/HDF5DataType.h>
36 #include <casacore/casa/Arrays/Slicer.h>
37 #include <casacore/casa/BasicSL/String.h>
38 #include <casacore/casa/Utilities/DataType.h>
39 
40 namespace casacore { //# NAMESPACE CASACORE - BEGIN
41 
42  //# Forward Declarations
43  class ArrayBase;
44  template<typename T> class Block;
45 
46  // <summary>
47  // A class representing an HDF5 data set.
48  // </summary>
49 
50  // <use visibility=export>
51 
52  // <reviewed reviewer="" date="" tests="tHDF5DataSet.cc">
53  // </reviewed>
54 
55  // <prerequisite>
56  // <li> <a href="http://hdf.ncsa.uiuc.edu">HDF5 system</a>
57  // </prerequisite>
58 
59  // <synopsis>
60  // This class wraps the HDF5 functions to create and open a data set.
61  // It is meant to be used in class HDF5Lattice, but can be used in itself
62  // as well.
63  // A dataset of any HDF5DataType (including compound types) can be created.
64  // For a limited number of data types special constructors exist which
65  // create the appropriate HDF5DataType themselves.
66  // <br>
67  // A data set can be created extendible by defining the appropriate
68  // axis with length 0, whereafter the extend function can be used to
69  // extend the data set.
70  // The data can be stored in a tiled (chunked) way by specifying the tile
71  // shape when creating it.
72  // <br>
73  // When opening an existing data set, it is checked if the given data type
74  // matches the data set's data type. For a compound data type, it only
75  // checks if its size matches; it does not check if the fields match.
76  // <br>
77  // It is possible to read or write a section of the data set by using an
78  // appropriate Slicer object. Note that the Slicer object must be fully
79  // filled; it does not infer missing info from the array shape.
80  // <p>
81  // Note that Casacore arrays are in Fortran order, while HDF5 uses C order.
82  // Therefore array axes are reversed, thus axes in shapes, slicers, etc.
83  // </synopsis>
84 
85  // <motivation>
86  // It was overkill to use the HDF5 C++ interface. Instead little wrappers
87  // have been written. HDF5DataSet can be embedded in a shared pointer making
88  // it possible to share an HDF5 data set amongst various HDF5Lattice objects
89  // and close (i.e. destruct) the HDF5 data set object when needed.
90  // </motivation>
91 
92  class HDF5DataSet : public HDF5Object
93  {
94  public:
95  // Create an HDF5 data set in the given hid (file or group).
96  // It gets the given name, shape (also tile shape), and data type.
97  // <group>
98  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
99  const IPosition& tileShape, const Bool*);
100  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
101  const IPosition& tileShape, const uChar*);
102  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
103  const IPosition& tileShape, const Short*);
104  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
105  const IPosition& tileShape, const Int*);
106  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
107  const IPosition& tileShape, const Int64*);
108  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
109  const IPosition& tileShape, const Float*);
110  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
111  const IPosition& tileShape, const Double*);
112  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
113  const IPosition& tileShape, const Complex*);
114  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
115  const IPosition& tileShape, const DComplex*);
116  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
117  const IPosition& tileShape, const HDF5DataType&);
118  // </group>
119 
120  // Open an existing HDF5 data set in the given hid (file or group).
121  // It checks if the internal type matches the given type.
122  // <group>
123  HDF5DataSet (const HDF5Object&, const String&, const Bool*);
124  HDF5DataSet (const HDF5Object&, const String&, const uChar*);
125  HDF5DataSet (const HDF5Object&, const String&, const Short*);
126  HDF5DataSet (const HDF5Object&, const String&, const Int*);
127  HDF5DataSet (const HDF5Object&, const String&, const Int64*);
128  HDF5DataSet (const HDF5Object&, const String&, const Float*);
129  HDF5DataSet (const HDF5Object&, const String&, const Double*);
130  HDF5DataSet (const HDF5Object&, const String&, const Complex*);
131  HDF5DataSet (const HDF5Object&, const String&, const DComplex*);
132  HDF5DataSet (const HDF5Object&, const String&, const HDF5DataType&);
133  // </group>
134 
135  // The destructor closes the HDF5 dataset object.
136  virtual ~HDF5DataSet();
137 
138  // Close the hid if valid.
139  virtual void close();
140 
141  // Set the cache size (in chunks) for the data set.
142  // It needs to close and reopen the DataSet to take effect.
143  void setCacheSize (uInt nchunks);
144 
145  // Get the data type for the data set with the given name.
146  static DataType getDataType (hid_t, const String& name);
147 
148  // Get the shape.
149  const IPosition& shape() const
150  { return itsShape; }
151 
152  // Get the tile (chunk) shape.
153  const IPosition& tileShape() const
154  { return itsTileShape; }
155 
156  // Get a section of data into the array.
157  // The array is resized if its shape does not match the slicer's shape.
158  // This is only possible if the array is empty or if resize=True.
159  // It is not checked if the data type of array and HDF5DataSet match.
160  void get (const Slicer&, ArrayBase& buf, Bool resize=False);
161 
162  // Get a section of data.
163  // The buffer must be large enough to hold the section.
164  void get (const Slicer&, void* buf);
165 
166  // Put a section of data.
167  // The shape of the array and slicer must match.
168  // It is not checked if the data type of array and HDF5DataSet match.
169  void put (const Slicer&, const ArrayBase& buf);
170 
171  // Put a section of data.
172  // The buffer must be large enough to hold the section.
173  void put (const Slicer&, const void* buf);
174 
175  // Extend the dataset if an axis in the new shape is larger.
176  void extend (const IPosition& shape);
177 
178  protected:
179  // Create the data set.
180  void create (const HDF5Object&, const String&,
181  const IPosition& shape, const IPosition& tileShape);
182 
183  // Open the data set and check if the external data type matches.
184  void open (const HDF5Object&, const String&);
185 
186  // Close the dataset (but not other hids).
187  void closeDataSet();
188 
189  private:
190  // Copy constructor cannot be used.
191  HDF5DataSet (const HDF5DataSet& that);
192  // Assignment cannot be used.
194 
195  HDF5HidDataSpace itsDSid; //# data space id
196  HDF5HidProperty itsPLid; //# create property list id
197  HDF5HidProperty itsDaplid; //# access property list id
202  };
203 
204 }
205 
206 #endif
Non-templated base class for templated Array class.
Definition: ArrayBase.h:73
HDF5DataSet(const HDF5Object &, const String &, const Int64 *)
HDF5DataSet(const HDF5Object &, const String &, const Double *)
HDF5DataSet(const HDF5Object &, const String &, const IPosition &shape, const IPosition &tileShape, const DComplex *)
void closeDataSet()
Close the dataset (but not other hids).
HDF5DataSet(const HDF5Object &, const String &, const IPosition &shape, const IPosition &tileShape, const HDF5DataType &)
void put(const Slicer &, const void *buf)
Put a section of data.
HDF5DataSet(const HDF5Object &, const String &, const IPosition &shape, const IPosition &tileShape, const Bool *)
Create an HDF5 data set in the given hid (file or group).
void get(const Slicer &, void *buf)
Get a section of data.
HDF5DataSet(const HDF5DataSet &that)
Copy constructor cannot be used.
HDF5DataSet(const HDF5Object &, const String &, const Complex *)
HDF5DataSet(const HDF5Object &, const String &, const IPosition &shape, const IPosition &tileShape, const Float *)
void put(const Slicer &, const ArrayBase &buf)
Put a section of data.
HDF5DataSet(const HDF5Object &, const String &, const Bool *)
Open an existing HDF5 data set in the given hid (file or group).
HDF5DataSet(const HDF5Object &, const String &, const IPosition &shape, const IPosition &tileShape, const Int64 *)
HDF5DataSet(const HDF5Object &, const String &, const IPosition &shape, const IPosition &tileShape, const Short *)
HDF5DataSet(const HDF5Object &, const String &, const Int *)
HDF5HidDataSpace itsDSid
Definition: HDF5DataSet.h:195
HDF5DataSet(const HDF5Object &, const String &, const IPosition &shape, const IPosition &tileShape, const Complex *)
HDF5DataSet(const HDF5Object &, const String &, const IPosition &shape, const IPosition &tileShape, const Double *)
HDF5DataSet(const HDF5Object &, const String &, const uChar *)
HDF5DataSet(const HDF5Object &, const String &, const IPosition &shape, const IPosition &tileShape, const uChar *)
virtual ~HDF5DataSet()
The destructor closes the HDF5 dataset object.
HDF5DataSet & operator=(const HDF5DataSet &that)
Assignment cannot be used.
HDF5HidProperty itsDaplid
Definition: HDF5DataSet.h:197
HDF5DataSet(const HDF5Object &, const String &, const HDF5DataType &)
const IPosition & tileShape() const
Get the tile (chunk) shape.
Definition: HDF5DataSet.h:153
HDF5DataSet(const HDF5Object &, const String &, const Float *)
virtual void close()
Close the hid if valid.
void create(const HDF5Object &, const String &, const IPosition &shape, const IPosition &tileShape)
Create the data set.
void extend(const IPosition &shape)
Extend the dataset if an axis in the new shape is larger.
static DataType getDataType(hid_t, const String &name)
Get the data type for the data set with the given name.
HDF5HidProperty itsPLid
Definition: HDF5DataSet.h:196
HDF5DataSet(const HDF5Object &, const String &, const Short *)
void open(const HDF5Object &, const String &)
Open the data set and check if the external data type matches.
const IPosition & shape() const
Get the shape.
Definition: HDF5DataSet.h:149
HDF5DataSet(const HDF5Object &, const String &, const IPosition &shape, const IPosition &tileShape, const Int *)
void get(const Slicer &, ArrayBase &buf, Bool resize=False)
Get a section of data into the array.
HDF5DataType itsDataType
Definition: HDF5DataSet.h:200
HDF5DataSet(const HDF5Object &, const String &, const DComplex *)
void setCacheSize(uInt nchunks)
Set the cache size (in chunks) for the data set.
const HDF5Object * itsParent
Definition: HDF5DataSet.h:201
A class representing an HDF5 dataspace hid.
Definition: HDF5HidMeta.h:151
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
unsigned char uChar
Definition: aipstype.h:47
const Bool False
Definition: aipstype.h:44
short Short
Definition: aipstype.h:48
unsigned int uInt
Definition: aipstype.h:51
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
float Float
Definition: aipstype.h:54
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
double Double
Definition: aipstype.h:55