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 
39 namespace 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 
177 template<class T> class Gaussian2D : public Gaussian2DParam<T>
178 {
179 public:
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>
190  Gaussian2D(const T &height, const Vector<T> &center,
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.
231 protected:
237 public:
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>
256 
257 template <class T> class Gaussian2D_PS<AutoDiff<T> > :
258 public Gaussian2DParam<AutoDiff<T> >
259 {
260 public:
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 {
308  return new Gaussian2D<typename FunctionTraits<AutoDiff<T> >::DiffType>
309  (*this); }
311  *cloneNonAD() const {
312  return new Gaussian2D<typename FunctionTraits<AutoDiff<T> >::BaseType>
313  (*this); }
314  // </group>
315 
316  //# Make members of parent classes known.
317 protected:
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;
323 public:
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
const ArgType * FunctionArg
Definition: Function.h:207
T height() const
Get or set the peak height of the Gaussian.
Gaussian2DParam< T > & operator=(const Gaussian2DParam< T > &other)
Copy assignment (deep copy)
Vector< T > width() const
Set or get the FWHM of the Gaussian.
Vector< T > center() const
Get or set the center ordinate of the Gaussian.
Gaussian2D_PS(const AutoDiff< T > &height, const Vector< AutoDiff< T > > &center, const Vector< AutoDiff< T > > &width, const AutoDiff< T > &pa)
Definition: Gaussian2D.h:264
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
virtual Function< typename FunctionTraits< T >::DiffType > * cloneAD() const
Definition: Gaussian2D.h:224
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
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.
virtual Function< T > * clone() const
Return a copy of this object from the heap.
Definition: Gaussian2D.h:223
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)