casacore
HDF5Image.h
Go to the documentation of this file.
1//# HDF5Image.h: astronomical image in HDF5 format
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 IMAGES_HDF5IMAGE_H
29#define IMAGES_HDF5IMAGE_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/images/Images/ImageInterface.h>
34#include <casacore/images/Images/ImageAttrHandlerHDF5.h>
35#include <casacore/lattices/Lattices/HDF5Lattice.h>
36
37//# Forward Declarations
38#include <casacore/casa/iosfwd.h>
39
40namespace casacore { //# NAMESPACE CASACORE - BEGIN
41
42 // <summary>
43 // Read, store, and manipulate astronomical images in HDF5 format.
44 // </summary>
45
46 // <use visibility=export>
47
48 // <reviewed reviewer="" date="" tests="tHDF5Image.cc" demos="dHDF5Image.cc">
49 // </reviewed>
50
51 // <prerequisite>
52 // <li> <linkto class=CoordinateSystem>CoordinateSystem</linkto>
53 // <li> <linkto class=ImageInterface>ImageInterface</linkto>
54 // <li> <linkto class=Lattice>Lattice</linkto>
55 // <li> <linkto class=LatticeIterator>LatticeIterator</linkto>
56 // <li> <linkto class=LatticeNavigator>LatticeNavigator</linkto>
57 // <li> <linkto class=ImageRegion>ImageRegion</linkto>
58 // </prerequisite>
59
60 // <etymology>
61 // The HDF5Image name comes from its role as the Image class using HDF5.
62 // </etymology>
63
64 // <synopsis>
65 // All Casacore Images are Lattices. They may be treated like any other Lattice;
66 // getSlice(...), putSlice(...), LatticeIterator for iterating, etc...
67 // ArrayImages contain a map, a mask for that map, and coordinate
68 // information. This provides a Lattice interface for images and their
69 // respective coordinates. Additional functionality is defined by the
70 // ImageInterface class.
71 //
72 // You can use the global function <src>imagePixelType</src> to determine
73 // what the pixel type of an image is before you open the image if your
74 // code can work with Images of many possible types, or for error checking.
75 //
76 // </synopsis>
77
78 // <example>
79 // This example shows how to create a mask for an image, fill it, and
80 // make it known to the image.
81 // <srcblock>
82 // // Open the image (as readonly for the moment).
83 // HDF5Image<Float> myimage ("image.name");
84 // // Create a mask for the image.
85 // // The mask will be stored in a subtable of the image.
86 // LCPagedMask mask (RegionHandler::makeMask (myimage, "mask.name"));
87 // // Fill the mask with whatever values (e.g. all True).
88 // mask.set (True);
89 // // Make the mask known to the image (with name mask1).
90 // myimage.defineRegion ("mask1", mask, RegionHandler::Masks);
91 // // Make the mask the default mask for this image.
92 // myimage.setDefaultMask ("mask1");
93 // </srcblock>
94 // It is possible to create as many masks as one likes. They can all
95 // be defined as masks for the image (with different names, of course).
96 // However, only one of them can be the default mask (the mask used
97 // by default when the image is opened). When another mask has to be
98 // used, one can do two things:
99 // <ul>
100 // <li> Use setDefaultMask to make the other mask the default mask.
101 // This is advisable when the change should be more or less permanent.
102 // <li> Open the HDF5Image without using a default mask. Thereafter
103 // a <linkto class=SubImage>SubImage</linkto> object can be created
104 // from the HDF5Image and the mask. This is advisable when it the
105 // mask has to be used only one time.
106 // </ul>
107 // </example>
108
109 // <motivation>
110 // The size of astronomical data can be very large. The ability to fit an
111 // entire image into random access memory cannot be guaranteed. Paging from
112 // disk pieces of the image appeared to be the way to deal with this problem.
113 // </motivation>
114
115 // <note>
116 // When you make a new HDF5Image, and you are transferring
117 // information from some other HDF5Image, be aware that you
118 // must copy, manually, things like miscInfo, imageInfo, units,
119 // logSink (history) to the new file.
120 // </note>
121
122 template <class T> class HDF5Image: public ImageInterface<T>
123 {
124 public:
125 // Construct a new Image from shape and coordinate information. The image
126 // will be stored in the named file.
127 HDF5Image (const TiledShape& mapShape,
128 const CoordinateSystem& coordinateInfo,
129 const String& nameOfNewFile);
130
131 // Reconstruct an image from a pre-existing file.
132 // By default the default pixelmask (if available) is used.
133 explicit HDF5Image (const String& fileName, MaskSpecifier = MaskSpecifier());
134
135 // Copy constructor (reference semantics).
136 HDF5Image (const HDF5Image<T>& other);
137
139
140 // Assignment operator (reference semantics).
142
143 // Make a copy of the object (reference semantics).
144 virtual ImageInterface<T>* cloneII() const;
145
146 // Get the image type (returns name of derived class).
147 virtual String imageType() const;
148
149 // Return the current HDF5 file name. By default this includes the full path.
150 // The path preceding the file name can be stripped off on request.
151 virtual String name (Bool stripPath=False) const;
152
153 // Function which changes the shape of the ImageExpr.
154 // Throws an exception as an HDF5Image cannot be resized.
155 virtual void resize(const TiledShape& newShape);
156
157 // Check for symmetry in data members.
158 virtual Bool ok() const;
159
160 // Return the shape of the image.
161 virtual IPosition shape() const;
162
163 // Function which extracts an array from the map.
164 virtual Bool doGetSlice (Array<T>& buffer, const Slicer& theSlice);
165
166 // Function to replace the values in the map with soureBuffer.
167 virtual void doPutSlice (const Array<T>& sourceBuffer,
168 const IPosition& where,
169 const IPosition& stride);
170
171 // Get a pointer the default pixelmask object used with this image.
172 // It returns 0 if no default pixelmask is used.
173 virtual const LatticeRegion* getRegionPtr() const;
174
175 // An HDF5Image is always persistent.
176 virtual Bool isPersistent() const;
177
178 // An HDF5Image is always paged to disk.
179 virtual Bool isPaged() const;
180
181 // Is the HDF5Image writable?
182 virtual Bool isWritable() const;
183
184 // Does the image object use a pixelmask?
185 virtual Bool hasPixelMask() const;
186
187 // Get access to the pixelmask used.
188 // An exception is thrown if the image does not use a pixelmask.
189 // <group>
190 virtual const Lattice<Bool>& pixelMask() const;
192 // </group>
193
194 // Set the default pixelmask to the mask with the given name
195 // (which has to exist in the "masks" group).
196 // If the image file is writable, the setting is persistent by writing
197 // the name as a keyword.
198 // If the given mask name is the empty string,
199 // the default pixelmask is unset.
200 virtual void setDefaultMask (const String& maskName);
201
202 // Use the mask as specified.
203 // If a mask was already in use, it is replaced by the new one.
205
206 // Replace every element, x, of the lattice with the result of f(x).
207 // you must pass in the address of the function -- so the function
208 // must be declared and defined in the scope of your program.
209 // Both versions of apply require a function that accepts a single
210 // argument of type T (the Lattice template actual type) and returns
211 // a result of the same type. The first apply expects a function with
212 // an argument passed by value; the second expects the argument to
213 // be passed by const reference. The first form ought to run faster
214 // for the built-in types, which may be an issue for large Lattices
215 // stored in memory, where disk access is not an issue.
216 // <group>
217 virtual void apply (T (*function)(T));
218 virtual void apply (T (*function)(const T& ));
219 virtual void apply (const Functional<T,T>& function);
220 // </group>
221
222 // Add a lattice to this image.
224
225 // Function which sets the units associated with the image
226 // pixels (i.e. the "brightness" unit). <src>setUnits()</src> returns
227 // False if it cannot set the unit for some reason (e.g. the underlying
228 // file is not writable).
229 virtual Bool setUnits (const Unit& newUnits);
230
231 // Flushes the new coordinate system to disk if the file is writable.
232 virtual Bool setCoordinateInfo (const CoordinateSystem& coords);
233
234 // These are the true implementations of the paran operator.
235 // <note> Not for public use </note>
236 // <group>
237 virtual T getAt (const IPosition& where) const;
238 virtual void putAt (const T& value, const IPosition& where);
239 // </group>
240
241 // Replace the miscinfo in the HDF5Image.
242 // It can fail if, e.g., the underlying file is not writable.
243 virtual Bool setMiscInfo (const RecordInterface& newInfo);
244
245 // The ImageInfo object contains some miscellaneous information about the
246 // image, which unlike that stored in MiscInfo, has a standard list of
247 // things, such as the restoring beam.
248 // Note that setImageInfo REPLACES the information with the new information.
249 // It can fail if, e.g., the underlying file is not writable.
250 virtual Bool setImageInfo(const ImageInfo& info);
251
252 // Get access to the attribute handler.
253 // If a handler keyword does not exist yet, it is created if
254 // <src>createHandler</src> is set.
255 // Otherwise the handler is empty and no groups can be created for it.
256 virtual ImageAttrHandler& attrHandler (Bool createHandler=False);
257
258 // Remove a region/mask belonging to the image from the given group
259 // (which can be Any).
260 // If a mask removed is the default mask, the image gets unmasked.
261 // <br>Optionally an exception is thrown if the region does not exist.
262 virtual void removeRegion (const String& name,
264 Bool throwIfUnknown = True);
265
266 // This is the implementation of the letter for the envelope Iterator
267 // class. <note> Not for public use </note>.
269 (const LatticeNavigator& navigator,
270 Bool useRef) const;
271
272 // Returns the maximum recommended number of pixels for a cursor. This is
273 // the number of pixels in a tile.
274 virtual uInt advisedMaxPixels() const;
275
276 // Help the user pick a cursor for most efficient access.
277 virtual IPosition doNiceCursorShape (uInt maxPixels) const;
278
279 // Flush the data.
280 virtual void flush();
281
282
283 private:
284 // Function to return the internal HDF5File object to the RegionHandler.
285 static const CountedPtr<HDF5File>& getFile (void* imagePtr);
286
287 // This must be called in every constructor and place where the image
288 // is attached to a new image.
291 void restoreUnits (const RecordInterface& rec);
295
296 void check_conformance (const Lattice<T>& other);
298 void applyMask (const String& maskName);
299
300 //# Data members.
304
305 //# Make members of parent class known.
306 public:
308 using ImageInterface<T>::logger;
314 protected:
320 };
321
322
323 // Tell if HDF5 images can be used.
325 { return HDF5Object::hasHDF5Support(); }
326
327 // Determine the pixel type in the HDF5Image contained in
328 // <src>fileName</src>. If the file doesn't appear to be HDF5 or cannot
329 // be opened, TpOther is returned.
330 // <group name="pixeltype")
331 DataType hdf5imagePixelType (const String& fileName);
332 // Check if this HDF5 file is an HDF5 image.
333 Bool isHDF5Image (const String& fileName);
334 // </group>
335
336
337} //# NAMESPACE CASACORE - END
338
339#ifndef CASACORE_NO_AUTO_TEMPLATES
340#include <casacore/images/Images/HDF5Image.tcc>
341#endif //# CASACORE_NO_AUTO_TEMPLATES
342#endif
Referenced counted pointer for constant data.
Definition: CountedPtr.h:81
virtual String name(Bool stripPath=False) const
Return the current HDF5 file name.
virtual T getAt(const IPosition &where) const
These are the true implementations of the paran operator.
HDF5Image(const TiledShape &mapShape, const CoordinateSystem &coordinateInfo, const String &nameOfNewFile)
Construct a new Image from shape and coordinate information.
void restoreImageInfo(const RecordInterface &rec)
void applyMask(const String &maskName)
virtual Bool isWritable() const
Is the HDF5Image writable?
HDF5Image< T > & operator+=(const Lattice< T > &other)
Add a lattice to this image.
HDF5Image(const HDF5Image< T > &other)
Copy constructor (reference semantics).
virtual Bool setUnits(const Unit &newUnits)
Function which sets the units associated with the image pixels (i.e.
virtual void putAt(const T &value, const IPosition &where)
Put the value of a single element.
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Function to replace the values in the map with soureBuffer.
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Help the user pick a cursor for most efficient access.
LatticeRegion * regionPtr_p
Definition: HDF5Image.h:302
virtual Bool setMiscInfo(const RecordInterface &newInfo)
Replace the miscinfo in the HDF5Image.
virtual Bool doGetSlice(Array< T > &buffer, const Slicer &theSlice)
Function which extracts an array from the map.
virtual IPosition shape() const
Return the shape of the image.
virtual void apply(T(*function)(T))
Replace every element, x, of the lattice with the result of f(x).
virtual void flush()
Flush the data.
virtual String imageType() const
Get the image type (returns name of derived class).
virtual Bool setImageInfo(const ImageInfo &info)
The ImageInfo object contains some miscellaneous information about the image, which unlike that store...
virtual ImageAttrHandler & attrHandler(Bool createHandler=False)
Get access to the attribute handler.
HDF5Image(const String &fileName, MaskSpecifier=MaskSpecifier())
Reconstruct an image from a pre-existing file.
virtual Bool isPersistent() const
An HDF5Image is always persistent.
virtual void apply(T(*function)(const T &))
static const CountedPtr< HDF5File > & getFile(void *imagePtr)
Function to return the internal HDF5File object to the RegionHandler.
void applyMaskSpecifier(const MaskSpecifier &)
HDF5Lattice< T > map_p
Definition: HDF5Image.h:301
virtual ImageInterface< T > * cloneII() const
Make a copy of the object (reference semantics).
virtual Lattice< Bool > & pixelMask()
virtual Bool ok() const
Check for symmetry in data members.
virtual Bool setCoordinateInfo(const CoordinateSystem &coords)
Flushes the new coordinate system to disk if the file is writable.
virtual void removeRegion(const String &name, RegionHandler::GroupType=RegionHandler::Any, Bool throwIfUnknown=True)
Remove a region/mask belonging to the image from the given group (which can be Any).
void restoreUnits(const RecordInterface &rec)
HDF5Image< T > & operator=(const HDF5Image< T > &other)
Assignment operator (reference semantics).
virtual uInt advisedMaxPixels() const
Returns the maximum recommended number of pixels for a cursor.
virtual void resize(const TiledShape &newShape)
Function which changes the shape of the ImageExpr.
void restoreMiscInfo(const RecordInterface &rec)
virtual const LatticeRegion * getRegionPtr() const
Get a pointer the default pixelmask object used with this image.
virtual void setDefaultMask(const String &maskName)
Set the default pixelmask to the mask with the given name (which has to exist in the "masks" group).
void attach_logtable()
This must be called in every constructor and place where the image is attached to a new image.
virtual void useMask(MaskSpecifier=MaskSpecifier())
Use the mask as specified.
void check_conformance(const Lattice< T > &other)
virtual LatticeIterInterface< T > * makeIter(const LatticeNavigator &navigator, Bool useRef) const
This is the implementation of the letter for the envelope Iterator class; Note: Not for public use ...
virtual void apply(const Functional< T, T > &function)
virtual Bool hasPixelMask() const
Does the image object use a pixelmask?
virtual Bool isPaged() const
An HDF5Image is always paged to disk.
ImageAttrHandlerHDF5 itsAttrHandler
Definition: HDF5Image.h:303
virtual const Lattice< Bool > & pixelMask() const
Get access to the pixelmask used.
static Bool hasHDF5Support()
Check if there is HDF5 support compiled in.
LogIO & logSink()
Allow messages to be logged to this ImageInterface.
void setCoordsMember(const CoordinateSystem &coords)
Set the coordinate system variable.
LoggerHolder & logger()
Get access to the LoggerHolder.
void setLogMember(const LoggerHolder &logger)
Set the image logger variable.
const ImageInfo & imageInfo() const
The ImageInfo object contains some miscellaneous information about the image which unlike that stored...
virtual String getDefaultMask() const
Get the name of the default pixelmask.
virtual ImageRegion * getImageRegionPtr(const String &name, RegionHandler::GroupType=RegionHandler::Any, Bool throwIfUnknown=True) const
Get a region/mask belonging to the image from the given group (which can be Any).
void setImageInfoMember(const ImageInfo &imageInfo)
Set the image info variable.
virtual Bool hasRegion(const String &regionName, RegionHandler::GroupType=RegionHandler::Any) const
Does the image have a region with the given name?
void setMiscInfoMember(const RecordInterface &rec)
Set the miscinfo variable.
const CoordinateSystem & coordinates() const
void setUnitMember(const Unit &unit)
Set the unit variable.
GroupType
Define the possible group types (regions or masks).
Definition: RegionHandler.h:99
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
const Bool False
Definition: aipstype.h:44
Bool isHDF5Image(const String &fileName)
Check if this HDF5 file is an HDF5 image.
unsigned int uInt
Definition: aipstype.h:51
DataType hdf5imagePixelType(const String &fileName)
Determine the pixel type in the HDF5Image contained in fileName.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
Bool canUseHDF5Image()
Tell if HDF5 images can be used.
Definition: HDF5Image.h:324
const Bool True
Definition: aipstype.h:43