casacore
ImageBeamSet.h
Go to the documentation of this file.
1 //# Copyright (C) 1996,1997,1998,1999,2000,2001,2003
2 //# Associated Universities, Inc. Washington DC, USA.
3 //#
4 //# This library is free software; you can redistribute it and/or modify it
5 //# under the terms of the GNU Library General Public License as published by
6 //# the Free Software Foundation; either version 2 of the License, or (at your
7 //# option) any later version.
8 //#
9 //# This library is distributed in the hope that it will be useful, but WITHOUT
10 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 //# License for more details.
13 //#
14 //# You should have received a copy of the GNU Library General Public License
15 //# along with this library; if not, write to the Free Software Foundation,
16 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
17 //#
18 //# Correspondence concerning AIPS++ should be addressed as follows:
19 //# Internet email: aips2-request@nrao.edu.
20 //# Postal address: AIPS++ Project Office
21 //# National Radio Astronomy Observatory
22 //# 520 Edgemont Road
23 //# Charlottesville, VA 22903-2475 USA
24 //#
25 //# $Id$
26 
27 #ifndef IMAGES_IMAGEBEAMSET_H
28 #define IMAGES_IMAGEBEAMSET_H
29 
30 #include <casacore/casa/aips.h>
31 #include <casacore/casa/Arrays/Matrix.h>
32 #include <casacore/scimath/Mathematics/GaussianBeam.h>
33 //#include <casacore/measures/Measures/Stokes.h>
34 //#include <map>
35 
36 namespace casacore {
37 
38 class SpectralCoordinate;
39 
40 class CoordinateSystem;
41 
42 // <summary>
43 // Represents a set of restoring beams associated with an image.
44 // </summary>
45 
46 // <use visibility=export>
47 
48 // <reviewed reviewer="" date="yyyy/mm/dd" tests="" demos="">
49 // </reviewed>
50 
51 // <prerequisite>
52 // </prerequisite>
53 
54 // <etymology>
55 // A Set of Beams associated with an Image.
56 // </etymology>
57 
58 // <synopsis>
59 // This class represents a set of restoring beams associated with
60 // a deconvolved image. Internally, the beams are stored in a Matrix in
61 // which the first dimension represents the spectral axis and the second
62 // dimension represents the polarization axis. Methods which take the number
63 // of channels and stokes as the input parameters will accept 0 for either of
64 // these, in the cases where the corresponding axis is absent, but internally,
65 // the associated axis of the storage Matrix will be set to one since a Matrix
66 // with one dimension of length 0 must be empty. If one (or both) of the axes is
67 // of length 1, the beam associated with that position is valid for all channels or
68 // stokes at the position. For example, if one has an image with 10 spectral channels
69 // and 4 stokes, and one has a beam set of dimensions (1, 4) associated with that image,
70 // all channels for a given stokes will have the same beam. Similarly, if the beam set
71 // is of shape (10, 1) in this case, all stokes will have the same beam for a given channel.
72 // If the axis lengths of the beam set are greater than one, they must be exactly
73 // the same length of the corresponding axes in the associated image.
74 // </synopsis>
75 //
76 // <example>
77 
78 // </example>
79 
80 
81 // <motivation>
82 // Restoring beams are used many places in image analysis tasks.
83 // </motivation>
84 
85 // <todo>
86 // </todo>
87 
88 class ImageBeamSet {
89 public:
90 
92 
93  // Construct an empty beam set.
94  ImageBeamSet();
95 
96  // Construct a beam set from an 2-D array of beams representing
97  // the frequency and stokes axis.
98  // Axis length 1 means it is valid for all channels cq. stokes.
99  // If the image has 0 spectral channels or stokes, the corresponding
100  // length of the axis in the provided matrix should be 1.
101  ImageBeamSet(
102  const Matrix<GaussianBeam>& beams
103  );
104 
105  // construct an ImageBeamSet representing a single beam which is valid for
106  // all channels and stokes
107  ImageBeamSet(const GaussianBeam& beam);
108 
109  // Create an ImageBeamSet of the specified shape with all
110  // GaussianBeams initialized to <src>beam</src>.
112 
113  // The copy constructor (reference semantics).
114  ImageBeamSet(const ImageBeamSet& other);
115 
116  ~ImageBeamSet();
117 
118  // Assignment can change the shape (copy semantics).
119  ImageBeamSet& operator=(const ImageBeamSet& other);
120 
121  // Beam sets are equal if the shapes and all corresponding beams are equal.
122  Bool operator== (const ImageBeamSet& other) const;
123  Bool operator!= (const ImageBeamSet& other) const;
124 
125  // Beam sets are equivalent if both have no beams or if the
126  // expanded sets are equal. Expanded means that an axis can have
127  // length 0 or 1 and is (virtually) expanded to the length of the matching
128  // axis in the other beam set.
129  Bool equivalent (const ImageBeamSet& that) const;
130 
131  // Get the number of elements in the beam array.
132  // <group>
133  uInt nelements() const
134  { return _beams.size(); }
135  uInt size() const
136  { return _beams.size(); }
137  // </group>
138 
140  { return _beams.size() == 1; }
141 
142  // Does this beam set contain multiple beams?
143  Bool hasMultiBeam() const {
144  return _beams.size() > 1;
145  }
146 
147  // Is the beam set empty?
148  Bool empty() const
149  { return _beams.empty(); }
150 
151  // Get the shape of the beam array. The minimum value for
152  // a component of the returned IPosition is always 1.
153  const IPosition& shape() const
154  { return _beams.shape(); }
155 
156  // Get the number of channels in the beam array. NOte that this will
157  // always return a minimum of 1, even if nchan was specified as 0 on construction.
158  uInt nchan() const
159  { return _beams.shape()[0]; }
160 
161  // Get the number of stokes in the beam array. Note that this will always
162  // return a minimum of 1, even if nstokes was specified as 0 on construction.
163  uInt nstokes() const
164  { return _beams.shape()[1]; }
165 
166  // Get the single global beam. If there are multiple beams,
167  // an exception is thrown.
168  const GaussianBeam& getBeam() const;
169 
170  // Get the beam at the specified location.
171  // Note that a single channel or stokes in the beam set is valid for
172  // all channels cq. stokes.
173  // <group>
174  const GaussianBeam& getBeam(Int chan, Int stokes) const;
175  const GaussianBeam &operator()(Int chan, Int stokes) const
176  { return getBeam (chan, stokes); }
177  // </group>
178 
179  // Get a beam at the given 2-dim IPosition. It should match exactly,
180  // thus a single channel or stokes in the beam set is not valid for all.
181  // const GaussianBeam& getBeam(const IPosition& pos) const
182  // { return _beams(pos); }
183 
184  // Set the beam at the given location.
185  // The location must be within the beam set shape.
186  // If <src>chan</src> or <src>stokes</src> is negative, then the beam applies
187  // to all channels or stokes, respectively. If both are negative, the specified
188  // beam becomes the global beam and the beam set is resized to (1, 1).
189  void setBeam(Int chan, Int stokes, const GaussianBeam& beam);
190 
191  // Resize the beam array. <src>nchan</src>=0 or <src>nstokes</src>=0
192  // is silently changed to 1.
193  void resize(uInt nchan, uInt nstokes);
194 
195  // Return a subset of the beam array.
196  // The slicer is usually the slicer used for a subimage.
197  // The slicer can contain multiple stokes or channels, even if the
198  // beam set has only one.
199  ImageBeamSet subset (const Slicer& imageSlicer,
200  const CoordinateSystem& csys) const;
201 
202  // Get the beam array.
204  { return _beams; }
205 
206  // Set the beams in this beam set.
207  // The shape of the given array must match the beam set.
208  // It also matches if an axis in array or beam set has length 1, which
209  // means that it expands to the other length.
210  void setBeams(const Matrix<GaussianBeam>& beams);
211 
212  // Set all beams to the same value.
213  void set(const GaussianBeam& beam);
214 
215  // Get the beam in the set which has the smallest area.
217  { return _minBeam; }
218 
219  // Get the beam in the set which has the largest area.
220  // Get the beam in the set which has the largest area.
222  { return _maxBeam; }
223 
224  // Get the beam in the set which has the median area.
226 
227  // Get the position of the beam with the minimum area.
229  { return _minBeamPos; }
230 
231  // Get the position of the beam with the maximum area.
233  { return _maxBeamPos; }
234 
235  // Get the minimal, maximal, and median area beams and positions in the beam set matrix for
236  // the given stokes. If the stokes axis has length 1 in the beam matrix,
237  // it is valid for all stokes and no checking is done that <src>stokes</src> is valid;
238  // the requested beam for the entire beam set is simply returned in this case. If the
239  // number of stokes in the beam matrix is >1, checking is done that the specified value
240  // of <src>stokes</src> is valid and if not, an exception is thrown.
241  // <group>
243  uInt stokes) const;
244 
246  uInt stokes) const;
247 
249  uInt stokes) const;
250  // </group>
251 
252  static const String& className();
253 
254  // Get the beam that has the smallest minor axis. If multiple beams have the smallest minor axis,
255  // the beam in this subset with the smallest area will be returned.
257 
258  // convert ImageBeamSet to and from record
259  // <group>
260  static ImageBeamSet fromRecord(const Record& rec);
261  Record toRecord() const;
262  //</group>
263 
264  // If verbose, log all beams, if not just summarize beam stats.
265  void summarize(LogIO& log, Bool verbose, const CoordinateSystem& csys) const;
266 
267  // Modify the beam set by rotating all beams counterclockwise through the specified angle.
268  void rotate(const Quantity& angle);
269 
270 private:
271 
273 
279 
280  void _calculateAreas();
281 
282  static void _chanInfoToStream(
283  ostream& os, const SpectralCoordinate *spCoord,
284  const uInt chan, const uInt chanWidth, const uInt freqPrec,
285  const uInt velWidth, const uInt velPrec
286  );
287 
288  static void _beamToStream(
289  ostream& os, const GaussianBeam& beam,
290  const Unit& unit
291  );
292 };
293 
294 ostream &operator<<(ostream &os, const ImageBeamSet& beamSet);
295 
296 }
297 
298 #endif
299 
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
int Int
Definition: aipstype.h:47
GaussianBeam getMinAreaBeam() const
Get the beam in the set which has the smallest area.
Definition: ImageBeamSet.h:216
IPosition getMaxAreaBeamPosition() const
Get the position of the beam with the maximum area.
Definition: ImageBeamSet.h:232
LatticeExprNode log(const LatticeExprNode &expr)
const Matrix< GaussianBeam > & getBeams() const
Get the beam array.
Definition: ImageBeamSet.h:203
void resize(uInt nchan, uInt nstokes)
Resize the beam array.
ImageBeamSet & operator=(const ImageBeamSet &other)
Assignment can change the shape (copy semantics).
Bool operator==(const ImageBeamSet &other) const
Beam sets are equal if the shapes and all corresponding beams are equal.
void setBeams(const Matrix< GaussianBeam > &beams)
Set the beams in this beam set.
static const String & className()
const GaussianBeam & getMaxAreaBeamForPol(IPosition &pos, uInt stokes) const
void rotate(const Quantity &angle)
Modify the beam set by rotating all beams counterclockwise through the specified angle.
uInt nelements() const
Get the number of elements in the beam array.
Definition: ImageBeamSet.h:133
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
const GaussianBeam & operator()(Int chan, Int stokes) const
Definition: ImageBeamSet.h:175
A 2-D Specialization of the Array class.
Definition: Array.h:53
ostream-like interface to creating log messages.
Definition: LogIO.h:167
Record toRecord() const
ImageBeamSet()
Construct an empty beam set.
Bool hasMultiBeam() const
Does this beam set contain multiple beams?
Definition: ImageBeamSet.h:143
static void _beamToStream(ostream &os, const GaussianBeam &beam, const Unit &unit)
const IPosition & shape() const
Get the shape of the beam array.
Definition: ImageBeamSet.h:153
Bool hasSingleBeam() const
Definition: ImageBeamSet.h:139
Represents a Gaussian restoring beam associated with an image.
Definition: GaussianBeam.h:68
const GaussianBeam & getBeam() const
Get the single global beam.
defines physical units
Definition: Unit.h:189
Represents a set of restoring beams associated with an image.
Definition: ImageBeamSet.h:88
const GaussianBeam & getMinAreaBeamForPol(IPosition &pos, uInt stokes) const
Get the minimal, maximal, and median area beams and positions in the beam set matrix for the given st...
static void _chanInfoToStream(ostream &os, const SpectralCoordinate *spCoord, const uInt chan, const uInt chanWidth, const uInt freqPrec, const uInt velWidth, const uInt velPrec)
Array< GaussianBeam >::const_iterator BeamIter
Definition: ImageBeamSet.h:91
A hierarchical collection of named fields of various types.
Definition: Record.h:181
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:39
Matrix< Double > _areas
Definition: ImageBeamSet.h:275
void summarize(LogIO &log, Bool verbose, const CoordinateSystem &csys) const
If verbose, log all beams, if not just summarize beam stats.
Matrix< GaussianBeam > _beams
Definition: ImageBeamSet.h:274
uInt nstokes() const
Get the number of stokes in the beam array.
Definition: ImageBeamSet.h:163
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:275
Interconvert pixel and frequency values.
static const String _DEFAULT_AREA_UNIT
Definition: ImageBeamSet.h:272
IPosition getMinAreaBeamPosition() const
Get the position of the beam with the minimum area.
Definition: ImageBeamSet.h:228
GaussianBeam getMedianAreaBeam() const
Get the beam in the set which has the median area.
Bool equivalent(const ImageBeamSet &that) const
Beam sets are equivalent if both have no beams or if the expanded sets are equal. ...
GaussianBeam getMaxAreaBeam() const
Get the beam in the set which has the largest area.
Definition: ImageBeamSet.h:221
uInt nchan() const
Get the number of channels in the beam array.
Definition: ImageBeamSet.h:158
const GaussianBeam & getMedianAreaBeamForPol(IPosition &pos, uInt stokes) const
String: the storage and methods of handling collections of characters.
Definition: String.h:223
Bool empty() const
Is the beam set empty?
Definition: ImageBeamSet.h:148
const GaussianBeam getSmallestMinorAxisBeam() const
Get the beam that has the smallest minor axis.
Bool operator!=(const ImageBeamSet &other) const
ImageBeamSet subset(const Slicer &imageSlicer, const CoordinateSystem &csys) const
Return a subset of the beam array.
static const GaussianBeam NULL_BEAM
Definition: GaussianBeam.h:71
this file contains all the compiler specific defines
Definition: mainpage.dox:28
Interconvert pixel and world coordinates.
unsigned int uInt
Definition: aipstype.h:48
static ImageBeamSet fromRecord(const Record &rec)
convert ImageBeamSet to and from record
void setBeam(Int chan, Int stokes, const GaussianBeam &beam)
Get a beam at the given 2-dim IPosition.