casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
GaussianShape.h
Go to the documentation of this file.
1 //# GaussianShape.h:
2 //# Copyright (C) 1998,1999,2000,2001,2002
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: GaussianShape.h 21130 2011-10-18 07:39:05Z gervandiepen $
28 
29 #ifndef COMPONENTS_GAUSSIANSHAPE_H
30 #define COMPONENTS_GAUSSIANSHAPE_H
31 
32 #include <casa/aips.h>
34 #include <casa/BasicSL/Complex.h>
37 
38 namespace casacore{
39 
40 class MDirection;
41 class MVAngle;
42 template <class Qtype> class Quantum;
43 template <class T> class Matrix;
44 template <class T> class Vector;
45 }
46 
47 namespace casa { //# NAMESPACE CASA - BEGIN
48 
49 
50 // <summary>A Gaussian model for the spatial distribution of emission</summary>
51 
52 // <use visibility=export>
53 
54 // <reviewed reviewer="" date="yyyy/mm/dd" tests="tGaussianShape" demos="dTwoSidedShape">
55 // </reviewed>
56 
57 // <prerequisite>
58 // <li> <linkto class=TwoSidedShape>TwoSidedShape</linkto>
59 // </prerequisite>
60 
61 // <synopsis>
62 
63 // A GaussianShape models the spatial distribution of radiation from the sky as
64 // a two-dimensional Gaussian function with user specified major axis width,
65 // minor axis width and position angle.
66 
67 // This class like the other component shapes becomes more useful when used
68 // through the <linkto class=SkyComponent>SkyComponent</linkto> class, which
69 // incorperates the flux and spectral variation of the emission, or through the
70 // <linkto class=ComponentList>ComponentList</linkto> class, which handles
71 // groups of SkyComponent objects.
72 
73 // The reference direction is defined in celestial co-ordinates, using a
74 // <linkto class=casacore::MDirection>MDirection</linkto> object. It indicates where the
75 // centre of the Gaussian is on the sky. The direction can be specified both in
76 // the constructor or with the <src>setRefDirection</src> function.
77 
78 // The width of the Gaussian is defined as the angle subtended by the full
79 // width at half maximum of the Gaussian. The major axis has the larger width
80 // and is aligned North-South when the position angle is zero. A positive
81 // position angle moves the Northern side of the component to the East. The
82 // axial ratio is the ratio of the minor to major axis widths. The major axis
83 // MUST not be smaller than the minor axis otherwise an exception (casacore::AipsError)
84 // is thrown.
85 
86 // These parameters of the Gaussian (width, position angle, direction etc.) can
87 // be specified at construction time, using the <src>*inRad</src> functions or
88 // through functions in the base classes (TwoSidedShape & ComponentShape). The
89 // base classes also implement functions for inter-converting this object into
90 // a record representation.
91 
92 // The flux, or integrated intensity, is always normalised to one. This class
93 // does not model the actual flux or its variation with frequency. It solely
94 // models the way the emission varies with position on the sky.
95 
96 // The <src>scale</src> member function is used to sample the component at any
97 // point on the sky. The scale factor calculated by this function is the
98 // proportion of the flux that is within a specified pixel size centered on the
99 // specified direction. Ultimatly this function will integrate the emission
100 // from the Gaussian over the entire pixel but currently it just assumes the
101 // flux can be calculated by the height of the Gaussian at the centre of the
102 // pixel scaled by the pixel area. This is <em>NOT</em> accurate for Gaussians
103 // whose width is small compared with the pixel size.
104 
105 // This class contains functions that return the Fourier transform of the
106 // component at a specified spatial frequency. There are described more fully
107 // in the description of the <src>visibility</src> functions below.
108 // </synopsis>
109 
110 // <example>
111 // Suppose I had an image of a region of the sky and we wanted to subtract
112 // a extended source from it. This could be done as follows:
113 // <ul>
114 // <li> Construct a SkyComponent with a Gaussian of width that is similar to
115 // the extended source.
116 // <li> Project the component onto an image
117 // <li> Convolve the image by the point spread function
118 // <li> subtract the convolved model from the dirty image.
119 // </ul>
120 // Shown below is the code to perform the first step in this process, ie
121 // construct the SkyComponent. This example is also available in the
122 // <src>dTwoSidedShape.cc</src> file. Note that it is more accurate to do
123 // subtraction of components in the (u,v) domain.
124 // <srcblock>
125 // { // Construct a Gaussian shape
126 // casacore::MDirection blob_dir;
127 // { // get the right direction into blob_dir
128 // casacore::Quantity blob_ra; casacore::MVAngle::read(blob_ra, "19:39:");
129 // casacore::Quantity blob_dec; casacore::MVAngle::read(blob_dec, "-63.43.");
130 // blob_dir = casacore::MDirection(blob_ra, blob_dec, casacore::MDirection::J2000);
131 // }
132 // {
133 // const Flux<casacore::Double> flux(6.28, 0.1, 0.15, 0.01);
134 // const GaussianShape shape(blob_dir,
135 // casacore::Quantity(30, "arcmin"),
136 // casacore::Quantity(2000, "mas"),
137 // casacore::Quantity(C::pi_2, "rad"));
138 // const ConstantSpectrum spectrum;
139 // SkyComponent component(flux, shape, spectrum);
140 // printShape(shape);
141 // }
142 // }
143 // </srcblock>
144 // The printShape function is the example shown for the TwoSidedShape class.
145 // </example>
146 //
147 // <todo asof="1999/11/12">
148 // <li> Use Measures & Quanta in the interface to the visibility functions.
149 // <li> Use a better way of integrating over the pixel area in the sample
150 // function.
151 // </todo>
152 
153 // <linkfrom anchor="GaussianShape" classes="ComponentShape TwoSidedShape PointShape DiskShape">
154 // <here>GaussianShape</here> - a Gaussian variation in the sky brightness
155 // </linkfrom>
156 
157 
159 {
160 public:
161  // The default GaussianShape is at the J2000 North Pole. with a full width at
162  // half maximum (FWHM) on both axes of 1 arc-min.
163  GaussianShape();
164 
165  // Construct a Gaussian shape centred in the specified direction, specifying
166  // the widths & position angle.
167  // <group>
168  GaussianShape(const casacore::MDirection& direction,
174  const casacore::Quantum<casacore::Double>& positionAngle);
175  // </group>
176 
177  // The copy constructor uses copy semantics.
178  GaussianShape(const GaussianShape& other);
179 
180  // The destructor does nothing special.
181  virtual ~GaussianShape();
182 
183  // The assignment operator uses copy semantics.
184  GaussianShape& operator=(const GaussianShape& other);
185 
186  // get the type of the shape. This function always returns
187  // ComponentType::GAUSSIAN.
188  virtual ComponentType::Shape type() const;
189 
190  // set or return the width and orientation of the Gaussian. All numerical
191  // values are in radians. There are also functions in the base class for
192  // doing this with other angular units.
193  // <group>
194  virtual void setWidthInRad(const casacore::Double majorAxis,
195  const casacore::Double minorAxis,
196  const casacore::Double positionAngle);
197  virtual casacore::Double majorAxisInRad() const;
198  virtual casacore::Double minorAxisInRad() const;
199  virtual casacore::Double positionAngleInRad() const;
200  virtual casacore::Double axialRatio() const;
201  // </group>
202 
203  // Calculate the proportion of the flux that is in a pixel of specified size
204  // centered in the specified direction. The returned value will always be
205  // between zero and one (inclusive).
206  virtual casacore::Double sample(const casacore::MDirection& direction,
207  const casacore::MVAngle& pixelLatSize,
208  const casacore::MVAngle& pixelLongSize) const;
209 
210  // Same as the previous function except that many directions can be sampled
211  // at once. The reference frame and pixel size must be the same for all the
212  // specified directions.
213  virtual void sample(casacore::Vector<casacore::Double>& scale,
215  const casacore::MDirection::Ref& refFrame,
216  const casacore::MVAngle& pixelLatSize,
217  const casacore::MVAngle& pixelLongSize) const;
218 
219  // Return the Fourier transform of the component at the specified point in
220  // the spatial frequency domain. The point is specified by a 3 element vector
221  // (u,v,w) that has units of meters and the frequency of the observation, in
222  // Hertz. These two quantities can be used to derive the required spatial
223  // frequency <src>(s = uvw*freq/c)</src>. The w component is not used in
224  // these functions.
225 
226  // The reference position for the transform is the direction of the
227  // component. As this component is symmetric about this point the transform
228  // is always a real value.
230  const casacore::Double& frequency) const;
231 
232  // Same as the previous function except that many (u,v,w) points can be
233  // sampled at once. The uvw casacore::Matrix must have a first dimension of three, and
234  // a second dimension that is the same as the length of the scale
235  // Vector. Otherwise and exception is thrown (when compiled in debug mode).
237  const casacore::Double& frequency) const;
238 
239  // as above but with many frequencies
241  const casacore::Vector<casacore::Double>& frequency) const;
242 
243  // Return a pointer to a copy of this object upcast to a ComponentShape
244  // object. The class that uses this function is responsible for deleting the
245  // pointer. This is used to implement a virtual copy constructor.
246  virtual ComponentShape* clone() const;
247 
248  // casacore::Function which checks the internal data of this class for correct
249  // dimensionality and consistent values. Returns true if everything is fine
250  // otherwise returns false.
251  virtual casacore::Bool ok() const;
252 
253  // return a pointer to this object.
254  virtual const ComponentShape* getPtr() const;
255 
256  // TODO This probably should be made a pure virtual method in TwoSidedShape
257  // Return the effective area of the Gaussian (pi/(4*ln(2))*maj*min.
258  // Units of the returned casacore::Quantity are steradians.
259  virtual casacore::Quantity getArea() const;
260 
261  virtual casacore::String sizeToString() const;
262 
263 private:
264  //# Updates the parameters of the itsFT object
265  void updateFT();
266  //# A generic Gaussian function
268  //# The FT of a Gaussian is also a Gaussian. Its parameters are stored here
270 };
271 
272 } //# NAMESPACE CASA - END
273 
274 #endif
A Measure: astronomical direction.
Definition: MDirection.h:174
std::vector< double > Vector
Definition: ds9context.h:24
Base class for component shapes with two sides.
virtual casacore::Double positionAngleInRad() const
virtual const ComponentShape * getPtr() const
return a pointer to this object.
virtual ComponentType::Shape type() const
get the type of the shape.
Shape
The shapes of all the components.
virtual casacore::String sizeToString() const
Get the string containing the various size quantities of a component.
virtual casacore::Double sample(const casacore::MDirection &direction, const casacore::MVAngle &pixelLatSize, const casacore::MVAngle &pixelLongSize) const
Calculate the proportion of the flux that is in a pixel of specified size centered in the specified d...
casacore::Quantum< casacore::Double > minorAxis() const
GaussianShape & operator=(const GaussianShape &other)
The assignment operator uses copy semantics.
virtual casacore::DComplex visibility(const casacore::Vector< casacore::Double > &uvw, const casacore::Double &frequency) const
Return the Fourier transform of the component at the specified point in the spatial frequency domain...
Base class for component shapes.
double Double
Definition: aipstype.h:55
virtual ~GaussianShape()
The destructor does nothing special.
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
virtual void setWidthInRad(const casacore::Double majorAxis, const casacore::Double minorAxis, const casacore::Double positionAngle)
set or return the width and orientation of the Gaussian.
casacore::Gaussian2D< casacore::Double > itsShape
virtual ComponentShape * clone() const
Return a pointer to a copy of this object upcast to a ComponentShape object.
virtual casacore::Double axialRatio() const
virtual casacore::Double minorAxisInRad() const
casacore::Quantum< casacore::Double > positionAngle() const
casacore::Gaussian2D< casacore::Double > itsFT
String: the storage and methods of handling collections of characters.
Definition: String.h:223
virtual casacore::Quantity getArea() const
TODO This probably should be made a pure virtual method in TwoSidedShape Return the effective area of...
virtual casacore::Double majorAxisInRad() const
GaussianShape()
The default GaussianShape is at the J2000 North Pole.
casacore::Quantum< casacore::Double > majorAxis() const
A Gaussian model for the spatial distribution of emission.
virtual casacore::Bool ok() const
casacore::Function which checks the internal data of this class for correct dimensionality and consis...
Class to handle angle type conversions and I/O.
Definition: MVAngle.h:245
#define casacore
&lt;X11/Intrinsic.h&gt; #defines true, false, casacore::Bool, and String.
Definition: X11Intrinsic.h:42