00001 //# ImageAttrHandler.h: Abstract base class for an image attributes handler 00002 //# Copyright (C) 2012 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_IMAGEATTRHANDLER_H 00029 #define IMAGES_IMAGEATTRHANDLER_H 00030 00031 00032 //# Includes 00033 #include <casacore/casa/aips.h> 00034 #include <casacore/images/Images/ImageAttrGroup.h> 00035 #include <casacore/casa/Containers/ValueHolder.h> 00036 #include <casacore/casa/Arrays/Vector.h> 00037 00038 namespace casacore { 00039 00040 // <summary> 00041 // Abstract base class for an image attributes handler. 00042 // </summary> 00043 00044 // <use visibility=export> 00045 00046 // <reviewed reviewer="" date="" tests="tPagedmage.cc" demos="dPagedImage.cc"> 00047 // </reviewed> 00048 00049 // <prerequisite> 00050 // <li> <linkto class=ImageInterface>ImageInterface</linkto> 00051 // </prerequisite> 00052 00053 // <etymology> 00054 // This class makes it possible to store extra attributes with an image to 00055 // describe atrbitrary meta information. 00056 // </etymology> 00057 00058 // <synopsis> 00059 // For LOFAR it was needed to store extra meta information and to be able to 00060 // convert it from casacore table format to HDF5 format and vice-versa. 00061 // Furthermore, it must be possible to access the information in a way that 00062 // arbitrary info can be stored and retrieved. 00063 // 00064 // An ImageAttrHandler object handles those attributes in an image. Specific 00065 // handler classes exist for images stored in casacore and in HDF5 format. 00066 // The attributes are divided into group which are handled by ImageAttrGroup. 00067 // A group (e.g. LOFAR_SOURCES) maps to a subtable in casacore format and a 00068 // group in HDF5 format. 00069 // </synopsis> 00070 00071 // <example> 00072 // This example shows how to get attributes from an image. 00073 // <srcblock> 00074 // // Open the image (done as read/write when having write access). 00075 // PagedImage<Float> myimage ("image.name"); 00076 // // Get access to the attibute handler. 00077 // ImageAttrHandler& attrHandler = myimage.attrHandler(); 00078 // // Get the names of all attribute groups. 00079 // Vector<String> groupNames = attrHandler.groupNames(); 00080 // // Create a new group and define an attribute defining Freq in Hz. 00081 // ImageAttrGroup& newGroup = attrHandler.createGroup ("NEW_GROUP"); 00082 // newGroup.putAttr ("Freq", ValueHolder(Vector<Double>(1, 1e7)), 00083 // Vector<String>(1,"Hz")); 00084 // </srcblock> 00085 // </example> 00086 // 00087 // <motivation> 00088 // LOFAR needed functionality to store arbitrary attributes. 00089 // </motivation> 00090 00091 class ImageAttrHandler 00092 { 00093 public: 00094 // Default constructor. 00095 ImageAttrHandler() 00096 {} 00097 00098 virtual ~ImageAttrHandler(); 00099 00100 // Flush the attibrutes if needed. 00101 // The default implementation does nothing. 00102 virtual void flush(); 00103 00104 // Test if the given attribute group is present. 00105 // The default implementation returns False. 00106 virtual Bool hasGroup (const String& name); 00107 00108 // Get all attribute group names. 00109 // The default implementation returns an empty vector. 00110 virtual Vector<String> groupNames() const; 00111 00112 // Get access to a group. 00113 // The default implementation throws an exception. 00114 virtual ImageAttrGroup& openGroup (const String& groupName); 00115 00116 // Create an attribute group with the given name. 00117 // The default implementation throws an exception. 00118 virtual ImageAttrGroup& createGroup (const String& groupName); 00119 00120 // Close the group with the given name. 00121 // The default implementation does nothing. 00122 virtual void closeGroup (const String& groupName); 00123 }; 00124 00125 } //# NAMESPACE CASACORE - END 00126 00127 #endif