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