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?
144  { return _beams.size() > 1; }
145 
146  // Is the beam set empty?
147  Bool empty() const
148  { return _beams.empty(); }
149 
150  // Get the shape of the beam array. The minimum value for
151  // a component of the returned IPosition is always 1.
152  const IPosition& shape() const
153  { return _beams.shape(); }
154 
155  // Get the number of channels in the beam array. Note that this will
156  // always return a minimum of 1, even if nchan was specified as 0 on construction.
157  uInt nchan() const
158  { return _beams.shape()[0]; }
159 
160  // Get the number of stokes in the beam array. Note that this will always
161  // return a minimum of 1, even if nstokes was specified as 0 on construction.
162  uInt nstokes() const
163  { return _beams.shape()[1]; }
164 
165  // Get the single global beam. If there are multiple beams,
166  // an exception is thrown.
167  const GaussianBeam& getBeam() const;
168 
169  // Get the beam at the specified location.
170  // Note that a single channel or stokes in the beam set is valid for
171  // all channels cq. stokes.
172  // <group>
173  const GaussianBeam& getBeam(Int chan, Int stokes) const;
174  const GaussianBeam &operator()(Int chan, Int stokes) const
175  { return getBeam (chan, stokes); }
176  // </group>
177 
178  // Get a beam at the given 2-dim IPosition. It should match exactly,
179  // thus a single channel or stokes in the beam set is not valid for all.
180  // const GaussianBeam& getBeam(const IPosition& pos) const
181  // { return _beams(pos); }
182 
183  // Set the beam at the given location.
184  // The location must be within the beam set shape.
185  // If <src>chan</src> or <src>stokes</src> is negative, then the beam applies
186  // to all channels or stokes, respectively. If both are negative, the specified
187  // beam becomes the global beam and the beam set is resized to (1, 1).
188  void setBeam(Int chan, Int stokes, const GaussianBeam& beam);
189 
190  // Resize the beam array. <src>nchan</src>=0 or <src>nstokes</src>=0
191  // is silently changed to 1.
192  void resize(uInt nchan, uInt nstokes);
193 
194  // Return a subset of the beam array.
195  // The slicer is usually the slicer used for a subimage.
196  // The slicer can contain multiple stokes or channels, even if the
197  // beam set has only one.
198  ImageBeamSet subset (const Slicer& imageSlicer,
199  const CoordinateSystem& csys) const;
200 
201  // Get the beam array.
203  { return _beams; }
204 
205  // Set the beams in this beam set.
206  // The shape of the given array must match the beam set.
207  // It also matches if an axis in array or beam set has length 1, which
208  // means that it expands to the other length.
209  void setBeams(const Matrix<GaussianBeam>& beams);
210 
211  // Set all beams to the same value.
212  void set(const GaussianBeam& beam);
213 
214  // Get the beam in the set which has the smallest area.
216  { return _minBeam; }
217 
218  // Get the beam in the set which has the largest area.
219  // Get the beam in the set which has the largest area.
221  { return _maxBeam; }
222 
223  // Get the beam in the set which has the median area.
225 
226  // Get the position of the beam with the minimum area.
228  { return _minBeamPos; }
229 
230  // Get the position of the beam with the maximum area.
232  { return _maxBeamPos; }
233 
234  // Get the minimal, maximal, and median area beams and positions in the
235  // beam set matrix for the given stokes. If the stokes axis has length 1
236  // in the beam matrix, it is valid for all stokes and no checking is done
237  // that <src>stokes</src> is valid; the requested beam for the entire beam set
238  // is simply returned in this case.
239  // If the number of stokes in the beam matrix is >1, checking is done that
240  // the specified value of <src>stokes</src> is valid and if not, an exception
241  // is thrown.
242  // <group>
244  uInt stokes) const;
245 
247  uInt stokes) const;
248 
250  uInt stokes) const;
251  // </group>
252 
253  static const String& className();
254 
255  // Get the beam that has the smallest minor axis. If multiple beams have
256  // the smallest minor axis, the beam in this subset with the smallest area
257  // will be returned.
259 
260  // convert ImageBeamSet to and from record
261  // <group>
262  static ImageBeamSet fromRecord(const Record& rec);
263  Record toRecord() const;
264  //</group>
265 
266  // If verbose, log all beams, if not just summarize beam stats.
267  void summarize(LogIO& log, Bool verbose, const CoordinateSystem& csys) const;
268 
269  // Modify the beam set by rotating all beams counterclockwise through the
270  // specified angle. If unwrap=True, unwrap the new position angle(s) so that
271  // it falls in the range -90 to 90 degrees before setting it.
272  void rotate(const Quantity& angle, Bool unwrap=False);
273 
274 private:
275 
277 
283 
284  void _calculateAreas();
285 
286  // Show the spectral info.
287  static void _chanInfoToStream(
288  ostream& os, const SpectralCoordinate *spCoord,
289  const uInt chan, const uInt chanWidth, const uInt freqPrec,
290  const uInt velWidth, const uInt velPrec
291  );
292 
293  // Show the beam info.
294  static void _beamToStream(
295  ostream& os, const GaussianBeam& beam,
296  const Unit& unit
297  );
298 };
299 
300 // Show the beam set info.
301 ostream &operator<<(ostream &os, const ImageBeamSet& beamSet);
302 
303 }
304 
305 #endif
306 
A Vector of integers, for indexing into Array<T> objects.
Definition: IPosition.h:119
int Int
Definition: aipstype.h:50
GaussianBeam getMinAreaBeam() const
Get the beam in the set which has the smallest area.
Definition: ImageBeamSet.h:215
IPosition getMaxAreaBeamPosition() const
Get the position of the beam with the maximum area.
Definition: ImageBeamSet.h:231
LatticeExprNode log(const LatticeExprNode &expr)
const Matrix< GaussianBeam > & getBeams() const
Get the beam array.
Definition: ImageBeamSet.h:202
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
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.
void rotate(const Quantity &angle, Bool unwrap=False)
Modify the beam set by rotating all beams counterclockwise through the specified angle.
const GaussianBeam & operator()(Int chan, Int stokes) const
Definition: ImageBeamSet.h:174
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)
Show the beam info.
const IPosition & shape() const
Get the shape of the beam array.
Definition: ImageBeamSet.h:152
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)
Show the spectral info.
Array< GaussianBeam >::const_iterator BeamIter
Definition: ImageBeamSet.h:91
A hierarchical collection of named fields of various types.
Definition: Record.h:180
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
Matrix< Double > _areas
Definition: ImageBeamSet.h:279
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:278
uInt nstokes() const
Get the number of stokes in the beam array.
Definition: ImageBeamSet.h:162
const Bool False
Definition: aipstype.h:44
Specify which elements to extract from an n-dimensional array.
Definition: Slicer.h:289
Interconvert pixel and frequency values.
static const String _DEFAULT_AREA_UNIT
Definition: ImageBeamSet.h:276
IPosition getMinAreaBeamPosition() const
Get the position of the beam with the minimum area.
Definition: ImageBeamSet.h:227
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:220
uInt nchan() const
Get the number of channels in the beam array.
Definition: ImageBeamSet.h:157
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:147
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:51
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.