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 HDF5Array, but can be used in itself
62  // as well.
63  // Only a limited number of data types are supported.
64  // They are: boolean (stored as chars), 4-byte integer, and single and
65  // double precision real and complex.
66  // <br>
67  // The data set has a fixed shape, thus cannot be extended nor resized.
68  // It can be stored in a tiled (chunked) way by specifying the tile shape
69  // when creating it.
70  // <br>
71  // It is possible to read or write a section of the data set by using an
72  // appropriate Slicer object. Note that the Slicer object must be fully
73  // filled; it does not infer missing info from the array shape.
74  // <p>
75  // Casacore arrays are in Fortran order, while HDF5 uses C order.
76  // Therefore array axes are reversed, thus axes in shapes, slicers, etc.
77  // </synopsis>
78 
79  // <motivation>
80  // It was overkill to use the HDF5 C++ interface. Instead little wrappers
81  // have been written. HDF5DataSet can be embedded in a shared pointer making
82  // it possible to share an HDF5 data set amongst various HDF5Array objects
83  // and close (i.e. destruct) the HDF5 data set object when needed.
84  // </motivation>
85 
86  class HDF5DataSet : public HDF5Object
87  {
88  public:
89  // Create an HDF5 data set in the given hid (file or group).
90  // It gets the given name, shape (also tile shape), and data type.
91  // <group>
92  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
93  const IPosition& tileShape, const Bool*);
94  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
95  const IPosition& tileShape, const uChar*);
96  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
97  const IPosition& tileShape, const Int*);
98  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
99  const IPosition& tileShape, const Int64*);
100  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
101  const IPosition& tileShape, const Float*);
102  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
103  const IPosition& tileShape, const Double*);
104  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
105  const IPosition& tileShape, const Complex*);
106  HDF5DataSet (const HDF5Object&, const String&, const IPosition& shape,
107  const IPosition& tileShape, const DComplex*);
108  // </group>
109 
110  // Open an existing HDF5 data set in the given hid (file or group).
111  // It checks if the internal type matches the given type.
112  // <group>
113  HDF5DataSet (const HDF5Object&, const String&, const Bool*);
114  HDF5DataSet (const HDF5Object&, const String&, const uChar*);
115  HDF5DataSet (const HDF5Object&, const String&, const Int*);
116  HDF5DataSet (const HDF5Object&, const String&, const Int64*);
117  HDF5DataSet (const HDF5Object&, const String&, const Float*);
118  HDF5DataSet (const HDF5Object&, const String&, const Double*);
119  HDF5DataSet (const HDF5Object&, const String&, const Complex*);
120  HDF5DataSet (const HDF5Object&, const String&, const DComplex*);
121  // </group>
122 
123  // The destructor closes the HDF5 dataset object.
124  ~HDF5DataSet();
125 
126  // Close the hid if valid.
127  virtual void close();
128 
129  // Set the cache size (in chunks) for the data set.
130  // It needs to close and reopen the DataSet to take effect.
131  void setCacheSize (uInt nchunks);
132 
133  // Get the data type for the data set with the given name.
134  static DataType getDataType (hid_t, const String& name);
135 
136  // Get the shape.
137  const IPosition& shape() const
138  { return itsShape; }
139 
140  // Get the tile (chunk) shape.
141  const IPosition& tileShape() const
142  { return itsTileShape; }
143 
144  // Get a section of data into the array.
145  // The array is resized if its shape does not match the slicer's shape.
146  // This is only possible if the array is empty or if resize=True.
147  // It is not checked if the data type of array and HDF5DataSet match.
148  void get (const Slicer&, ArrayBase& buf, Bool resize=False);
149 
150  // Get a section of data.
151  // The buffer must be large enough to hold the section.
152  void get (const Slicer&, void* buf);
153 
154  // Put a section of data.
155  // The shape of the array and slicer must match.
156  // It is not checked if the data type of array and HDF5DataSet match.
157  void put (const Slicer&, const ArrayBase& buf);
158 
159  // Put a section of data.
160  // The buffer must be large enough to hold the section.
161  void put (const Slicer&, const void* buf);
162 
163  // Extend the dataset if an axis in the new shape is larger.
164  void extend (const IPosition& shape);
165 
166  // Helper functions to convert shapes.
167  // It reverses the axes, because HDF5 uses C-order.
168  // <group>
169  static Block<hsize_t> fromShape (const IPosition& shape);
170  static IPosition toShape (const Block<hsize_t>& b);
171  // </group>
172 
173  private:
174  // Copy constructor cannot be used.
175  HDF5DataSet (const HDF5DataSet& that);
176  // Assignment cannot be used.
177  HDF5DataSet& operator= (const HDF5DataSet& that);
178 
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  HDF5HidDataSpace itsDSid; //# data space id
190  HDF5HidProperty itsPLid; //# create property list id
191  HDF5HidProperty itsDaplid; //# access property list id
196  };
197 
198 }
199 
200 #endif
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
void setCacheSize(uInt nchunks)
Set the cache size (in chunks) for the data set.
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size)
Definition: aipsxtype.h:38
int Int
Definition: aipstype.h:50
Non-templated base class for templated Array class.
Definition: ArrayBase.h:74
A class representing an HDF5 dataspace hid.
Definition: HDF5HidMeta.h:151
A class representing an HDF5 data type.
Definition: HDF5DataType.h:65
void open(const HDF5Object &, const String &)
Open the data set and check if the external data type matches.
unsigned char uChar
Definition: aipstype.h:47
void closeDataSet()
Close the dataset (but not other hids).
const IPosition & tileShape() const
Get the tile (chunk) shape.
Definition: HDF5DataSet.h:141
const HDF5Object * itsParent
Definition: HDF5DataSet.h:195
virtual void close()
Close the hid if valid.
void extend(const IPosition &shape)
Extend the dataset if an axis in the new shape is larger.
HDF5DataSet & operator=(const HDF5DataSet &that)
Assignment cannot be used.
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).
HDF5HidDataSpace itsDSid
Definition: HDF5DataSet.h:189
HDF5HidProperty itsPLid
Definition: HDF5DataSet.h:190
double Double
Definition: aipstype.h:55
static Block< hsize_t > fromShape(const IPosition &shape)
Helper functions to convert shapes.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
~HDF5DataSet()
The destructor closes the HDF5 dataset object.
float Float
Definition: aipstype.h:54
const Bool False
Definition: aipstype.h:44
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:289
simple 1-D array
Definition: ArrayIO.h:47
An abstract base class representing an HDF5 object.
Definition: HDF5Object.h:70
HDF5HidProperty itsDaplid
Definition: HDF5DataSet.h:191
static DataType getDataType(hid_t, const String &name)
Get the data type for the data set with the given name.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
A class representing an HDF5 data set.
Definition: HDF5DataSet.h:86
static IPosition toShape(const Block< hsize_t > &b)
HDF5DataType itsDataType
Definition: HDF5DataSet.h:194
A class representing an HDF5 property hid.
Definition: HDF5HidMeta.h:53
void create(const HDF5Object &, const String &, const IPosition &shape, const IPosition &tileShape)
Create the data set.
void put(const Slicer &, const ArrayBase &buf)
Put a section of data.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const IPosition & shape() const
Get the shape.
Definition: HDF5DataSet.h:137
unsigned int uInt
Definition: aipstype.h:51