casacore
Loading...
Searching...
No Matches
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.
229
230 // Get the position of the beam with the maximum area.
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
Matrix< GaussianBeam > _beams
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
uInt nstokes() const
Get the number of stokes in the beam array.
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.
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?
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.
const IPosition & shape() const
Get the shape of the beam array.
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.
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.
static ImageBeamSet fromRecord(const Record &rec)
convert ImageBeamSet to and from record
Bool empty() const
Is the beam set empty?
const Quantum< Matrix< double > > getAreas() const
get all the beam areas in a single quantum matrix.
Matrix< Double > _areas
const GaussianBeam & getBeam() const
Get the single global beam.
uInt nchan() const
Get the number of channels in the beam array.
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
const Matrix< GaussianBeam > & getBeams() const
Get the beam array.
IPosition getMaxAreaBeamPosition() const
Get the position of the beam with the maximum area.
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
static const String & className()
static const String _DEFAULT_AREA_UNIT
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
int Int
Definition aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42