casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
PointShape.h
Go to the documentation of this file.
00001 //# PointShape.h:
00002 //# Copyright (C) 1998,1999,2000,2001
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //#
00027 //# $Id: PointShape.h 21130 2011-10-18 07:39:05Z gervandiepen $
00028 
00029 #ifndef COMPONENTS_POINTSHAPE_H
00030 #define COMPONENTS_POINTSHAPE_H
00031 
00032 #include <casa/aips.h>
00033 #include <components/ComponentModels/ComponentShape.h>
00034 #include <components/ComponentModels/ComponentType.h>
00035 #include <casa/BasicSL/Complex.h>
00036 
00037 namespace casa { //# NAMESPACE CASA - BEGIN
00038 
00039 class MVAngle;
00040 class MDirection;
00041 class RecordInterface;
00042 class String;
00043 template <class T> class Vector;
00044 
00045 // <summary>A shape where emission comes from only one direction</summary>
00046 
00047 // <use visibility=export> 
00048 
00049 // <reviewed reviewer="" date="yyyy/mm/dd" tests="tPointShape" demos="dPointShape">
00050 // </reviewed>
00051 
00052 // <prerequisite>
00053 //   <li> <linkto class=ComponentShape>ComponentShape</linkto>
00054 // </prerequisite>
00055 
00056 // <synopsis> 
00057 
00058 // This class represents the shape of components where the emission comes from
00059 // only one point in the sky. 
00060 
00061 // This class like the other component shapes becomes more useful when used
00062 // through the <linkto class=SkyComponent>SkyComponent</linkto> class, which
00063 // incorporates the flux and spectral variation of the emission, or through the
00064 // <linkto class=ComponentList>ComponentList</linkto> class, which handles
00065 // groups of SkyComponent objects.
00066 
00067 // For a point shape all the emission comes only from the reference direction
00068 // which is specified in celestial co-ordinates, using a 
00069 // <linkto class=MDirection>MDirection</linkto> object.  The direction can be
00070 // specified both in the constructor or with the <src>setRefDirection</src>
00071 // function.
00072 
00073 // The <src>sample</src> member functions are used to determine the proportion
00074 // of flux the component at any point on the sky. For a point component this is
00075 // either zero or one depending on whether the specified pixel contains the
00076 // point source or not.
00077 
00078 // The <src>visibility</src> functions return the Fourier transform of the
00079 // component at a specified spatial frequency. For a point shape the Fourier
00080 // transform is a constant value. Hence these functions return one, regardless
00081 // of the input parameters.
00082 
00083 // This class also contains functions (<src>toRecord</src> &
00084 // <src>fromRecord</src>) which perform the conversion between Records and
00085 // PointShape objects. These functions define how a PointShape object is
00086 // represented in glish. The format of the record that is generated and
00087 // accepted by these functions is:
00088 // <srcblock>
00089 // c := [type = 'point',
00090 //       direction = [type = 'direction',
00091 //                    refer = 'j2000',
00092 //                    m0 = [value = 0, unit = 'deg']
00093 //                    m1 = [value = 0, unit = 'deg']
00094 //                   ]
00095 //      ]
00096 // </srcblock>
00097 // The direction field contains a record representation of a direction measure
00098 // and its format is defined in the Measures module. Its refer field defines
00099 // the reference frame for the direction and the m0 and m1 fields define the
00100 // latitude and longitude in that frame.
00101 // </synopsis>
00102 //
00103 
00104 // <example>
00105 // Suppose I had an image of a region of the sky and we wanted to subtract
00106 // a point source from it. This could be done as follows:
00107 // <ul> 
00108 // <li> Construct a SkyComponent with to represent the point source
00109 // <li> Project the component onto an image
00110 // <li> Convolve the image by the point spread function
00111 // <li> subtract the convolved model from the dirty image.
00112 // </ul>
00113 // Shown below is the code to perform the first step in this process, ie
00114 // construct the SkyComponent. This example is also available in the
00115 // <src>dPointShape.cc</src> file.  Note that it is more accurate to do
00116 // subtraction of point components in the (u,v) domain
00117 // <srcblock>
00118 //  MDirection J1934_dir;
00119 //  { // get the right direction into J1934_dir
00120 //    Quantity J1934_ra; MVAngle::read(J1934_ra, "19:39:");
00121 //    Quantity J1934_dec; MVAngle::read(J1934_dec, "-63.43.");
00122 //    J1934_dir = MDirection(J1934_ra, J1934_dec, MDirection::J2000);
00123 //  }
00124 //  { // One way to construct the SkyComponent
00125 //    SkyComponent J1934(ComponentType::POINT, ComponentType::CONSTANT_SPECTRUM);
00126 //    J1934.shape().setRefDirection(J1934_dir);
00127 //    J1934.flux() = Flux<Double>(6.28, 0.1, 0.15, 0.01);
00128 //    printShape(J1934.shape());
00129 //  }
00130 //  { // An alternative way to construct the SkyComponent
00131 //    const Flux<Double> flux(6.28, 0.1, 0.15, 0.01);
00132 //    const PointShape shape(J1934_dir);
00133 //    const ConstantSpectrum spectrum;
00134 //    SkyComponent component(flux, shape, spectrum);
00135 //    printShape(component.shape());
00136 //  }
00137 // </srcblock>
00138 // Note how the member functions of the PointShape class (the setDirection
00139 // function) are accessable through the shape function in the SkyComponent
00140 // class. The printShape function is the example shown for the ComponentShape
00141 // class.
00142 // </example>
00143 //
00144 // <todo asof="1999/11/11">
00145 //   <li> Use Measures & Quanta in the interface to the visibility functions.
00146 // </todo>
00147 
00148 // <linkfrom anchor="PointShape" classes="ComponentShape GaussianShape DiskShape">
00149 //  <here>PointShape</here> - a shape where emission comes from only one direction
00150 // </linkfrom>
00151 
00152 class PointShape: public ComponentShape
00153 {
00154 public:
00155   // The default PointShape is at the J2000 North Pole.
00156   PointShape();
00157   
00158   // Construct a point shape at the specified direction.
00159   PointShape(const MDirection& direction);
00160   
00161   // The copy constructor uses copy semantics.
00162   PointShape(const PointShape& other);
00163 
00164   // The destructor does nothing special.
00165   virtual ~PointShape();
00166 
00167   // The assignment operator uses copy semantics.
00168   PointShape& operator=(const PointShape& other);
00169 
00170   // Return the type of shape. This function always returns
00171   // ComponentType::POINT.
00172   virtual ComponentType::Shape type() const;
00173 
00174   // Calculate the proportion of the flux that is in a pixel of the specified
00175   // size centered on the specified direction. Because this is a point shape
00176   // the returned value is either zero or one.  It is one if the specified
00177   // direction is less than half a pixelSize away from the reference direction.
00178   virtual Double sample(const MDirection& direction, 
00179                         const MVAngle& pixelLatSize,
00180                         const MVAngle& pixelLongSize) const;
00181 
00182   // Same as the previous function except that many directions can be sampled
00183   // at once. The reference frame and pixel size must be the same for all the
00184   // specified directions. This is a customised version.
00185   virtual void sample(Vector<Double>& scale, 
00186                       const Vector<MDirection::MVType>& directions, 
00187                       const MDirection::Ref& refFrame, 
00188                       const MVAngle& pixelLatSize,
00189                       const MVAngle& pixelLongSize) const;
00190 
00191   // Return the Fourier transform of the component at the specified point in
00192   // the spatial frequency domain. The point is specified by a 3 element vector
00193   // (u,v,w) that has units of meters and the frequency of the observation, in
00194   // Hertz. These two quantities can be used to derive the required spatial
00195   // frequency <src>(s = uvw*freq/c)</src>. The w component is not used in
00196   // these functions.
00197 
00198   // The reference position for the transform is the direction of the
00199   // component. Hence the returned value is always a constant real value of
00200   // one.  The input arguments are ignored except in debug mode where the
00201   // length of the uvw Vector and sign of the frequency variable are checked.
00202   virtual DComplex visibility(const Vector<Double>& uvw,
00203                               const Double& frequency) const;
00204 
00205   // Same as the previous function except that many (u,v,w) points can be
00206   // sampled at once. As with the previous function the returned value is
00207   // always a constant real vector of one.  The input arguments are ignored
00208   // except in debug mode where the shape of the uvw Matrix and the scale
00209   // Vector are checked as is the  sign of the frequency variable.
00210   virtual void visibility(Vector<DComplex>& scale, const Matrix<Double>& uvw,
00211                           const Double& frequency) const;
00212 
00213   //Same as above except with many frequencies
00214   virtual void visibility(Matrix<DComplex>& scale, const Matrix<Double>& uvw,
00215                           const Vector<Double>& frequency) const;
00216 
00217   // A point shape is symmetric so this function always returns True;
00218   virtual Bool isSymmetric() const;
00219 
00220   // Return a pointer to a copy of this object upcast to a ComponentShape
00221   // object. The class that uses this function is responsible for deleting the
00222   // pointer. This is used to implement a virtual copy constructor.
00223   virtual ComponentShape* clone() const;
00224 
00225   // return the number of parameters in this shape and set/get them.  As this
00226   // is a point shape there are none. So calling <src>setParameters</src> or
00227   // <src>setErrors</src> with anything other than a zero length Vector will
00228   // throw an exception (when compiled in debug mode). The
00229   // <src>nParameters</src> will always return zero and the
00230   // <src>parameters</src> and <src>errors</src> functions will always return
00231   // zero length Vectors.
00232   // <group>
00233   virtual uInt nParameters() const;
00234   virtual void setParameters(const Vector<Double>& newParms);
00235   virtual Vector<Double> parameters() const;
00236   virtual void setErrors(const Vector<Double>& newParms);
00237   virtual Vector<Double> errors() const;
00238   virtual Vector<Double> optParameters() const;
00239   virtual void setOptParameters(const Vector<Double>& newOptParms);
00240   // </group>
00241 
00242   // This functions convert between a Record and a PointShape. These functions
00243   // define how a point shape is represented in glish and this is detailed in
00244   // the synopsis above.  They return False if the supplied Record is malformed
00245   // and append an error message to the supplied String giving the reason.
00246   // <group>
00247   virtual Bool fromRecord(String& errorMessage,
00248                           const RecordInterface& record);
00249   virtual Bool toRecord(String& errorMessage, RecordInterface& record) const;
00250   // </group>
00251 
00252   // Convert the parameters of the component to the specified units. As a point
00253   // component has no parameters this function does nothing and always returns
00254   // True.
00255   virtual Bool convertUnit(String&, const RecordInterface&);
00256 
00257 
00258 
00259   // Function which checks the internal data of this class for consistent
00260   // values. Returns True if everything is fine otherwise returns False.
00261   virtual Bool ok() const;
00262 
00263   // return a pointer to this object.
00264   virtual const ComponentShape* getPtr() const; 
00265 
00266   virtual String sizeToString() const;
00267 
00268 private:
00269 
00270 // FInd out if a direction is located within a pixel 
00271    Double dirIsInPixel (Double longSize, Double latSize, Double nearSize,
00272                                     const MDirection::MVType& dirValue,
00273                                     const MDirection::MVType* compDirValue) const;
00274 };
00275 
00276 } //# NAMESPACE CASA - END
00277 
00278 #endif