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.
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.
102  const Matrix<GaussianBeam>& beams
103  );
104 
105  // construct an ImageBeamSet representing a single beam which is valid for
106  // all channels and stokes
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 
117 
118  // Assignment can change the shape (copy semantics).
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.
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  // get all the beam areas in a single quantum matrix.
276 
277  // get all the major axes, minor axes, and pas in quantum matrices.
278  // The returned map has keys "major", "minor", and "pa".
279  const std::map<String, Quantum<Matrix<double>>> paramMatrices(
280  const Unit& majminUnit=Unit("arcsec"), const Unit& paUnit="deg"
281  ) const;
282 
283 private:
284 
286 
292 
294 
295  // common code for replacing a beam in a multi-beam set
297  const GaussianBeam& beam, const IPosition& location1,
298  const IPosition& location2, Bool overwriteMaxMin
299  );
300 
301  // Show the spectral info.
302  static void _chanInfoToStream(
303  ostream& os, const SpectralCoordinate *spCoord,
304  const uInt chan, const uInt chanWidth, const uInt freqPrec,
305  const uInt velWidth, const uInt velPrec
306  );
307 
308  // Show the beam info.
309  static void _beamToStream(
310  ostream& os, const GaussianBeam& beam,
311  const Unit& unit
312  );
313 };
314 
315 // Show the beam set info.
316 ostream &operator<<(ostream &os, const ImageBeamSet& beamSet);
317 
318 }
319 
320 #endif
321 
static const GaussianBeam NULL_BEAM
Definition: GaussianBeam.h:71
ImageBeamSet & operator=(const ImageBeamSet &other)
Assignment can change the shape (copy semantics).
Matrix< GaussianBeam > _beams
Definition: ImageBeamSet.h:287
void summarize(LogIO &log, Bool verbose, const CoordinateSystem &csys) const
If verbose, log all beams, if not just summarize beam stats.
void rotate(const Quantity &angle, Bool unwrap=False)
Modify the beam set by rotating all beams counterclockwise through the specified angle.
Array< GaussianBeam >::const_iterator BeamIter
Definition: ImageBeamSet.h:91
const IPosition & shape() const
Get the shape of the beam array.
Definition: ImageBeamSet.h:152
uInt nstokes() const
Get the number of stokes in the beam array.
Definition: ImageBeamSet.h:162
void setBeam(Int chan, Int stokes, const GaussianBeam &beam)
Get a beam at the given 2-dim IPosition.
const std::map< String, Quantum< Matrix< double > > > paramMatrices(const Unit &majminUnit=Unit("arcsec"), const Unit &paUnit="deg") const
get all the major axes, minor axes, and pas in quantum matrices.
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.
const Quantum< Matrix< double > > getAreas() const
get all the beam areas in a single quantum matrix.
const GaussianBeam & getMaxAreaBeamForPol(IPosition &pos, uInt stokes) const
const GaussianBeam & getBeam() const
Get the single global beam.
Bool operator!=(const ImageBeamSet &other) const
void setBeams(const Matrix< GaussianBeam > &beams)
Set the beams in this beam set.
Bool equivalent(const ImageBeamSet &that) const
Beam sets are equivalent if both have no beams or if the expanded sets are equal.
ImageBeamSet(uInt nchan, uInt nstokes, const GaussianBeam &beam=GaussianBeam::NULL_BEAM)
Create an ImageBeamSet of the specified shape with all GaussianBeams initialized to beam.
Record toRecord() const
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.
ImageBeamSet(const GaussianBeam &beam)
construct an ImageBeamSet representing a single beam which is valid for all channels and stokes
ImageBeamSet(const ImageBeamSet &other)
The copy constructor (reference semantics).
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.
ImageBeamSet subset(const Slicer &imageSlicer, const CoordinateSystem &csys) const
Return a subset of the beam array.
uInt nelements() const
Get the number of elements in the beam array.
Definition: ImageBeamSet.h:133
void set(const GaussianBeam &beam)
Set all beams to the same value.
GaussianBeam getMinAreaBeam() const
Get the beam in the set which has the smallest area.
Definition: ImageBeamSet.h:215
Bool operator==(const ImageBeamSet &other) const
Beam sets are equal if the shapes and all corresponding beams are equal.
GaussianBeam getMaxAreaBeam() const
Get the beam in the set which has the largest area.
Definition: ImageBeamSet.h:220
static ImageBeamSet fromRecord(const Record &rec)
convert ImageBeamSet to and from record
Bool empty() const
Is the beam set empty?
Definition: ImageBeamSet.h:147
const GaussianBeam & getBeam(Int chan, Int stokes) const
Get the beam at the specified location.
const GaussianBeam & getMedianAreaBeamForPol(IPosition &pos, uInt stokes) const
Matrix< Double > _areas
Definition: ImageBeamSet.h:288
uInt nchan() const
Get the number of channels in the beam array.
Definition: ImageBeamSet.h:157
ImageBeamSet(const Matrix< GaussianBeam > &beams)
Construct a beam set from an 2-D array of beams representing the frequency and stokes axis.
const GaussianBeam & operator()(Int chan, Int stokes) const
Definition: ImageBeamSet.h:174
ImageBeamSet()
Construct an empty beam set.
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...
Bool hasSingleBeam() const
Definition: ImageBeamSet.h:139
static const String & className()
IPosition getMaxAreaBeamPosition() const
Get the position of the beam with the maximum area.
Definition: ImageBeamSet.h:231
const Matrix< GaussianBeam > & getBeams() const
Get the beam array.
Definition: ImageBeamSet.h:202
void _replaceBeam(const GaussianBeam &beam, const IPosition &location1, const IPosition &location2, Bool overwriteMaxMin)
common code for replacing a beam in a multi-beam set
const GaussianBeam getSmallestMinorAxisBeam() const
Get the beam that has the smallest minor axis.
void resize(uInt nchan, uInt nstokes)
Resize the beam array.
static const String _DEFAULT_AREA_UNIT
Definition: ImageBeamSet.h:285
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
const Bool False
Definition: aipstype.h:44
unsigned int uInt
Definition: aipstype.h:51
LatticeExprNode log(const LatticeExprNode &expr)
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.