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
36namespace casacore {
37
38class SpectralCoordinate;
39
40class 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
89public:
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).
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>
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);
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
283private:
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.
316ostream &operator<<(ostream &os, const ImageBeamSet& beamSet);
317
318}
319
320#endif
321
static const GaussianBeam NULL_BEAM
Definition: GaussianBeam.h:71
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
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.
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 operator!=(const ImageBeamSet &other) const
void setBeams(const Matrix< GaussianBeam > &beams)
Set the beams in this beam set.
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.
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.
ImageBeamSet & operator=(const ImageBeamSet &other)
Assignment can change the shape (copy semantics).
Record toRecord() const
Bool hasMultiBeam() const
Does this beam set contain multiple beams?
Definition: ImageBeamSet.h:143
const GaussianBeam & getBeam(Int chan, Int stokes) const
Get the beam at the specified location.
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
const IPosition & shape() const
Get the shape of the beam array.
Definition: ImageBeamSet.h:152
const GaussianBeam & getMaxAreaBeamForPol(IPosition &pos, uInt stokes) const
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
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 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 Quantum< Matrix< double > > getAreas() const
get all the beam areas in a single quantum matrix.
Matrix< Double > _areas
Definition: ImageBeamSet.h:288
const GaussianBeam & getBeam() const
Get the single global beam.
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 & getMedianAreaBeamForPol(IPosition &pos, uInt stokes) const
ImageBeamSet()
Construct an empty beam set.
Bool hasSingleBeam() const
Definition: ImageBeamSet.h:139
const Matrix< GaussianBeam > & getBeams() const
Get the beam array.
Definition: ImageBeamSet.h:202
IPosition getMaxAreaBeamPosition() const
Get the position of the beam with the maximum area.
Definition: ImageBeamSet.h:231
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.
const GaussianBeam & operator()(Int chan, Int stokes) const
Definition: ImageBeamSet.h:174
static const String & className()
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
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
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