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
casacore::RegionHandler::GroupType
GroupType
Define the possible group types (regions or masks).
Definition: RegionHandler.h:99
casacore::RegionHandlerTable::canDefineRegion
virtual Bool canDefineRegion() const
Can the class indeed define and handle regions? The default implementation returns False.
casacore::RegionHandler::Any
@ Any
Definition: RegionHandler.h:102
casacore::RegionHandlerTable::setObjectPtr
virtual void setObjectPtr(void *objectPtr)
Set the object pointer (for RegionHandlerTable's callback).
casacore::RegionHandlerTable::RegionHandlerTable
RegionHandlerTable(GetCallback *callback, void *objectPtr)
casacore::RegionHandlerTable::setDefaultMask
virtual void setDefaultMask(const String &maskName)
Set the default mask to the mask with the given name.
casacore::RegionHandlerTable
Class for keeping regions in memory.
Definition: RegionHandlerTable.h:89
casacore::RegionHandlerTable::findRegionGroup
virtual Int findRegionGroup(const String &regionName, RegionHandler::GroupType=Any, Bool throwIfUnknown=True) const
casacore::RegionHandlerTable::~RegionHandlerTable
virtual ~RegionHandlerTable()
casacore::Table
Main interface class to a read/write table.
Definition: Table.h:154
casacore::RegionHandlerTable::itsCallback
GetCallback * itsCallback
Definition: RegionHandlerTable.h:192
casacore::False
const Bool False
Definition: aipstype.h:44
casacore::RegionHandlerTable::renameRegion
virtual Bool renameRegion(const String &newName, const String &oldName, RegionHandler::GroupType=Any, Bool overwrite=False)
Rename a region.
casacore::RegionHandlerTable::operator=
RegionHandlerTable & operator=(const RegionHandlerTable &)
casacore::LatticeBase
A non-templated, abstract base class for array-like objects.
Definition: LatticeBase.h:81
casacore::RegionHandlerTable::clone
virtual RegionHandlerTable * clone() const
Make a copy of the object.
casacore::Int
int Int
Definition: aipstype.h:50
casacore
this file contains all the compiler specific defines
Definition: mainpage.dox:28
casacore::RegionHandlerTable::hasRegion
virtual Bool hasRegion(const String &name, RegionHandler::GroupType=RegionHandler::Any) const
Does the table have a region with the given name?
casacore::RegionHandlerTable::getRegion
virtual ImageRegion * getRegion(const String &name, RegionHandler::GroupType=Any, Bool throwIfUnknown=True) const
Get a region belonging to the table.
casacore::RegionHandlerTable::itsObjectPtr
void * itsObjectPtr
Definition: RegionHandlerTable.h:193
casacore::RegionHandlerTable::removeRegion
virtual Bool removeRegion(const String &name, RegionHandler::GroupType=Any, Bool throwIfUnknown=True)
Remove a region belonging to the table.
casacore::RegionHandlerTable::getDefaultMask
virtual String getDefaultMask() const
Get the name of the default mask.
casacore::True
const Bool True
Definition: aipstype.h:43
casacore::RegionHandlerTable::defineRegion
virtual Bool defineRegion(const String &name, const ImageRegion &region, RegionHandler::GroupType, Bool overwrite=False)
Define a region belonging to the table.
casacore::RegionHandlerTable::RegionHandlerTable
RegionHandlerTable(const RegionHandlerTable &)
casacore::String
String: the storage and methods of handling collections of characters.
Definition: String.h:223
casacore::RegionHandler
Base class for handling regions in images.
Definition: RegionHandler.h:94
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
casacore::ImageRegion
Class to hold a region of interest in an image.
Definition: ImageRegion.h:87
casacore::Vector
A 1-D Specialization of the Array class.
Definition: ArrayIO.h:45
casacore::RegionHandlerTable::GetCallback
Table & GetCallback(void *objectPtr, Bool writable)
Definition: RegionHandlerTable.h:93
casacore::RegionHandlerTable::makeMask
virtual ImageRegion makeMask(const LatticeBase &lattice, const String &name)
Make a mask for a lattice (e.g.
casacore::RegionHandlerTable::table
const Table & table() const
Definition: RegionHandlerTable.h:178
casacore::RegionHandlerTable::rwTable
Table & rwTable()
Definition: RegionHandlerTable.h:176
casacore::RegionHandlerTable::regionNames
virtual Vector< String > regionNames(RegionHandler::GroupType=Any) const
Get the names of all regions/masks.