casacore
RegionHandlerHDF5.h
Go to the documentation of this file.
1 //# RegionHandlerHDF5.h: Class for keeping regions in an HDF5 file
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_REGIONHANDLERHDF5_H
29 #define IMAGES_REGIONHANDLERHDF5_H
30 
31 //# Includes
32 #include <casacore/casa/aips.h>
33 #include <casacore/images/Regions/RegionHandler.h>
34 #include <casacore/casa/HDF5/HDF5File.h>
35 #include <casacore/tables/Tables/TableRecord.h>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 
40 // <summary>
41 // Class for keeping regions in an HDF5 file.
42 // </summary>
43 
44 // <use visibility=local>
45 
46 // <reviewed reviewer="" date="" tests="tHDF5Image2.cc" demos="">
47 // </reviewed>
48 
49 // <prerequisite>
50 // <li> <linkto class=HDF5Image>HDF5Image</linkto>
51 // <li> <linkto class=ImageRegion>ImageRegion</linkto>
52 // </prerequisite>
53 
54 // <synopsis>
55 // Persistent regions are stored as subrecords of the table keywords
56 // "regions" and "masks". The user can choose one of both keywords.
57 // Keyword "masks" is meant for true image masks, i.e. telling for
58 // each pixel if it is good or bad. Keyword "regions" is meant for
59 // true regions in an image.
60 // <p>
61 // This class handles defining, getting and removing such regions.
62 // It is used by class <linkto class=PagedImage</linkto>, but it can also
63 // be used by other code to handle regions in other tables.
64 // <p>
65 // Another function performed by this class for PagedImage is the
66 // definition of the default region to be used with an image.
67 // </synopsis>
68 
69 // <example>
70 // </example>
71 
72 // <motivation>
73 // This class has 2 purposes:
74 // <ol>
75 // <li> This untemplated code can be factored out from the templated
76 // Image classes.
77 // <li> The functions can easily be used by other code.
78 // </ol>
79 // </motivation>
80 
81 //# <todo asof="1999/02/16">
82 //# <li>
83 //# </todo>
84 
85 
87 {
88 public:
89  // The HDF5File object needed for the region operations.
90  typedef const CountedPtr<HDF5File>& GetCallback (void* objectPtr);
91 
92  RegionHandlerHDF5 (GetCallback* callback, void* objectPtr);
93 
94  // Copy constructor (copy semantics).
96 
97  virtual ~RegionHandlerHDF5();
98 
99  // Assignment (copy semantics).
101 
102  // Make a copy of the object.
103  virtual RegionHandlerHDF5* clone() const;
104 
105  // Set the object pointer for callback function.
106  virtual void setObjectPtr (void* objectPtr);
107 
108  // This class can define and handle regions.
109  virtual Bool canDefineRegion() const;
110 
111  // Set the default mask to the mask with the given name.
112  // It constructs a ImageRegion object for the new default mask.
113  // If the table is writable, the setting is persistent by writing
114  // the name as a keyword.
115  // If the given maskName is the empty string, the default mask is unset.
116  virtual void setDefaultMask (const String& maskName);
117 
118  // Get the name of the default mask.
119  // An empty string is returned if no default mask.
120  virtual String getDefaultMask() const;
121 
122  // Define a region belonging to the table.
123  // The group type determines if it stored as a region or mask.
124  // If overwrite=False, an exception will be thrown if the region
125  // already exists in the "regions" or "masks" keyword.
126  // Otherwise the region will be removed first.
127  // <br>A False status is returned if the table is not writable
128  virtual Bool defineRegion (const String& name,
129  const ImageRegion& region,
131  Bool overwrite = False);
132 
133  // Does the table have a region with the given name?
134  virtual Bool hasRegion (const String& name,
136 
137  // Get a region belonging to the table.
138  // A zero pointer is returned if the region does not exist.
139  // The caller has to delete the <src>ImageRegion</src> object created.
140  // <br>No exception is thrown if the region does not exist.
141  virtual ImageRegion* getRegion (const String& name,
143  Bool throwIfUnknown = True) const;
144 
145  // Rename a region.
146  // If a region with the new name already exists, it is deleted or
147  // an exception is thrown (depending on <src>overwrite</src>).
148  // The region name is looked up in the given group(s).
149  // <br>An exception is thrown if the old region name does not exist.
150  virtual Bool renameRegion (const String& newName,
151  const String& oldName,
153  Bool overwrite = False);
154 
155  // Remove a region belonging to the table.
156  // <br>Optionally an exception is thrown if the region does not exist.
157  // <br>A False status is returned if the table is not writable
158  virtual Bool removeRegion (const String& name,
160  Bool throwIfUnknown = True);
161 
162  // Get the names of all regions/masks.
164 
165  // Make a mask (an LCPagedMask) for a stored lattice (a PagedImage).
166  // It creates it with the shape and tile shape of the lattice.
167  virtual ImageRegion makeMask (const LatticeBase& lattice,
168  const String& name);
169 
170  // Save the record containing the masking info in the HDF5 file.
171  // It is only saved if changed or if always is true.
172  void save (Bool always=False);
173 
174  // Restore the record containing the masking info from the HDF5 file.
175  void restore();
176 
177 private:
178  // Get the file object.
179  const CountedPtr<HDF5File>& file() const
180  { return itsCallback (itsObjectPtr); }
181 
182  // Find field number of the region group to which a region belongs
183  // (i.e. the field number of the "regions" or "masks" field).
184  // <0 is returned if the region does not exist.
185  // <br>Optionally an exception is thrown if the region does not exist.
186  virtual Int findRegionGroup (const String& regionName,
188  Bool throwIfUnknown = True) const;
189 
190 
192  Bool itsChanged; //# Has the record changed?
195 };
196 
197 
198 } //# NAMESPACE CASACORE - END
199 
200 #endif
Referenced counted pointer for constant data.
Definition: CountedPtr.h:81
RegionHandlerHDF5(GetCallback *callback, void *objectPtr)
virtual Bool removeRegion(const String &name, RegionHandler::GroupType=Any, Bool throwIfUnknown=True)
Remove a region belonging to the table.
virtual Bool defineRegion(const String &name, const ImageRegion &region, RegionHandler::GroupType, Bool overwrite=False)
Define a region belonging to the table.
virtual ImageRegion makeMask(const LatticeBase &lattice, const String &name)
Make a mask for a lattice (e.g.
void save(Bool always=False)
RegionHandlerHDF5 & operator=(const RegionHandlerHDF5 &)
virtual Bool canDefineRegion() const
Can the class indeed define and handle regions? The default implementation returns False.
const CountedPtr< HDF5File > & GetCallback(void *objectPtr)
virtual Int findRegionGroup(const String &regionName, RegionHandler::GroupType=Any, Bool throwIfUnknown=True) const
virtual Vector< String > regionNames(RegionHandler::GroupType=Any) const
Get the names of all regions/masks.
virtual ImageRegion * getRegion(const String &name, RegionHandler::GroupType=Any, Bool throwIfUnknown=True) const
Get a region belonging to the table.
virtual Bool hasRegion(const String &name, RegionHandler::GroupType=RegionHandler::Any) const
Does the table have a region with the given name?
const CountedPtr< HDF5File > & file() const
virtual String getDefaultMask() const
Get the name of the default mask.
virtual Bool renameRegion(const String &newName, const String &oldName, RegionHandler::GroupType=Any, Bool overwrite=False)
Rename a region.
virtual RegionHandlerHDF5 * clone() const
Make a copy of the object.
virtual void setDefaultMask(const String &maskName)
Set the default mask to the mask with the given name.
RegionHandlerHDF5(const RegionHandlerHDF5 &)
virtual void setObjectPtr(void *objectPtr)
Set the object pointer (for RegionHandlerTable's callback).
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
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43