casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
36 
37 namespace 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 
193 template<class T> class Gaussian2DParam : public Function<T>
194 {
195 public:
196  //# Enumerations
198 
199  //# Constructors
200  // Constructs the two dimensional Gaussians. Defaults:
201  // height=1, center=0, width(FWHM)=1, pa=0.
202  // <group>
203  Gaussian2DParam();
204  Gaussian2DParam(const T &height, const Vector<T> &center,
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>
213  Gaussian2DParam(const Gaussian2DParam<T> &other);
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
224  virtual ~Gaussian2DParam();
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>
251  Vector<T> center() const;
252  void setCenter(const Vector<T> &center);
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>
261  Vector<T> width() const;
262  void setWidth(const Vector<T> &width);
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 
278 protected:
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.
292 protected:
293  using Function<T>::param_p;
294 public:
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
T PA() const
Set/get the rotation angle (orientation) of the Gaussian.
FunctionParam< T > param_p
The parameters and masks.
Definition: Function.h:332
LatticeExprNode log(const LatticeExprNode &expr)
T height() const
Get or set the peak height of the Gaussian.
Gaussian2DParam()
Constructs the two dimensional Gaussians.
Parameter handling for 2 dimensional Gaussian class.
virtual const String & name() const
Give name of function.
Vector< T > width() const
Set or get the FWHM of the Gaussian.
void setMinorAxis(const T &width)
Gaussian2DParam< T > & operator=(const Gaussian2DParam< T > &other)
Copy assignment (deep copy)
void setXcenter(const T &cnter)
LatticeExprNode pa(const LatticeExprNode &left, const LatticeExprNode &right)
This function finds 180/pi*atan2(left,right)/2.
Numerical functional interface class.
Definition: GenericL2Fit.h:46
void setMajorAxis(const T &width)
void setWidth(const Vector< T > &width)
LatticeExprNode sqrt(const LatticeExprNode &expr)
Gaussian2DParam(const Gaussian2DParam< W > &other)
void setPA(const T &pa)
void setAxialRatio(const T &axialRatio)
void setHeight(const T &height)
T theXwidth
cached vale of the Xwidth = ratio*theYwidth;
virtual uInt ndim() const
Variable dimensionality.
void setYcenter(const T &cnter)
T theSpa
cached values of the cos and sine of thePA
T flux() const
Get or set the analytical integrated area underneath the Gaussian.
T fwhm2int
Constant to scale halfwidth at 1/e to FWHM.
void setFlux(const T &flux)
String: the storage and methods of handling collections of characters.
Definition: String.h:225
T thePA
cached vale of the PA
Vector< T > center() const
Get or set the center ordinate of the Gaussian.
virtual ~Gaussian2DParam()
Destructor.
void setCenter(const Vector< T > &center)
unsigned int uInt
Definition: aipstype.h:51