casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
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
A Vector of integers, for indexing into Array&lt;T&gt; objects.
Definition: IPosition.h:119
void attach_logtable()
This must be called in every constructor and place where the image is attached to a new image...
virtual void putAt(const T &value, const IPosition &where)
Put the value of a single element.
virtual void setDefaultMask(const String &maskName)
Set the default pixelmask to the mask with the given name (which has to exist in the &quot;masks&quot; group)...
virtual IPosition shape() const
Return the shape of the image.
virtual Bool hasPixelMask() const
Does the image object use a pixelmask?
void applyMask(const String &maskName)
Map a domain object into a range object via operator().
Definition: Functional.h:122
LatticeRegion * regionPtr_p
Definition: HDF5Image.h:302
virtual String imageType() const
Get the image type (returns name of derived class).
virtual Bool setUnits(const Unit &newUnits)
Function which sets the units associated with the image pixels (i.e.
virtual const Lattice< Bool > & pixelMask() const
Get access to the pixelmask used.
virtual Bool setImageInfo(const ImageInfo &info)
The ImageInfo object contains some miscellaneous information about the image, which unlike that store...
virtual Bool isPaged() const
An HDF5Image is always paged to disk.
static Bool hasHDF5Support()
Check if there is HDF5 support compiled in.
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).
virtual void flush()
Flush the data.
virtual String name(Bool stripPath=False) const
Return the current HDF5 file name.
Abstract base class for an image attributes handler.
virtual void apply(T(*function)(T))
Replace every element, x, of the lattice with the result of f(x).
virtual IPosition doNiceCursorShape(uInt maxPixels) const
Help the user pick a cursor for most efficient access.
virtual uInt advisedMaxPixels() const
Returns the maximum recommended number of pixels for a cursor.
defines physical units
Definition: Unit.h:189
virtual void resize(const TiledShape &newShape)
Function which changes the shape of the ImageExpr.
HDF5Image< T > & operator=(const HDF5Image< T > &other)
Assignment operator (reference semantics).
A base class for Lattice iterators.
Definition: SubImage.h:46
Define the shape and tile shape.
Definition: TiledShape.h:99
Referenced counted pointer for constant data.
Definition: VisModelData.h:42
A base class for astronomical images.
virtual Bool ok() const
Check for symmetry in data members.
Class to specify which mask to use in an image.
Definition: MaskSpecifier.h:69
virtual Bool setMiscInfo(const RecordInterface &newInfo)
Replace the miscinfo in the HDF5Image.
DataType hdf5imagePixelType(const String &fileName)
Determine the pixel type in the HDF5Image contained in fileName.
virtual const LatticeRegion * getRegionPtr() const
Get a pointer the default pixelmask object used with this image.
Bool canUseHDF5Image()
Tell if HDF5 images can be used.
Definition: HDF5Image.h:324
virtual T getAt(const IPosition &where) const
These are the true implementations of the paran operator.
void restoreUnits(const RecordInterface &rec)
HDF5Image(const TiledShape &mapShape, const CoordinateSystem &coordinateInfo, const String &nameOfNewFile)
Construct a new Image from shape and coordinate information.
void applyMaskSpecifier(const MaskSpecifier &)
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool False
Definition: aipstype.h:44
Read, store, and manipulate astronomical images in HDF5 format.
Definition: HDF5Image.h:122
template &lt;class T, class U&gt; class vector;
Definition: MSFlagger.h:37
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:289
ImageAttrHandlerHDF5 itsAttrHandler
Definition: HDF5Image.h:303
virtual Bool isWritable() const
Is the HDF5Image writable?
virtual Bool isPersistent() const
An HDF5Image is always persistent.
Bool isHDF5Image(const String &fileName)
Check if this HDF5 file is an HDF5 image.
void restoreMiscInfo(const RecordInterface &rec)
Abstract base class for an image attributes handler.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
An optionally strided region in a Lattice.
Definition: LatticeRegion.h:74
HDF5Image< T > & operator+=(const Lattice< T > &other)
Add a lattice to this image.
virtual Bool doGetSlice(Array< T > &buffer, const Slicer &theSlice)
Function which extracts an array from the map.
Abstract base class for Record classes.
virtual ImageInterface< T > * cloneII() const
Make a copy of the object (reference semantics).
HDF5Lattice< T > map_p
Definition: HDF5Image.h:301
virtual void useMask(MaskSpecifier=MaskSpecifier())
Use the mask as specified.
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 ...
Miscellaneous information related to an image.
Definition: ImageInfo.h:92
virtual void doPutSlice(const Array< T > &sourceBuffer, const IPosition &where, const IPosition &stride)
Function to replace the values in the map with soureBuffer.
const Bool True
Definition: aipstype.h:43
virtual ImageAttrHandler & attrHandler(Bool createHandler=False)
Get access to the attribute handler.
A Lattice that is read from or written to an HDF5 dataset.
Definition: HDF5Lattice.h:109
void check_conformance(const Lattice< T > &other)
virtual Bool setCoordinateInfo(const CoordinateSystem &coords)
Flushes the new coordinate system to disk if the file is writable.
GroupType
Define the possible group types (regions or masks).
Definition: RegionHandler.h:99
Interconvert pixel and world coordinates.
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.
static const CountedPtr< HDF5File > & getFile(void *imagePtr)
Function to return the internal HDF5File object to the RegionHandler.
unsigned int uInt
Definition: aipstype.h:51
Abstract base class to steer lattice iterators.
void restoreImageInfo(const RecordInterface &rec)
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42