00001 //# RegionHandlerTable.h: Class for keeping regions in memory 00002 //# Copyright (C) 2000 00003 //# Associated Universities, Inc. Washington DC, USA. 00004 //# 00005 //# This library is free software; you can redistribute it and/or modify it 00006 //# under the terms of the GNU Library General Public License as published by 00007 //# the Free Software Foundation; either version 2 of the License, or (at your 00008 //# option) any later version. 00009 //# 00010 //# This library is distributed in the hope that it will be useful, but WITHOUT 00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00012 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00013 //# License for more details. 00014 //# 00015 //# You should have received a copy of the GNU Library General Public License 00016 //# along with this library; if not, write to the Free Software Foundation, 00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00018 //# 00019 //# Correspondence concerning AIPS++ should be addressed as follows: 00020 //# Internet email: aips2-request@nrao.edu. 00021 //# Postal address: AIPS++ Project Office 00022 //# National Radio Astronomy Observatory 00023 //# 520 Edgemont Road 00024 //# Charlottesville, VA 22903-2475 USA 00025 //# 00026 //# $Id$ 00027 00028 #ifndef IMAGES_REGIONHANDLERTABLE_H 00029 #define IMAGES_REGIONHANDLERTABLE_H 00030 00031 00032 //# Includes 00033 #include <casacore/casa/aips.h> 00034 #include <casacore/images/Regions/RegionHandler.h> 00035 00036 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00037 00038 //# Forward declarations 00039 class Table; 00040 00041 00042 // <summary> 00043 // Class for keeping regions in memory. 00044 // </summary> 00045 00046 // <use visibility=local> 00047 00048 // <reviewed reviewer="" date="" tests="tPagedImage2.cc" demos=""> 00049 // </reviewed> 00050 00051 // <prerequisite> 00052 // <li> <linkto class=PagedImage>PagedImage</linkto> 00053 // <li> <linkto class=ImageRegion>ImageRegion</linkto> 00054 // </prerequisite> 00055 00056 // <synopsis> 00057 // Persistent regions are stored as subrecords of the table keywords 00058 // "regions" and "masks". The user can choose one of both keywords. 00059 // Keyword "masks" is meant for true image masks, i.e. telling for 00060 // each pixel if it is good or bad. Keyword "regions" is meant for 00061 // true regions in an image. 00062 // <p> 00063 // This class handles defining, getting and removing such regions. 00064 // It is used by class <linkto class=PagedImage</linkto>, but it can also 00065 // be used by other code to handle regions in other tables. 00066 // <p> 00067 // Another function performed by this class for PagedImage is the 00068 // definition of the default region to be used with an image. 00069 // </synopsis> 00070 00071 // <example> 00072 // </example> 00073 00074 // <motivation> 00075 // This class has 2 purposes: 00076 // <ol> 00077 // <li> This untemplated code can be factored out from the templated 00078 // Image classes. 00079 // <li> The functions can easily be used by other code. 00080 // </ol> 00081 // </motivation> 00082 00083 //# <todo asof="1999/02/16"> 00084 //# <li> 00085 //# </todo> 00086 00087 00088 class RegionHandlerTable: public RegionHandler 00089 { 00090 public: 00091 // Define the signature of the function being called to get 00092 // the table object needed for the region operations. 00093 typedef Table& GetCallback (void* objectPtr, Bool writable); 00094 00095 RegionHandlerTable (GetCallback* callback, void* objectPtr); 00096 00097 // Copy constructor (copy semantics). 00098 RegionHandlerTable (const RegionHandlerTable&); 00099 00100 virtual ~RegionHandlerTable(); 00101 00102 // Assignment (copy semantics). 00103 RegionHandlerTable& operator= (const RegionHandlerTable&); 00104 00105 // Make a copy of the object. 00106 virtual RegionHandlerTable* clone() const; 00107 00108 // Set the object pointer for callback function. 00109 virtual void setObjectPtr (void* objectPtr); 00110 00111 // This class can define and handle regions. 00112 virtual Bool canDefineRegion() const; 00113 00114 // Set the default mask to the mask with the given name. 00115 // It constructs a ImageRegion object for the new default mask. 00116 // If the table is writable, the setting is persistent by writing 00117 // the name as a keyword. 00118 // If the given maskName is the empty string, the default mask is unset. 00119 virtual void setDefaultMask (const String& maskName); 00120 00121 // Get the name of the default mask. 00122 // An empty string is returned if no default mask. 00123 virtual String getDefaultMask() const; 00124 00125 // Define a region belonging to the table. 00126 // The group type determines if it stored as a region or mask. 00127 // If overwrite=False, an exception will be thrown if the region 00128 // already exists in the "regions" or "masks" keyword. 00129 // Otherwise the region will be removed first. 00130 // <br>A False status is returned if the table is not writable 00131 virtual Bool defineRegion (const String& name, 00132 const ImageRegion& region, 00133 RegionHandler::GroupType, 00134 Bool overwrite = False); 00135 00136 // Does the table have a region with the given name? 00137 virtual Bool hasRegion (const String& name, 00138 RegionHandler::GroupType = RegionHandler::Any) const; 00139 00140 // Get a region belonging to the table. 00141 // A zero pointer is returned if the region does not exist. 00142 // The caller has to delete the <src>ImageRegion</src> object created. 00143 // <br>No exception is thrown if the region does not exist. 00144 virtual ImageRegion* getRegion (const String& name, 00145 RegionHandler::GroupType = Any, 00146 Bool throwIfUnknown = True) const; 00147 00148 // Rename a region. 00149 // If a region with the new name already exists, it is deleted or 00150 // an exception is thrown (depending on <src>overwrite</src>). 00151 // The region name is looked up in the given group(s). 00152 // <br>An exception is thrown if the old region name does not exist. 00153 virtual Bool renameRegion (const String& newName, 00154 const String& oldName, 00155 RegionHandler::GroupType = Any, 00156 Bool overwrite = False); 00157 00158 // Remove a region belonging to the table. 00159 // <br>Optionally an exception is thrown if the region does not exist. 00160 // <br>A False status is returned if the table is not writable 00161 virtual Bool removeRegion (const String& name, 00162 RegionHandler::GroupType = Any, 00163 Bool throwIfUnknown = True); 00164 00165 // Get the names of all regions/masks. 00166 virtual Vector<String> regionNames (RegionHandler::GroupType = Any) const; 00167 00168 // Make a mask (an LCPagedMask) for a stored lattice (a PagedImage). 00169 // It creates it with the shape and tile shape of the lattice. 00170 virtual ImageRegion makeMask (const LatticeBase& lattice, 00171 const String& name); 00172 00173 private: 00174 // Get the table object. 00175 // <group> 00176 Table& rwTable() 00177 { return itsCallback (itsObjectPtr, True); } 00178 const Table& table() const 00179 { return itsCallback (const_cast<RegionHandlerTable*>(this)->itsObjectPtr, 00180 False); } 00181 // </group> 00182 00183 // Find field number of the region group to which a region belongs 00184 // (i.e. the field number of the "regions" or "masks" field). 00185 // <0 is returned if the region does not exist. 00186 // <br>Optionally an exception is thrown if the region does not exist. 00187 virtual Int findRegionGroup (const String& regionName, 00188 RegionHandler::GroupType = Any, 00189 Bool throwIfUnknown = True) const; 00190 00191 00192 GetCallback* itsCallback; 00193 void* itsObjectPtr; 00194 }; 00195 00196 00197 00198 00199 } //# NAMESPACE CASACORE - END 00200 00201 #endif