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
IPosition getMaxAreaBeamPosition() const
Get the position of the beam with the maximum area.
Definition: ImageBeamSet.h:232
int Int
Definition: aipstype.h:47
LatticeExprNode log(const LatticeExprNode &expr)
uInt nstokes() const
Get the number of stokes in the beam array.
Definition: ImageBeamSet.h:163
void resize(uInt nchan, uInt nstokes)
Resize the beam array.
ImageBeamSet & operator=(const ImageBeamSet &other)
Assignment can change the shape (copy semantics).
void summarize(LogIO &log, Bool verbose, const CoordinateSystem &csys) const
If verbose, log all beams, if not just summarize beam stats.
Record toRecord() const
Bool equivalent(const ImageBeamSet &that) const
Beam sets are equivalent if both have no beams or if the expanded sets are equal. ...
const IPosition & shape() const
Get the shape of the beam array.
Definition: ImageBeamSet.h:153
void setBeams(const Matrix< GaussianBeam > &beams)
Set the beams in this beam set.
static const String & className()
GaussianBeam getMinAreaBeam() const
Get the beam in the set which has the smallest area.
Definition: ImageBeamSet.h:216
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...
void rotate(const Quantity &angle)
Modify the beam set by rotating all beams counterclockwise through the specified angle.
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
const GaussianBeam & getMaxAreaBeamForPol(IPosition &pos, uInt stokes) const
ImageBeamSet()
Construct an empty beam set.
static void _beamToStream(ostream &os, const GaussianBeam &beam, const Unit &unit)
Represents a Gaussian restoring beam associated with an image.
Definition: GaussianBeam.h:68
defines physical units
Definition: Unit.h:189
Bool empty() const
Is the beam set empty?
Definition: ImageBeamSet.h:148
Bool hasSingleBeam() const
Definition: ImageBeamSet.h:139
IPosition getMinAreaBeamPosition() const
Get the position of the beam with the minimum area.
Definition: ImageBeamSet.h:228
const GaussianBeam & getBeam() const
Get the single global beam.
Represents a set of restoring beams associated with an image.
Definition: ImageBeamSet.h:88
GaussianBeam getMedianAreaBeam() const
Get the beam in the set which has the median area.
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
ImageBeamSet subset(const Slicer &imageSlicer, const CoordinateSystem &csys) const
Return a subset of the beam array.
Matrix< Double > _areas
Definition: ImageBeamSet.h:275
Matrix< GaussianBeam > _beams
Definition: ImageBeamSet.h:274
Bool operator!=(const ImageBeamSet &other) const
const Matrix< GaussianBeam > & getBeams() const
Get the beam array.
Definition: ImageBeamSet.h:203
Bool operator==(const ImageBeamSet &other) const
Beam sets are equal if the shapes and all corresponding beams are equal.
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:275
Interconvert pixel and frequency values.
GaussianBeam getMaxAreaBeam() const
Get the beam in the set which has the largest area.
Definition: ImageBeamSet.h:221
static const String _DEFAULT_AREA_UNIT
Definition: ImageBeamSet.h:272
Bool hasMultiBeam() const
Does this beam set contain multiple beams?
Definition: ImageBeamSet.h:143
String: the storage and methods of handling collections of characters.
Definition: String.h:223
static const GaussianBeam NULL_BEAM
Definition: GaussianBeam.h:71
const GaussianBeam & getMedianAreaBeamForPol(IPosition &pos, uInt stokes) const
const GaussianBeam getSmallestMinorAxisBeam() const
Get the beam that has the smallest minor axis.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
uInt nelements() const
Get the number of elements in the beam array.
Definition: ImageBeamSet.h:133
Interconvert pixel and world coordinates.
unsigned int uInt
Definition: aipstype.h:48
static ImageBeamSet fromRecord(const Record &rec)
convert ImageBeamSet to and from record
uInt nchan() const
Get the number of channels in the beam array.
Definition: ImageBeamSet.h:158
void setBeam(Int chan, Int stokes, const GaussianBeam &beam)
Get a beam at the given 2-dim IPosition.