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 
40 namespace 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 
138  ~HDF5Image();
139 
140  // Assignment operator (reference semantics).
141  HDF5Image<T>& operator= (const HDF5Image<T>& other);
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;
191  virtual Lattice<Bool>& pixelMask();
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.
204  virtual void useMask (MaskSpecifier = MaskSpecifier());
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.
223  HDF5Image<T>& operator+= (const Lattice<T>& other);
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.
289  void attach_logtable();
290  void open_logtable();
291  void restoreUnits (const RecordInterface& rec);
292  void restoreMiscInfo (const RecordInterface& rec);
293  void restoreImageInfo (const RecordInterface& rec);
294  void restoreAll();
295 
296  void check_conformance (const Lattice<T>& other);
297  void applyMaskSpecifier (const MaskSpecifier&);
298  void applyMask (const String& maskName);
299 
300  //# Data members.
304 
305  //# Make members of parent class known.
306  public:
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
casacore::CoordinateSystem
Interconvert pixel and world coordinates.
Definition: CoordinateSystem.h:217
casacore::ImageInterface
A base class for astronomical images.
Definition: ImageFITSConverter.h:48
casacore::Slicer
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:289
casacore::IPosition
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
casacore::HDF5Image::open_logtable
void open_logtable()
casacore::HDF5Image::setImageInfo
virtual Bool setImageInfo(const ImageInfo &info)
The ImageInfo object contains some miscellaneous information about the image, which unlike that store...
casacore::HDF5Image::getFile
static const CountedPtr< HDF5File > & getFile(void *imagePtr)
Function to return the internal HDF5File object to the RegionHandler.
casacore::HDF5Image::isWritable
virtual Bool isWritable() const
Is the HDF5Image writable?
casacore::RegionHandler::GroupType
GroupType
Define the possible group types (regions or masks).
Definition: RegionHandler.h:99
casacore::RegionHandler::Any
Definition: RegionHandler.h:102
casacore::HDF5Image::operator=
HDF5Image< T > & operator=(const HDF5Image< T > &other)
Assignment operator (reference semantics).
casacore::HDF5Image::applyMaskSpecifier
void applyMaskSpecifier(const MaskSpecifier &)
casacore::HDF5Image::HDF5Image
HDF5Image(const TiledShape &mapShape, const CoordinateSystem &coordinateInfo, const String &nameOfNewFile)
Construct a new Image from shape and coordinate information.
casacore::HDF5Image::apply
virtual void apply(T(*function)(T))
Replace every element, x, of the lattice with the result of f(x).
casacore::HDF5Image::getRegionPtr
virtual const LatticeRegion * getRegionPtr() const
Get a pointer the default pixelmask object used with this image.
casacore::HDF5Image::name
virtual String name(Bool stripPath=False) const
Return the current HDF5 file name.
casacore::CountedPtr
Referenced counted pointer for constant data.
Definition: CountedPtr.h:80
casacore::Functional
Map a domain object into a range object via operator().
Definition: Array.h:53
casacore::HDF5Lattice
A Lattice that is read from or written to an HDF5 dataset.
Definition: HDF5Lattice.h:109
casacore::HDF5Image::makeIter
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 ...
casacore::HDF5Image::resize
virtual void resize(const TiledShape &newShape)
Function which changes the shape of the ImageExpr.
casacore::HDF5Image::restoreUnits
void restoreUnits(const RecordInterface &rec)
casacore::HDF5Image::getAt
virtual T getAt(const IPosition &where) const
These are the true implementations of the paran operator.
casacore::HDF5Image::isPersistent
virtual Bool isPersistent() const
An HDF5Image is always persistent.
casacore::LatticeRegion
An optionally strided region in a Lattice.
Definition: LatticeRegion.h:74
casacore::HDF5Image::shape
virtual IPosition shape() const
Return the shape of the image.
casacore::HDF5Image::imageType
virtual String imageType() const
Get the image type (returns name of derived class).
casacore::HDF5Image::setMiscInfo
virtual Bool setMiscInfo(const RecordInterface &newInfo)
Replace the miscinfo in the HDF5Image.
casacore::isHDF5Image
Bool isHDF5Image(const String &fileName)
Check if this HDF5 file is an HDF5 image.
casacore::HDF5Image::regionPtr_p
LatticeRegion * regionPtr_p
Definition: HDF5Image.h:302
casacore::HDF5Image::applyMask
void applyMask(const String &maskName)
casacore::HDF5Image::restoreAll
void restoreAll()
casacore::HDF5Image::restoreMiscInfo
void restoreMiscInfo(const RecordInterface &rec)
casacore::value
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
casacore::LatticeNavigator
Abstract base class to steer lattice iterators.
Definition: LatticeNavigator.h:182
casacore::False
const Bool False
Definition: aipstype.h:44
casacore::uInt
unsigned int uInt
Definition: aipstype.h:51
casacore::HDF5Image::putAt
virtual void putAt(const T &value, const IPosition &where)
Put the value of a single element.
casacore::HDF5Image::restoreImageInfo
void restoreImageInfo(const RecordInterface &rec)
casacore::HDF5Image::isPaged
virtual Bool isPaged() const
An HDF5Image is always paged to disk.
casacore::MaskSpecifier
Class to specify which mask to use in an image.
Definition: MaskSpecifier.h:69
casacore::ImageAttrHandlerHDF5
Abstract base class for an image attributes handler.
Definition: ImageAttrHandlerHDF5.h:89
casacore::HDF5Image::hasPixelMask
virtual Bool hasPixelMask() const
Does the image object use a pixelmask?
casacore::HDF5Image::setUnits
virtual Bool setUnits(const Unit &newUnits)
Function which sets the units associated with the image pixels (i.e.
casacore::HDF5Image::itsAttrHandler
ImageAttrHandlerHDF5 itsAttrHandler
Definition: HDF5Image.h:303
casacore::HDF5Image::advisedMaxPixels
virtual uInt advisedMaxPixels() const
Returns the maximum recommended number of pixels for a cursor.
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::HDF5Image::attrHandler
virtual ImageAttrHandler & attrHandler(Bool createHandler=False)
Get access to the attribute handler.
casacore::HDF5Image::useMask
virtual void useMask(MaskSpecifier=MaskSpecifier())
Use the mask as specified.
casacore::HDF5Image::operator+=
HDF5Image< T > & operator+=(const Lattice< T > &other)
Add a lattice to this image.
casacore::True
const Bool True
Definition: aipstype.h:43
casacore::HDF5Image::doNiceCursorShape
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Help the user pick a cursor for most efficient access.
casacore::HDF5Image::removeRegion
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).
casacore::HDF5Image
Read, store, and manipulate astronomical images in HDF5 format.
Definition: HDF5Image.h:122
casacore::HDF5Image::doGetSlice
virtual Bool doGetSlice(Array< T > &buffer, const Slicer &theSlice)
Function which extracts an array from the map.
casacore::RecordInterface
Abstract base class for Record classes.
Definition: RecordInterface.h:144
casacore::HDF5Image::attach_logtable
void attach_logtable()
This must be called in every constructor and place where the image is attached to a new image.
casacore::HDF5Image::doPutSlice
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Function to replace the values in the map with soureBuffer.
casacore::Lattice< Bool >
casacore::Array
template <class T, class U> class vector;
Definition: Array.h:166
casacore::HDF5Image::ok
virtual Bool ok() const
Check for symmetry in data members.
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::HDF5Image::cloneII
virtual ImageInterface< T > * cloneII() const
Make a copy of the object (reference semantics).
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::ImageAttrHandler
Abstract base class for an image attributes handler.
Definition: ImageAttrHandler.h:91
casacore::canUseHDF5Image
Bool canUseHDF5Image()
Tell if HDF5 images can be used.
Definition: HDF5Image.h:324
casacore::Unit
defines physical units
Definition: Unit.h:189
casacore::HDF5Image::flush
virtual void flush()
Flush the data.
casacore::HDF5Image::pixelMask
virtual const Lattice< Bool > & pixelMask() const
Get access to the pixelmask used.
casacore::HDF5Image::setDefaultMask
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).
casacore::HDF5Object::hasHDF5Support
static Bool hasHDF5Support()
Check if there is HDF5 support compiled in.
casacore::HDF5Image::~HDF5Image
~HDF5Image()
casacore::HDF5Image::map_p
HDF5Lattice< T > map_p
Definition: HDF5Image.h:301
casacore::HDF5Image::check_conformance
void check_conformance(const Lattice< T > &other)
casacore::hdf5imagePixelType
DataType hdf5imagePixelType(const String &fileName)
Determine the pixel type in the HDF5Image contained in fileName.
casacore::TiledShape
Define the shape and tile shape.
Definition: TiledShape.h:99
casacore::ImageInfo
Miscellaneous information related to an image.
Definition: ImageInfo.h:92
casacore::HDF5Image::setCoordinateInfo
virtual Bool setCoordinateInfo(const CoordinateSystem &coords)
Flushes the new coordinate system to disk if the file is writable.
casacore::LatticeIterInterface
A base class for Lattice iterators.
Definition: ImageExpr.h:47