casacore
Gaussian2D.h
Go to the documentation of this file.
1//# Gaussian2D.h: A two-dimensional Gaussian class
2//# Copyright (C) 1995,1996,1997,2001,2002,2005
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//# $Id$
27
28#ifndef SCIMATH_GAUSSIAN2D_H
29#define SCIMATH_GAUSSIAN2D_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/casa/Arrays/ArrayFwd.h>
34#include <casacore/scimath/Functionals/Gaussian2DParam.h>
35#include <casacore/scimath/Functionals/Function.h>
36#include <casacore/scimath/Mathematics/AutoDiff.h>
37#include <casacore/scimath/Mathematics/AutoDiffMath.h>
38
39namespace casacore { //# NAMESPACE CASACORE - BEGIN
40
41// <summary> A two dimensional Gaussian class.</summary>
42
43// <use visibility=export>
44
45// <reviewed reviewer="tcornwel" date="1996/02/22" tests="tGaussian2D"
46// demos="">
47// </reviewed>
48
49// <prerequisite>
50// <li> <linkto class="Gaussian2DParam">Gaussian2DParam</linkto>
51// <li> <linkto class="Function">Function</linkto>
52// </prerequisite>
53
54// <etymology>
55// A Gaussian2D functional is designed exclusively for calculating a
56// Gaussian (or Normal) distribution in two dimensions. Other classes exist
57// for calculating these functions in two
58// (<linkto class=Gaussian1D>Gaussian1D</linkto>) and N
59// (<linkto class=GaussianND>GaussianND</linkto>) dimensions.
60// </etymology>
61
62// <synopsis>
63// A <src>Gaussian2D</src> is described by a height, center, and width,
64// and position angle. Its fundamental operation is evaluating itself
65// at some <src>(x,y)</src>
66// coordinate. Its parameters (height, center and width, position angle) may
67// be changed at run time.
68//
69// The width of the Gaussian (for the constructors or the <src> setWidth
70// </src> function) is always specified in terms of the full width at half
71// maximum (FWHM). The major axis is parallel with the y axis when the
72// position angle is zero. The major axis will always have a larger width
73// than the minor axis.
74//
75// It is not possible to set the width of the major axis (using the <src>
76// setMajorAxis </src> function) smaller than the width of the current minor
77// axis. Similarly it is not possible to set the width of the minor axis
78// (using the <src> setMinorAxis </src> function) to be larger than the
79// current major axis. Exceptions are thrown if these rules are violated or
80// if the either the major or minor axis is set to a non-positive width. To
81// set both axis in one hit use the <src> setWidth </src> function. All
82// these restrictions can be overcome when the parameters interface is used
83// (see below).
84//
85// The position angle is the angle between the y axis and the major axis and
86// is measured counterclockwise, so a position angle of 45 degrees rotates
87// the major axis to the line where y=-x. The position angle is always
88// specified and returned in radians. When using the <src> setPA </src>
89// function its value must be between -2pi and + 2pi, and the returned value
90// from the <src> pa </src> function will always be a value between 0 and
91// pi.
92//
93// The axial ratio can be used as an alternative to specifying the width of
94// the minor axis. It is the ratio between the minor and major axis
95// widths. The axial ratio is constrained to be between zero and one, and
96// specifying something different (using setAxialRatio) will throw an
97// exception.
98//
99// The peak height of the Gaussian can be specified at construction time or
100// by using the <src> setHeight </src> function. Alternatively the <src>
101// setFlux </src> function can be used to implicitly set the peak height by
102// specifying the integrated area under the Gaussian. The height (or flux)
103// can be positive, negative or zero, as this class makes no assumptions on
104// what quantity the height represents.
105//
106// <note role=tip> Changing the width of the Gaussian will not affect
107// its peak height but will change its flux. So you should always set the
108// width before setting the flux. </note>
109//
110// The parameter interface (see
111// <linkto class="Gaussian2DParam">Gaussian2DParam</linkto> class),
112// is used to provide an interface to the
113// <linkto module="Fitting">Fitting</linkto> classes.
114//
115// There are 6 parameters that are used to describe the Gaussian:
116// <ol>
117// <li> The height of the Gaussian. This is identical to the value
118// returned using the <src> height </src> member function.
119// <li> The center of the Gaussian in the x direction. This is identical to
120// the value returned using the <src> xCenter </src> member function.
121// <li> The center of the Gaussian in the y direction. This is identical to
122// the value returned using the <src> yCenter </src> member function.
123// <li> The width (FWHM) of the Gaussian on one axis. Initially this will be
124// the major axis, but if the parameters are adjusted by a Fitting
125// class, it may become the axis with the smaller width. To aid
126// convergence of the non-linear fitting routines this parameter is
127// allowed to be negative. This does not affect the shape of the
128// Gaussian as the squares of the widths are used when evaluating the
129// function.
130// <li> A modified axial ratio. This parameter is the ratio of the width on
131// the 'other' axis (which initially is the minor axis) and axis given
132// by parameter YWIDTH. Because these internal widths are allowed to be
133// negative and because there is no constraints on which axis is the
134// larger one the modified axial ratio is not constrained to be between
135// zero and one.
136// <li> The position angle. This represents the angle (in radians) between
137// the axis used by parameter 4, and the y axis, measured
138// counterclockwise. If parameter 4 represents the major axis width
139// then this parameter will be identical to the position angle,
140// otherwise it will be different by 90 degrees. The tight constraints
141// on the value of the rotation angle enforced by the setPA() function
142// are relaxed so that any value between -6000 and 6000 is allowed. It
143// is still interpreted in radians.
144// </ol>
145//
146// An enumeration for the parameter index is provided, enabling the setting
147// and reading of parameters with the <src>[]</src> operator. The
148// <src>mask()</src> methods can be used to check and set the parameter masks.
149//
150// </synopsis>
151
152// <example>
153// <srcblock>
154// Gaussian2D<Double> g(10.0, 0.0, 0.0, 2.0, 1.0, 0.0);
155// Vector<Double> x(2);
156// x(0) = 1.0; x(1) = 0.5;
157// cout << "g(" << x(0) << "," << x(1) << ") = " << g(x) << endl;
158// </srcblock>
159// </example>
160
161// <templating arg=T>
162// <li> T should have standard numerical operators and exp() function. Current
163// implementation only tested for real types.
164// <li> To obtain derivatives, the derivatives should be defined.
165// </templating>
166
167// <thrown>
168// <li> Assertion in debug mode if attempt is made to set a negative width
169// <li> AipsError if incorrect parameter number specified.
170// <li> Assertion in debug mode if operator(Vector<>) with empty Vector
171// </thrown>
172
173// <todo asof="2001/08/19">
174// <li> Gaussians that know about their DFT's could be required eventually.
175// </todo>
176
177template<class T> class Gaussian2D : public Gaussian2DParam<T>
178{
179public:
180 //# Enumerations
181
182 //# Constructors
183 // Constructs the two dimensional Gaussians. Defaults:
184 // height=1, center=0, width(FWHM)=1, PA=0. The center and width vectors
185 // must have two elements
186 // <note role=warning> Could not use default arguments
187 // that worked both with gcc and IRIX </note>
188 // <group>
191 const Vector<T> &width, const T &pa) :
193 Gaussian2D(const T &height, const T &xCenter, const T &yCenter,
194 const T &majorAxis, const T &axialRatio, const T &pa) :
196 axialRatio, pa) {}
197 // </group>
198
199 // Copy constructor (deep copy)
200 // <group>
201 Gaussian2D(const Gaussian2D<T> &other) : Gaussian2DParam<T>(other) {}
202 template <class W>
203 Gaussian2D(const Gaussian2D<W> &other) : Gaussian2DParam<T>(other) {}
204 // </group>
205
206 // Copy assignment (deep copy)
208 Gaussian2DParam<T>::operator=(other); return *this; }
209
210 // Destructor
211 virtual ~Gaussian2D() {}
212
213 //# Operators
214 // Evaluate the Gaussian at <src>x</src>.
215 // <group>
216 virtual T eval(typename Function<T>::FunctionArg x) const;
217 // </group>
218
219 //# Member functions
220 // Return a copy of this object from the heap. The caller is responsible
221 // for deleting this pointer.
222 // <group>
223 virtual Function<T> *clone() const { return new Gaussian2D<T>(*this); }
228 // </group>
229
230 //# Make members of parent classes known.
231protected:
233 using Gaussian2DParam<T>::thePA;
237public:
242 using Gaussian2DParam<T>::RATIO;
245};
246
247#define Gaussian2D_PS Gaussian2D
248
249// <summary> Partial specialization of Gaussian2D for <src>AutoDiff</src>
250// </summary>
251
252// <synopsis>
253// <note role=warning> The name <src>Gaussian2D_PS</src> is only for cxx2html
254// documentation problems. Use <src>Gaussian2D</src> in your code.</note>
255// </synopsis>
257template <class T> class Gaussian2D_PS<AutoDiff<T> > :
258public Gaussian2DParam<AutoDiff<T> >
259{
260public:
261 //# Constructors
262 // Constructs two dimensional Gaussians.
263 // <group>
265 Gaussian2D_PS(const AutoDiff<T> &height,
266 const Vector<AutoDiff<T> > &center,
267 const Vector<AutoDiff<T> > &width,
268 const AutoDiff<T> &pa) :
269 Gaussian2DParam<AutoDiff<T> >(height, center, width, pa) {}
270 Gaussian2D_PS(const AutoDiff<T> &height, const AutoDiff<T> &xCenter,
271 const AutoDiff<T> &yCenter, const AutoDiff<T> &majorAxis,
272 const AutoDiff<T> &axialRatio, const AutoDiff<T> &pa) :
273 Gaussian2DParam<AutoDiff<T> >(height, xCenter, yCenter, majorAxis,
274 axialRatio, pa) {}
275 // </group>
276
277 // Copy constructor (deep copy)
278 // <group>
279 Gaussian2D_PS(const Gaussian2D_PS &other) :
280 Gaussian2DParam<AutoDiff<T> >(other) {}
281 template <class W>
282 Gaussian2D_PS(const Gaussian2D_PS<W> &other) :
283 Gaussian2DParam<AutoDiff<T> >(other) {}
284 // </group>
285
286 // Copy assignment (deep copy)
287 Gaussian2D_PS<AutoDiff<T> > &
288 operator=(const Gaussian2D_PS<AutoDiff<T> > &other) {
289 Gaussian2DParam<AutoDiff<T> >::operator=(other); return *this; }
290
291 // Destructor
292 virtual ~Gaussian2D_PS() {}
293
294 //# Operators
295 // Evaluate the Gaussian and its derivatives at <src>x</src>.
296 // <group>
297 virtual AutoDiff<T> eval(typename Function<AutoDiff<T> >::FunctionArg x) const;
298 // </group>
299
300 //# Member functions
301 // Return a copy of this object from the heap. The caller is responsible
302 // for deleting this pointer.
303 // <group>
304 virtual Function<AutoDiff<T> > *clone() const {
305 return new Gaussian2D<AutoDiff<T> >(*this); }
307 *cloneAD() const {
309 (*this); }
311 *cloneNonAD() const {
313 (*this); }
314 // </group>
315
316 //# Make members of parent classes known.
317protected:
318 using Gaussian2DParam<AutoDiff<T> >::param_p;
319 using Gaussian2DParam<AutoDiff<T> >::thePA;
320 using Gaussian2DParam<AutoDiff<T> >::theCpa;
321 using Gaussian2DParam<AutoDiff<T> >::theSpa;
322 using Gaussian2DParam<AutoDiff<T> >::theXwidth;
323public:
324 using Gaussian2DParam<AutoDiff<T> >::HEIGHT;
325 using Gaussian2DParam<AutoDiff<T> >::XCENTER;
326 using Gaussian2DParam<AutoDiff<T> >::YCENTER;
327 using Gaussian2DParam<AutoDiff<T> >::YWIDTH;
328 using Gaussian2DParam<AutoDiff<T> >::RATIO;
329 using Gaussian2DParam<AutoDiff<T> >::PANGLE;
330 using Gaussian2DParam<AutoDiff<T> >::fwhm2int;
331};
332
333#undef Gaussian2D_PS
334
335
336} //# NAMESPACE CASACORE - END
337
338#ifndef CASACORE_NO_AUTO_TEMPLATES
339#include <casacore/scimath/Functionals/Gaussian2D.tcc>
340#include <casacore/scimath/Functionals/Gaussian2D2.tcc>
341#endif //# CASACORE_NO_AUTO_TEMPLATES
342#endif
#define Gaussian2D_PS
Definition: Gaussian2D.h:247
FunctionParam< T > param_p
The parameters and masks.
Definition: Function.h:332
T theXwidth
cached vale of the Xwidth = ratio*theYwidth;
T height() const
Get or set the peak height of the Gaussian.
T thePA
cached vale of the PA
Vector< T > center() const
Get or set the center ordinate of the Gaussian.
Vector< T > width() const
Set or get the FWHM of the Gaussian.
T fwhm2int
Constant to scale halfwidth at 1/e to FWHM.
T theSpa
cached values of the cos and sine of thePA
Gaussian2DParam< T > & operator=(const Gaussian2DParam< T > &other)
Copy assignment (deep copy)
virtual Function< typename FunctionTraits< AutoDiff< T > >::BaseType > * cloneNonAD() const
Definition: Gaussian2D.h:310
Gaussian2D_PS()
Constructs two dimensional Gaussians.
Definition: Gaussian2D.h:263
Gaussian2D_PS< AutoDiff< T > > & operator=(const Gaussian2D_PS< AutoDiff< T > > &other)
Copy assignment (deep copy)
Definition: Gaussian2D.h:287
Gaussian2D_PS(const AutoDiff< T > &height, const Vector< AutoDiff< T > > &center, const Vector< AutoDiff< T > > &width, const AutoDiff< T > &pa)
Definition: Gaussian2D.h:264
Gaussian2D_PS(const AutoDiff< T > &height, const AutoDiff< T > &xCenter, const AutoDiff< T > &yCenter, const AutoDiff< T > &majorAxis, const AutoDiff< T > &axialRatio, const AutoDiff< T > &pa)
Definition: Gaussian2D.h:269
Gaussian2D_PS(const Gaussian2D_PS &other)
Copy constructor (deep copy)
Definition: Gaussian2D.h:278
Gaussian2D_PS(const Gaussian2D_PS< W > &other)
Definition: Gaussian2D.h:281
virtual Function< typename FunctionTraits< AutoDiff< T > >::DiffType > * cloneAD() const
Definition: Gaussian2D.h:306
virtual Function< AutoDiff< T > > * clone() const
Return a copy of this object from the heap.
Definition: Gaussian2D.h:303
virtual AutoDiff< T > eval(typename Function< AutoDiff< T > >::FunctionArg x) const
Evaluate the Gaussian and its derivatives at x.
virtual Function< typename FunctionTraits< T >::DiffType > * cloneAD() const
Definition: Gaussian2D.h:224
virtual ~Gaussian2D()
Destructor.
Definition: Gaussian2D.h:211
Gaussian2D(const T &height, const T &xCenter, const T &yCenter, const T &majorAxis, const T &axialRatio, const T &pa)
Definition: Gaussian2D.h:193
Gaussian2D()
Constructs the two dimensional Gaussians.
Definition: Gaussian2D.h:189
Gaussian2D< T > & operator=(const Gaussian2D< T > &other)
Copy assignment (deep copy)
Definition: Gaussian2D.h:207
virtual Function< typename FunctionTraits< T >::BaseType > * cloneNonAD() const
Definition: Gaussian2D.h:226
Gaussian2D(const Gaussian2D< W > &other)
Definition: Gaussian2D.h:203
virtual Function< T > * clone() const
Return a copy of this object from the heap.
Definition: Gaussian2D.h:223
Gaussian2D(const T &height, const Vector< T > &center, const Vector< T > &width, const T &pa)
Definition: Gaussian2D.h:190
Gaussian2D(const Gaussian2D< T > &other)
Copy constructor (deep copy)
Definition: Gaussian2D.h:201
virtual T eval(typename Function< T >::FunctionArg x) const
Evaluate the Gaussian at x.
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.
PtrHolder< T > & operator=(const PtrHolder< T > &other)