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