00001 //# RegionHandlerHDF5.h: Class for keeping regions in an HDF5 file 00002 //# Copyright (C) 2008 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_REGIONHANDLERHDF5_H 00029 #define IMAGES_REGIONHANDLERHDF5_H 00030 00031 //# Includes 00032 #include <casacore/casa/aips.h> 00033 #include <casacore/images/Regions/RegionHandler.h> 00034 #include <casacore/casa/HDF5/HDF5File.h> 00035 #include <casacore/tables/Tables/TableRecord.h> 00036 00037 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00038 00039 00040 // <summary> 00041 // Class for keeping regions in an HDF5 file. 00042 // </summary> 00043 00044 // <use visibility=local> 00045 00046 // <reviewed reviewer="" date="" tests="tHDF5Image2.cc" demos=""> 00047 // </reviewed> 00048 00049 // <prerequisite> 00050 // <li> <linkto class=HDF5Image>HDF5Image</linkto> 00051 // <li> <linkto class=ImageRegion>ImageRegion</linkto> 00052 // </prerequisite> 00053 00054 // <synopsis> 00055 // Persistent regions are stored as subrecords of the table keywords 00056 // "regions" and "masks". The user can choose one of both keywords. 00057 // Keyword "masks" is meant for true image masks, i.e. telling for 00058 // each pixel if it is good or bad. Keyword "regions" is meant for 00059 // true regions in an image. 00060 // <p> 00061 // This class handles defining, getting and removing such regions. 00062 // It is used by class <linkto class=PagedImage</linkto>, but it can also 00063 // be used by other code to handle regions in other tables. 00064 // <p> 00065 // Another function performed by this class for PagedImage is the 00066 // definition of the default region to be used with an image. 00067 // </synopsis> 00068 00069 // <example> 00070 // </example> 00071 00072 // <motivation> 00073 // This class has 2 purposes: 00074 // <ol> 00075 // <li> This untemplated code can be factored out from the templated 00076 // Image classes. 00077 // <li> The functions can easily be used by other code. 00078 // </ol> 00079 // </motivation> 00080 00081 //# <todo asof="1999/02/16"> 00082 //# <li> 00083 //# </todo> 00084 00085 00086 class RegionHandlerHDF5: public RegionHandler 00087 { 00088 public: 00089 // The HDF5File object needed for the region operations. 00090 typedef const CountedPtr<HDF5File>& GetCallback (void* objectPtr); 00091 00092 RegionHandlerHDF5 (GetCallback* callback, void* objectPtr); 00093 00094 // Copy constructor (copy semantics). 00095 RegionHandlerHDF5 (const RegionHandlerHDF5&); 00096 00097 virtual ~RegionHandlerHDF5(); 00098 00099 // Assignment (copy semantics). 00100 RegionHandlerHDF5& operator= (const RegionHandlerHDF5&); 00101 00102 // Make a copy of the object. 00103 virtual RegionHandlerHDF5* clone() const; 00104 00105 // Set the object pointer for callback function. 00106 virtual void setObjectPtr (void* objectPtr); 00107 00108 // This class can define and handle regions. 00109 virtual Bool canDefineRegion() const; 00110 00111 // Set the default mask to the mask with the given name. 00112 // It constructs a ImageRegion object for the new default mask. 00113 // If the table is writable, the setting is persistent by writing 00114 // the name as a keyword. 00115 // If the given maskName is the empty string, the default mask is unset. 00116 virtual void setDefaultMask (const String& maskName); 00117 00118 // Get the name of the default mask. 00119 // An empty string is returned if no default mask. 00120 virtual String getDefaultMask() const; 00121 00122 // Define a region belonging to the table. 00123 // The group type determines if it stored as a region or mask. 00124 // If overwrite=False, an exception will be thrown if the region 00125 // already exists in the "regions" or "masks" keyword. 00126 // Otherwise the region will be removed first. 00127 // <br>A False status is returned if the table is not writable 00128 virtual Bool defineRegion (const String& name, 00129 const ImageRegion& region, 00130 RegionHandler::GroupType, 00131 Bool overwrite = False); 00132 00133 // Does the table have a region with the given name? 00134 virtual Bool hasRegion (const String& name, 00135 RegionHandler::GroupType = RegionHandler::Any) const; 00136 00137 // Get a region belonging to the table. 00138 // A zero pointer is returned if the region does not exist. 00139 // The caller has to delete the <src>ImageRegion</src> object created. 00140 // <br>No exception is thrown if the region does not exist. 00141 virtual ImageRegion* getRegion (const String& name, 00142 RegionHandler::GroupType = Any, 00143 Bool throwIfUnknown = True) const; 00144 00145 // Rename a region. 00146 // If a region with the new name already exists, it is deleted or 00147 // an exception is thrown (depending on <src>overwrite</src>). 00148 // The region name is looked up in the given group(s). 00149 // <br>An exception is thrown if the old region name does not exist. 00150 virtual Bool renameRegion (const String& newName, 00151 const String& oldName, 00152 RegionHandler::GroupType = Any, 00153 Bool overwrite = False); 00154 00155 // Remove a region belonging to the table. 00156 // <br>Optionally an exception is thrown if the region does not exist. 00157 // <br>A False status is returned if the table is not writable 00158 virtual Bool removeRegion (const String& name, 00159 RegionHandler::GroupType = Any, 00160 Bool throwIfUnknown = True); 00161 00162 // Get the names of all regions/masks. 00163 virtual Vector<String> regionNames (RegionHandler::GroupType = Any) const; 00164 00165 // Make a mask (an LCPagedMask) for a stored lattice (a PagedImage). 00166 // It creates it with the shape and tile shape of the lattice. 00167 virtual ImageRegion makeMask (const LatticeBase& lattice, 00168 const String& name); 00169 00170 // Save the record containing the masking info in the HDF5 file. 00171 // It is only saved if changed or if always is true. 00172 void save (Bool always=False); 00173 00174 // Restore the record containing the masking info from the HDF5 file. 00175 void restore(); 00176 00177 private: 00178 // Get the file object. 00179 const CountedPtr<HDF5File>& file() const 00180 { return itsCallback (itsObjectPtr); } 00181 00182 // Find field number of the region group to which a region belongs 00183 // (i.e. the field number of the "regions" or "masks" field). 00184 // <0 is returned if the region does not exist. 00185 // <br>Optionally an exception is thrown if the region does not exist. 00186 virtual Int findRegionGroup (const String& regionName, 00187 RegionHandler::GroupType = Any, 00188 Bool throwIfUnknown = True) const; 00189 00190 00191 TableRecord itsRecord; 00192 Bool itsChanged; //# Has the record changed? 00193 GetCallback* itsCallback; 00194 void* itsObjectPtr; 00195 }; 00196 00197 00198 } //# NAMESPACE CASACORE - END 00199 00200 #endif