casacore
Gaussian2DParam.h
Go to the documentation of this file.
1//# Gaussian2DParam.h: Parameter handling for 2 dimensional Gaussian class
2//# Copyright (C) 2001,2002,2003
3//# Associated Universities, Inc. Washington DC, USA.
4//#
5//# This library is free software; you can redistribute it and/or modify it
6//# under the terms of the GNU Library General Public License as published by
7//# the Free Software Foundation; either version 2 of the License, or (at your
8//# option) any later version.
9//#
10//# This library is distributed in the hope that it will be useful, but WITHOUT
11//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13//# License for more details.
14//#
15//# You should have received a copy of the GNU Library General Public License
16//# along with this library; if not, write to the Free Software Foundation,
17//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18//#
19//# Correspondence concerning AIPS++ should be addressed as follows:
20//# Internet email: aips2-request@nrao.edu.
21//# Postal address: AIPS++ Project Office
22//# National Radio Astronomy Observatory
23//# 520 Edgemont Road
24//# Charlottesville, VA 22903-2475 USA
25//#
26//#
27//# $Id$
28
29#ifndef SCIMATH_GAUSSIAN2DPARAM_H
30#define SCIMATH_GAUSSIAN2DPARAM_H
31
32#include <casacore/casa/aips.h>
33#include <casacore/casa/Arrays/ArrayFwd.h>
34#include <casacore/scimath/Functionals/Function.h>
35#include <casacore/casa/BasicSL/String.h>
36
37namespace casacore { //# NAMESPACE CASACORE - BEGIN
38
39// <summary> Parameter handling for 2 dimensional Gaussian class
40// </summary>
41
42// <use visibility=local>
43
44// <reviewed reviewer="mwieringa" date="1996/10/d24" tests="tGaussian2D">
45// </reviewed>
46
47// <prerequisite>
48// <li> <linkto class="FunctionParam">FunctionParam</linkto> class
49// <li> <linkto class="Function">Function</linkto> class
50// </prerequisite>
51
52// <etymology>
53// A 2-dimensional Gaussian's parameters.
54// </etymology>
55
56// <synopsis>
57
58// A <src>Gaussian2D</src> is described by a height, center, and width,
59// and position angle.
60
61// The width of the Gaussian (for the constructors or the <src> setWidth
62// </src> function) is always specified in terms of the full width at half
63// maximum (FWHM). The major axis is parallel with the y axis when the
64// position angle is zero. The major axis will always have a larger width
65// than the minor axis.
66//
67// It is not possible to set the width of the major axis (using the <src>
68// setMajorAxis </src> function) smaller than the width of the current minor
69// axis. Similarly it is not possible to set the width of the minor axis
70// (using the <src> setMinorAxis </src> function) to be larger than the
71// current major axis. Exceptions are thrown if these rules are violated or
72// if either the major or minor axis is set to a non-positive width. To
73// set both axis in one hit use the <src> setWidth </src> function. All
74// these restrictions can be overcome when the parameters interface is used
75// (see below).
76//
77// The position angle is the angle between the y axis and the major axis and
78// is measured counter-clockwise, so a position angle of 45 degrees rotates
79// the major axis to the line where <src>y=-x</src>.
80// The position angle is always
81// specified and returned in radians. When using the <src> setPA </src>
82// function its value must be between -2pi and + 2pi, and the returned value
83// from the <src> pa </src> function will always be a value between 0 and
84// pi.
85//
86// The axial ratio can be used as an alternative to specifying the width of
87// the minor axis. It is the ratio between the minor and major axis
88// widths. The axial ratio is constrained to be between zero and one, and
89// specifying something different (using setAxialRatio) will throw an
90// exception.
91//
92// The peak height of the Gaussian can be specified at construction time or
93// by using the <src> setHeight </src> function. Alternatively the <src>
94// setFlux </src> function can be used to implicitly set the peak height by
95// specifying the integrated area under the Gaussian. The height (or flux)
96// can be positive, negative or zero, as this class makes no assumptions on
97// what quantity the height represents.
98//
99// <note role=tip> Changing the width of the Gaussian will not affect
100// its peak height but will change its flux. So you should always set the
101// width before setting the flux. </note>
102//
103// The parameter interface (see
104// <linkto class="FunctionParam">FunctionParam</linkto> class),
105// is used to provide an interface to the
106// <linkto module="Fitting"> Fitting </linkto> classes.
107//
108// There are 6 parameters that are used to describe the Gaussian:
109// <ol>
110// <li> The height of the Gaussian. This is identical to the value
111// returned using the <src> height </src> member function.
112// <li> The center of the Gaussian in the x direction. This is identical to
113// the value returned using the <src> xCenter </src> member function.
114// <li> The center of the Gaussian in the y direction. This is identical to
115// the value returned using the <src> yCenter </src> member function.
116// <li> The width (FWHM) of the Gaussian on one axis. Initially this will be
117// the major axis, but if the parameters are adjusted by a Fitting
118// class, it may become the axis with the smaller width. To aid
119// convergence of the non-linear fitting routines this parameter is
120// allowed to be negative. This does not affect the shape of the
121// Gaussian as the squares of the widths are used when evaluating the
122// function.
123// <li> A modified axial ratio. This parameter is the ratio of the width on
124// the 'other' axis (which initially is the minor axis) and axis given
125// by parameter 4. Because these internal widths are allowed to be
126// negative and because there is no constraints on which axis is the
127// larger one the modified axial ratio is not constrained to be between
128// zero and one.
129// <li> The rotation angle. This represents the angle (in radians) between
130// the axis used by parameter 4, and the y axis, measured
131// counterclockwise. If parameter 4 represents the major axis width
132// then this parameter will be identical to the position angle,
133// otherwise it will be different by 90 degrees. The tight constraints
134// on the value of the rotation angle enforced by the setPA() function
135// are relaxed so that any value between -6000 and 6000 is allowed. It
136// is still interpreted in radians.
137// </ol>
138//
139// An enumeration for the <src>HEIGHT</src>, <src>XCENTER</src>,
140// <src>YCENTER</src>, <src>YWIDTH</src>, <src>RATIO</src>, <src>PANGLE</src>
141// parameter index is provided, enabling the setting
142// and reading of parameters with the <src>[]</src> operator. The
143// <src>mask()</src> methods can be used to check and set the parameter masks.
144//
145// This class is in general used implicitly by the <src>Gaussian2D</src>
146// class only.
147//
148// <note role=tip>
149// Other points to bear in mind when fitting this class to measured data
150// are:
151// <ul>
152// <li> If you need to fit a circular Gaussian to data you MUST set the
153// axial ratio to one, and mask the position angle and axial ratio
154// parameters. This avoids rank deficiency in the fitting routines as
155// the position angle is meaningless when the major and minor axis are
156// equal.
157// <li> If fitting an elliptical Gaussian your initial model should not be a
158// circular Gaussian.
159// </ul>
160// </note>
161//
162// </synopsis>
163
164// <example>
165// <srcblock>
166// Gaussian2D<Double> g(10.0, 0.0, 0.0, 2.0, 1.0, 0.0);
167// Vector<Double> x(2);
168// x(0) = 1.0; x(1) = 0.5;
169// cout << "g(" << x(0) << "," << x(1) << ") = " << g(x) << endl;
170// </srcblock>
171// </example>
172
173// <motivation>
174// Gaussian2D objects allow us to represent models of
175// the sky in a more conventional way than the generic interface used in the
176// GaussianND class does.
177// </motivation>
178
179// <templating arg=T>
180// <li> T should have standard numerical operators and exp() function. Current
181// implementation only tested for real types (and AutoDiff of them).
182// </templating>
183
184// <thrown>
185// <li> Assertion in debug mode if attempt is made to set a negative width
186// <li> AipsError if incorrect parameter number specified.
187// </thrown>
188
189// <todo asof="2001/08/19">
190// <li> Gaussians that know about their DFT's could be required eventually.
191// </todo>
192
193template<class T> class Gaussian2DParam : public Function<T>
194{
195public:
196 //# Enumerations
198
199 //# Constructors
200 // Constructs the two dimensional Gaussians. Defaults:
201 // height=1, center=0, width(FWHM)=1, pa=0.
202 // <group>
205 const Vector<T> &width, const T &pa);
206 Gaussian2DParam(const T &height, const T &xCenter, const T &yCenter,
207 const T &majorAxis, const T &axialRatio,
208 const T &pa);
209 // </group>
210
211 // Copy constructor (deep copy)
212 // <group>
214 template <class W>
216 Function<T>(other),
217 fwhm2int(T(1.0)/sqrt(log(T(16.0)))) { majorAxis(); setPA(PA()); }
218 // </group>
219
220 // Copy assignment (deep copy)
222
223 // Destructor
225
226 //# Operators
227
228 // Variable dimensionality
229 virtual uInt ndim() const { return 2; }
230
231 //# Member functions
232 // Give name of function
233 virtual const String &name() const { static String x("gaussian2d");
234 return x; }
235
236 // Get or set the peak height of the Gaussian
237 // <group>
238 T height() const { return param_p[HEIGHT]; }
239 void setHeight(const T &height) { param_p[HEIGHT] = height; }
240 // </group>
241
242 // Get or set the analytical integrated area underneath the Gaussian.
243 // Use these functions as an alternative to the height functions.
244 // <group>
245 T flux() const;
246 void setFlux(const T &flux);
247 // </group>
248
249 // Get or set the center ordinate of the Gaussian
250 // <group>
253 T xCenter() const { return param_p[XCENTER]; }
254 void setXcenter(const T &cnter) { param_p[XCENTER] = cnter; }
255 T yCenter() const { return param_p[YCENTER]; }
256 void setYcenter(const T &cnter) { param_p[YCENTER] = cnter; }
257 // </group>
258
259 // Set or get the FWHM of the Gaussian.
260 // <group>
263 T majorAxis() const;
264 void setMajorAxis(const T &width);
265 T minorAxis() const;
266 void setMinorAxis(const T &width);
267 T axialRatio() const;
268 void setAxialRatio(const T &axialRatio);
269 // </group>
270
271 // Set/get the rotation angle (orientation) of the Gaussian. PA is given
272 // in radians counterclockwise.
273 // <group>
274 T PA() const;
275 void setPA(const T &pa);
276 // </group>
277
278protected:
279 // Constant to scale halfwidth at 1/e to FWHM
281 // cached vale of the PA
282 mutable T thePA;
283 // cached values of the cos and sine of thePA
284 // <group>
285 mutable T theSpa;
286 mutable T theCpa;
287 // </group>
288 // cached vale of the Xwidth = ratio*theYwidth;
289 mutable T theXwidth;
290
291 //# Make members of parent classes known.
292protected:
293 using Function<T>::param_p;
294public:
295 using Function<T>::nparameters;
296};
297
298
299} //# NAMESPACE CASACORE - END
300
301#ifndef CASACORE_NO_AUTO_TEMPLATES
302#include <casacore/scimath/Functionals/Gaussian2DParam.tcc>
303#endif //# CASACORE_NO_AUTO_TEMPLATES
304#endif
FunctionParam< T > param_p
The parameters and masks.
Definition: Function.h:332
uInt nparameters() const
Returns the number of parameters.
Definition: Function.h:230
T theXwidth
cached vale of the Xwidth = ratio*theYwidth;
T height() const
Get or set the peak height of the Gaussian.
Gaussian2DParam(const Gaussian2DParam< W > &other)
virtual const String & name() const
Give name of function.
T thePA
cached vale of the PA
void setCenter(const Vector< T > &center)
Vector< T > center() const
Get or set the center ordinate of the Gaussian.
virtual ~Gaussian2DParam()
Destructor.
Gaussian2DParam(const T &height, const T &xCenter, const T &yCenter, const T &majorAxis, const T &axialRatio, const T &pa)
Vector< T > width() const
Set or get the FWHM of the Gaussian.
T fwhm2int
Constant to scale halfwidth at 1/e to FWHM.
T PA() const
Set/get the rotation angle (orientation) of the Gaussian.
void setPA(const T &pa)
Gaussian2DParam(const Gaussian2DParam< T > &other)
Copy constructor (deep copy)
Gaussian2DParam()
Constructs the two dimensional Gaussians.
T theSpa
cached values of the cos and sine of thePA
void setMinorAxis(const T &width)
void setFlux(const T &flux)
void setYcenter(const T &cnter)
void setHeight(const T &height)
virtual uInt ndim() const
Variable dimensionality.
void setMajorAxis(const T &width)
void setAxialRatio(const T &axialRatio)
void setWidth(const Vector< T > &width)
Gaussian2DParam< T > & operator=(const Gaussian2DParam< T > &other)
Copy assignment (deep copy)
void setXcenter(const T &cnter)
T flux() const
Get or set the analytical integrated area underneath the Gaussian.
Gaussian2DParam(const T &height, const Vector< T > &center, const Vector< T > &width, const T &pa)
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
LatticeExprNode pa(const LatticeExprNode &left, const LatticeExprNode &right)
This function finds 180/pi*atan2(left,right)/2.
unsigned int uInt
Definition: aipstype.h:51
LatticeExprNode sqrt(const LatticeExprNode &expr)
LatticeExprNode log(const LatticeExprNode &expr)