casacore
ImageAttrGroup.h
Go to the documentation of this file.
1 //# ImageAttrGroup.h: Abstract base class for an image attributes group
2 //# Copyright (C) 2012
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_IMAGEATTRGROUP_H
29 #define IMAGES_IMAGEATTRGROUP_H
30 
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/Containers/ValueHolder.h>
35 #include <casacore/casa/Arrays/Vector.h>
36 
37 namespace casacore {
38 
39 // <summary>
40 // Abstract base class for an image attributes group.
41 // </summary>
42 
43 // <use visibility=export>
44 
45 // <reviewed reviewer="" date="" tests="tPagedmage.cc" demos="dPagedImage.cc">
46 // </reviewed>
47 
48 // <prerequisite>
49 // <li> <linkto class=ImageInterface>ImageInterface</linkto>
50 // </prerequisite>
51 
52 // <etymology>
53 // This class makes it possible to store extra attributes with an image to
54 // describe atrbitrary meta information.
55 // </etymology>
56 
57 // <synopsis>
58 // For LOFAR it is needed to store extra meta information and be possible to
59 // convert it from casacore table format to HDF5 format and vice-versa.
60 // Furthermore, it must be possible to access the information in a way that
61 // arbitrary attributes can be stored and retrieved in a way that is agnostic
62 // to the format the image is stored in. It must also work fine for an image
63 // stored in FITS format, be it that such an image cannot have such attributes.
64 //
65 // The attributes are divided into groups. A group resides in a subtable
66 // of a casacore image or in a group of an HDF5 image. This class handles
67 // the attributes of a group. It can get and put the attribute values, as well
68 // as their unit and measure info (type and reference frame type).
69 // For HDF5 images the unit is stored in attribute <src>attrname>_UNIT</src>
70 // and the measure info in <src>attrname>_MEASINFO</src>. For casacore images
71 // that info is stored as TableMeasure info in the column keywords.
72 //
73 // All attributes in a group must have the same number of values, where each
74 // value can be a scalar or (small) array. The unit and measure info have
75 // only one value, thus all values of an attribute have the same unit.
76 // </synopsis>
77 
78 // <example>
79 // This example shows how to get attributes from an image.
80 // <srcblock>
81 // // Open the image.
82 // PagedImage<Float> myimage ("image.name");
83 // // Open the attribute handler.
84 // ImageAttrHandler& attrHandler = myimage.attrHandler();
85 // // Get access to attibute group LOFAR_SOURCE.
86 // ImageAttrGroup& lofarSource = attrHandler.openGroup ("LOFAR_SOURCE");
87 // // Get the names of all attributes in this group.
88 // Vector<String> attrNames = lofarSource.attrNames();
89 // // Get the value of the ATTRNAME attribute (if there).
90 // if (lofarSource.hasAttr ("ATTRNAME)) {
91 // ValueHolder vh (lofarSource.getData ("ATTRNAME"));
92 // Vector<String> name = vh.asString();
93 // }
94 // </srcblock>
95 // The following example shows how to add a group and attribute.
96 // <srcblock>
97 // // Open the image.
98 // PagedImage<Float> myimage ("image.name");
99 // // Open the attribute handler.
100 // ImageAttrHandler& attrHandler = myimage.attrHandler();
101 // // Add attribute group LOFAR_SOURCE.
102 // ImageAttrGroup& lofarSource = attrHandler.createGroup (LOFAR_SOURCE);
103 // // Add an attribute which has unit Hz.
104 // // The value has 2 values (e.g. for 2 frequency bands).
105 // Vector<double> freqs(2);
106 // freqs[0]=4.5e7; freqs[1]=5.5e7;
107 // lofarSource.putData ("CENTER_FREQ", ValueHolder(freqs),
108 // Vector<String(1,"Hz"));
109 // </srcblock>
110 // </example>
111 //
112 // <motivation>
113 // LOFAR needed functionality to store arbitrary attributes.
114 // </motivation>
115 
117 {
118 public:
119  // Default constructor.
121  {}
122 
123  virtual ~ImageAttrGroup();
124 
125  // Get the number of rows in the group.
126  virtual uInt nrows() const = 0;
127 
128  // Test if an attribute exists.
129  virtual Bool hasAttr (const String& attrName) const = 0;
130 
131  // Get all attribute names.
132  virtual Vector<String> attrNames() const = 0;
133 
134  // Get the datatype of a attribute.
135  // It returns TpOther if the attribute is not defined.
136  virtual DataType dataType (const String& attrName) const = 0;
137 
138  // Get the data of the given attribute in the given row
139  virtual ValueHolder getData (const String& attrName, uInt rownr) = 0;
140 
141  // Get the data of all attributes in a rows.
142  virtual Record getDataRow (uInt rownr) = 0;
143 
144  // Get the possible units of the values.
145  // An empty vector is returned if the attribute has no units.
146  virtual Vector<String> getUnit (const String& attrName) = 0;
147 
148  // Get the possible measure info as type and Ref.
149  // An empty vector is returned if the attribute has no MEASINFO.
150  virtual Vector<String> getMeasInfo (const String& attrName) = 0;
151 
152  // Put the data of the given attribute in the given row.
153  // If the row or attribute is new, it will be added. Note that the
154  // new row must be directly after the last row in the group.
155  // <br>If not empty, the units and MEASINFO will be put as column keywords.
156  // The MEASINFO vector must be given as type,Ref.
157  virtual void putData (const String& attrName, uInt rownr,
158  const ValueHolder& data,
159  const Vector<String>& units = Vector<String>(),
160  const Vector<String>& measInfo = Vector<String>()) = 0;
161 };
162 
163 } //# NAMESPACE CASACORE - END
164 
165 #endif
virtual DataType dataType(const String &attrName) const =0
Get the datatype of a attribute.
virtual Vector< String > getMeasInfo(const String &attrName)=0
Get the possible measure info as type and Ref.
virtual ValueHolder getData(const String &attrName, uInt rownr)=0
Get the data of the given attribute in the given row.
virtual Vector< String > attrNames() const =0
Get all attribute names.
virtual Bool hasAttr(const String &attrName) const =0
Test if an attribute exists.
virtual void putData(const String &attrName, uInt rownr, const ValueHolder &data, const Vector< String > &units=Vector< String >(), const Vector< String > &measInfo=Vector< String >())=0
Put the data of the given attribute in the given row.
ImageAttrGroup()
Default constructor.
virtual uInt nrows() const =0
Get the number of rows in the group.
virtual Vector< String > getUnit(const String &attrName)=0
Get the possible units of the values.
virtual Record getDataRow(uInt rownr)=0
Get the data of all attributes in a rows.
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
unsigned int uInt
Definition: aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42