casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
36 
37 namespace casacore { //# NAMESPACE CASACORE - BEGIN
38 
39 //# Forward Declarations
40 class Table;
41 class ImageRegion;
42 class LatticeBase;
43 class LCPagedMask;
44 class 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 {
95 public:
96  virtual ~RegionHandler();
97 
98  // Define the possible group types (regions or masks).
99  enum GroupType {
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.
176  String makeUniqueRegionName (const String& rootName,
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 
A 1-D Specialization of the Array class.
Definition: ArrayFwd.h:9
virtual RegionHandler * clone() const
Make a copy of the object.
virtual void setObjectPtr(void *objectPtr)
Set the object pointer (for RegionHandlerTable&#39;s callback).
virtual Vector< String > regionNames(RegionHandler::GroupType=Any) const
Get the names of all regions/masks.
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...
A non-templated, abstract base class for array-like objects.
Definition: LatticeBase.h:80
virtual Bool hasRegion(const String &name, RegionHandler::GroupType=RegionHandler::Any) const
Does the table have a region with the given name?
Base class for handling regions in images.
Definition: RegionHandler.h:93
virtual Bool removeRegion(const String &name, RegionHandler::GroupType=Any, Bool throwIfUnknown=True)
Remove a region belonging to the table.
virtual void setDefaultMask(const String &maskName)
Set the default mask to the mask with the given name.
virtual ImageRegion makeMask(const LatticeBase &lattice, const String &name)
Make a mask for a lattice (e.g.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual Bool canDefineRegion() const
Can the class indeed define and handle regions? The default implementation returns False...
virtual Bool renameRegion(const String &newName, const String &oldName, RegionHandler::GroupType=Any, Bool overwrite=False)
Rename a region.
const Bool False
Definition: aipstype.h:44
virtual ImageRegion * getRegion(const String &name, RegionHandler::GroupType=Any, Bool throwIfUnknown=True) const
Get a region belonging to the table.
Class to hold a region of interest in an image.
Definition: ImageRegion.h:86
virtual Bool defineRegion(const String &name, const ImageRegion &region, RegionHandler::GroupType, Bool overwrite=False)
Define a region belonging to the table.
String: the storage and methods of handling collections of characters.
Definition: String.h:225
virtual String getDefaultMask() const
Get the name of the default mask.
const Bool True
Definition: aipstype.h:43
GroupType
Define the possible group types (regions or masks).
Definition: RegionHandler.h:99
unsigned int uInt
Definition: aipstype.h:51