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